### Install Default Configuration File

Source: https://github.com/hyprwm/hyprlock/blob/main/CMakeLists.txt

Installs the example configuration file, renaming it to hyprlock.conf in the data root directory.

```cmake
install(
  FILES ${CMAKE_SOURCE_DIR}/assets/example.conf
  DESTINATION ${CMAKE_INSTALL_FULL_DATAROOTDIR}/hypr
  RENAME hyprlock.conf)
```

--------------------------------

### Install Hyprlock Executable

Source: https://github.com/hyprwm/hyprlock/blob/main/CMakeLists.txt

Installs the main Hyprlock executable to the system.

```cmake
install(TARGETS hyprlock)
```

--------------------------------

### Install hyprlock using Yay

Source: https://github.com/hyprwm/hyprlock/blob/main/README.md

Compile and install hyprlock from the latest source using the yay AUR helper.

```sh
yay -S hyprlock-git # compiles from latest source
```

--------------------------------

### Install hyprlock using Pacman

Source: https://github.com/hyprwm/hyprlock/blob/main/README.md

Install the binary release of hyprlock using the pacman package manager.

```sh
pacman -S hyprlock # binary x86 tagged release
```

--------------------------------

### Install PAM Configuration

Source: https://github.com/hyprwm/hyprlock/blob/main/CMakeLists.txt

Installs the PAM configuration file for Hyprlock to the system's PAM configuration directory.

```cmake
install(FILES ${CMAKE_SOURCE_DIR}/pam/hyprlock
        DESTINATION ${CMAKE_INSTALL_FULL_SYSCONFDIR}/pam.d)
```

--------------------------------

### Initialize and Run CHyprlock Application

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Connects to Wayland, initializes EGL, and sets the session grace period. The run() method starts the main blocking event loop.

```cpp
#include "core/hyprlock.hpp"

// Construction: connects to Wayland, initializes EGL, sets grace period.
// wlDisplay: Wayland socket name or "" for WAYLAND_DISPLAY env var.
// immediateRender: don't wait for screencopy frames before showing lock surface.
// gracePeriod: seconds before authentication is enforced (0 = immediate).
auto hyprlock = std::make_unique<CHyprlock>("", /*immediateRender=*/false, /*gracePeriod=*/0);

// Main blocking event loop — returns when the session is unlocked.
hyprlock->run();
```

--------------------------------

### Install hyprlock after building

Source: https://github.com/hyprwm/hyprlock/blob/main/README.md

Install hyprlock to the system after it has been built using CMake.

```sh
sudo cmake --install build
```

--------------------------------

### Build Hyprlock on Arch Linux

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Install dependencies using pacman, configure the build with CMake for release or debug, and build the target. Includes instructions for system-wide installation.

```sh
# --- Dependencies (Arch Linux) ---
sudo pacman -S cairo hyprlang hyprutils hyprwayland-scanner mesa pam pango \
               sdbus-cpp wayland wayland-protocols libxkbcommon libdrm \
               gbm hyprgraphics

# --- Configure (Release build) ---
cmake --no-warn-unused-cli \
      -DCMAKE_BUILD_TYPE:STRING=Release \
      -S . \
      -B ./build

# --- Build (parallel, all cores) ---
cmake --build ./build \
      --config Release \
      --target hyprlock \
      -j$(nproc 2>/dev/null || getconf _NPROCESSORS_CONF)

# --- Install (system-wide) ---
sudo cmake --install build
# Installs:
#   /usr/local/bin/hyprlock
#   /etc/pam.d/hyprlock
#   /usr/local/share/hypr/hyprlock.conf  (example config)

# --- Debug build ---
cmake --no-warn-unused-cli \
      -DCMAKE_BUILD_TYPE:STRING=Debug \
      -DHYPRLOCK_COMMIT="$(git rev-parse --short HEAD)" \
      -S . -B ./build-debug
cmake --build ./build-debug --target hyprlock -j$(nproc)

# --- Nix flake ---
nix build .#hyprlock
nix run .#hyprlock -- --config ./assets/example.conf
```

--------------------------------

### Complete Hyprlock Configuration Example

Source: https://context7.com/hyprwm/hyprlock/llms.txt

This configuration demonstrates all widget types available in hyprlock, including background blur, overlays, user avatars, input fields, and dynamic labels for time, date, and keyboard layout. It is intended for users who want a fully featured lock screen.

```ini
# ~/.config/hypr/hyprlock.conf
$font = JetBrains Mono

general {
    hide_cursor        = true
    ignore_empty_input = true
    fail_timeout       = 3000
}

auth {
    pam { enabled = true; module = hyprlock }
    fingerprint {
        enabled         = true
        ready_message   = Touch sensor to unlock
        present_message = Scanning...
        retry_delay     = 300
    }
}

animations {
    enabled  = true
    bezier   = smooth, 0.16, 1, 0.3, 1
    animation = fadeIn,          1, 4, smooth
    animation = fadeOut,         1, 4, smooth
    animation = inputFieldDots,  1, 2, smooth
    animation = inputFieldColors,1, 6, smooth
}

# Blurred screenshot background on all monitors
background {
    monitor      = 
    path         = screenshot
    blur_passes  = 3
    blur_size    = 8
    brightness   = 0.75
    contrast     = 0.9
    noise        = 0.012
    vibrancy     = 0.15
    crossfade_time = 0.3
}

# Dark overlay card behind the input field
shape {
    monitor  = 
    size     = 450, 300
    rounding = 20
    color    = rgba(0, 0, 0, 0.55)
    position = 0, -40
    halign   = center
    valign   = center
    zindex   = -1
}

# User avatar
image {
    monitor      = 
    path         = ~/.face
    size         = 100
    rounding     = -1
    border_size  = 3
    border_color = rgba(33ccffee) rgba(00ff99ee) 45deg
    position     = 0, 100
    halign       = center
    valign       = center
}

# Password input field
input-field {
    monitor           = 
    size              = 380, 55
    outline_thickness = 3
    inner_color       = rgba(0, 0, 0, 0.3)
    outer_color       = rgba(51, 204, 255, 0.9) rgba(0, 255, 153, 0.9) 45deg
    check_color       = rgba(0, 255, 153, 0.9) rgba(255, 102, 51, 0.9) 120deg
    fail_color        = rgba(255, 0, 102, 0.9)
    capslock_color    = rgba(255, 170, 0, 0.9)
    font_color        = rgb(220, 220, 220)
    font_family       = $font
    rounding          = 12
    placeholder_text  = <i>Password...</i>
    fail_text         = $PAMFAIL
    check_text        = Authenticating...
    dots_spacing      = 0.25
    dots_size         = 0.3
    fade_on_empty     = true
    fade_timeout      = 5000
    position          = 0, -20
    halign            = center
    valign            = center
    shadow_passes     = 2
    shadow_size       = 5
}

# Clock
label {
    monitor    = 
    text       = $TIME
    font_size  = 80
    font_family = $font
    color      = rgba(255, 255, 255, 0.9)
    position   = -30, 0
    halign     = right
    valign     = top
    shadow_passes = 1
    shadow_size   = 3
}

# Date
label {
    monitor    = 
    text       = cmd[update:60000] date +"%A, %d %B %Y"
    font_size  = 22
    font_family = $font
    color      = rgba(200, 200, 200, 0.8)
    position   = -30, -110
    halign     = right
    valign     = top
}

# Keyboard layout indicator
label {
    monitor    = 
    text       = $LAYOUT[EN, RU, DE]
    font_size  = 14
    font_family = $font
    color      = rgba(150, 150, 150, 0.7)
    position   = 0, -95
    halign     = center
    valign     = center
    onclick    = hyprctl switchxkblayout all next
}

```

--------------------------------

### Manage Authentication Backends with CAuth

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Use CAuth to coordinate multiple authentication backends. Start all backends with `start()`, submit user input with `submitInput()`, and check if authentication is in progress using `checkWaiting()`. Retrieve failure messages and prompts from individual backends as needed.

```cpp
#include "auth/Auth.hpp"

// Construction: reads auth config, instantiates enabled implementations
// g_pAuth is the global singleton, created in CHyprlock::run()
// auto auth = std::make_unique<CAuth>();

// Start all authentication backends
g_pAuth->start();
// CPam::init() spawns its thread; CFingerprint::init() opens D-Bus connections.

// Submit typed password from keyboard handler
// Called when the user presses Enter. Distributes to all IAuthImplementation instances.
g_pAuth->submitInput("hunter2");

// Check if any backend is currently processing (blocks new input)
bool waiting = g_pAuth->checkWaiting(); // true = PAM/fingerprint in progress

// Get the current fail display text (set after a failed attempt)
const std::string& failText = g_pAuth->getCurrentFailText();
// e.g. "Sorry, your password didn't work. 2 attempts remaining."

// Get fail text per backend
std::optional<std::string> pamFail = g_pAuth->getFailText(AUTH_IMPL_PAM);
std::optional<std::string> fpFail  = g_pAuth->getFailText(AUTH_IMPL_FINGERPRINT);

// Get current PAM prompt (e.g. "Password:" or "OTP:")
std::optional<std::string> prompt = g_pAuth->getPrompt(AUTH_IMPL_PAM);

// Number of failed attempts since last successful auth
size_t attempts = g_pAuth->getFailedAttempts(); // e.g. 3

// Direct access to an implementation
SP<IAuthImplementation> pamImpl = g_pAuth->getImpl(AUTH_IMPL_PAM);
SP<IAuthImplementation> fpImpl  = g_pAuth->getImpl(AUTH_IMPL_FINGERPRINT);

// Schedule unlock (bypasses password check — used after successful auth or SIGUSR1)
// Adds a 0ms timer that calls g_pHyprlock->fadeOutAndUnlock() on the main thread.
g_pAuth->enqueueUnlock();

// Report a failure from an auth backend (called internally by CPam / CFingerprint)
// Sets m_bDisplayFailText = true after a 0ms timer, schedules reset after fail_timeout ms.
g_pAuth->enqueueFail("Wrong password (3 attempts left)", AUTH_IMPL_PAM);

// Reset the displayed fail state on next keypress
g_pAuth->resetDisplayFail();
bool showing = g_pAuth->m_bDisplayFailText; // true while fail text is visible

// Terminate all backends (called on shutdown)
g_pAuth->terminate();
```

--------------------------------

### Pango Markup for Text Formatting

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Use Pango markup within the 'text' property to apply rich formatting like bold, italics, and color to labels. Ensure Pango is installed for this to work.

```ini
label {
    monitor =
    text      = <b>Hello,</b> <i>world!</i> <span foreground='#ff0000'>red</span>
    font_size  = 20
    font_family = Sans
    position   = 0, 100
    halign     = center
    valign     = center
}
```

--------------------------------

### Disable startup fade-in animation

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Disables the fade-in animation that occurs when hyprlock starts.

```sh
hyprlock --no-fade-in
```

--------------------------------

### Control global fade animation with CRenderer

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Manages the global opacity animation for the lock screen. Provides functions to start fade-in, fade-out (optionally unlocking), and to instantly set the opacity.

```cpp
// Global fade animation
g_pRenderer->startFadeIn();          // animate opacity 0→1 on lock
g_pRenderer->startFadeOut(/*unlock=*/true); // animate opacity 1→0, then unlock
g_pRenderer->warpOpacity(1.0f);      // instantly set opacity (no animation)

```

--------------------------------

### Connect to specific Wayland display

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Specifies the Wayland display socket to connect to. Useful in multi-display or complex Wayland setups.

```sh
hyprlock --display wayland-1
```

--------------------------------

### Specify configuration file

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Launches hyprlock using a custom configuration file. The short flag `-c` is also available.

```sh
hyprlock --config ~/.config/hypr/hyprlock.conf
```

```sh
hyprlock -c ~/.config/hypr/hyprlock.conf
```

--------------------------------

### Include Configuration Files

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Use the 'source' directive to include other configuration files. Supports tilde expansion, glob patterns, and nested sourcing.

```ini
# Include a single file
source = ~/.config/hypr/hyprlock-colors.conf
```

```ini
# Glob: include all .conf files in a directory
source = ~/.config/hypr/hyprlock.d/*.conf
```

```ini
# Nested source (relative to the including file's directory)
source = ./theme.conf
```

--------------------------------

### Lock screen immediately

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Launches hyprlock with the default configuration. Use this for a quick screen lock.

```sh
hyprlock
```

--------------------------------

### Initialize Configuration Manager

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Initializes the CConfigManager after resolving the configuration path. This step registers all known keys and parses the configuration file.

```cpp
// --- Construction & initialization ---
auto cfg = std::make_unique<CConfigManager>(result.value().c_str());
cfg->init(); // registers all keys, parses the file
```

--------------------------------

### Configure Background with Blurred Screenshot in Hyprlock

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Set up a background using a blurred screenshot or a static image file. Supports dynamic reloading and per-monitor configurations. Ensure 'path' is set to 'screenshot' for dynamic capture or provide a valid file path.

```ini
# Full-featured background with blurred screenshot
background {
    # Target monitor (port name or description prefix). Empty = all monitors.
    monitor =

    # "screenshot" captures the current screen via screencopy, or provide a file path.
    # Supports ~/ and environment variable expansion.
    path = screenshot
    # path = ~/Pictures/wallpaper.png
    # path = /usr/share/wallpapers/hyprlock-bg.jpg

    # Fallback solid color when no image is set (ARGB hex). Default: 0xFF111111
    color = rgba(17, 17, 17, 1.0)

    # Blur kernel radius (pixels). Default: 8
    blur_size = 8

    # Number of blur passes (0 = no blur). Default: 0
    blur_passes = 3

    # Post-process parameters (all 0.0–1.0 floats)
    noise             = 0.0117
    contrast          = 0.8917
    brightness        = 0.8172
    vibrancy          = 0.1686
    vibrancy_darkness = 0.05

    # Z-order (default: -1 = behind everything)
    zindex = -1

    # Dynamic reload: seconds between reloads (-1 = disabled)
    reload_time = 300
    # Shell command whose stdout is used as the new image path
    reload_cmd  = echo ~/Pictures/$(date +%A).png

    # Duration (seconds) of the crossfade between old and new image on reload
    # -1.0 uses the fadeIn animation config
    crossfade_time = 0.5
}

# Per-monitor override: darker background on secondary monitor
background {
    monitor = HDMI-A-1
    path    = screenshot
    blur_passes = 1
    brightness  = 0.5
}
```

--------------------------------

### Execute Shell Commands

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Use `spawnSync` for blocking command execution and capturing stdout, suitable for dynamic labels. Use `spawnAsync` for fire-and-forget commands in non-blocking contexts like onclick handlers.

```cpp
#include "helpers/MiscFunctions.hpp"

// --- spawnSync: run a command and capture stdout (blocking) ---
// Used for cmd[] label text and image reload_cmd.
std::string output = spawnSync("date +\"%A, %d %B %Y\"");
// output = "Monday, 06 January 2025\n"
// Note: trailing newlines are preserved; strip with trim() if needed.
```

```cpp
std::string wallpaperPath = spawnSync("echo ~/Pictures/wallpaper.png");
// wallpaperPath = "/home/alice/Pictures/wallpaper.png\n"
```

```cpp
// Error handling: returns empty string if the command fails or produces no output.
std::string bad = spawnSync("nonexistent_command_xyz");
// bad = ""
```

```cpp
// --- spawnAsync: fire-and-forget command (non-blocking) ---
// Used for onclick handlers.
spawnAsync("hyprctl switchxkblayout all next");
spawnAsync("notify-send 'Locked!' 'Screen is now locked'");
spawnAsync("playerctl pause");
```

--------------------------------

### Format String with Variables and Commands

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Use `IWidget::formatString` to substitute built-in variables like time and layout, execute shell commands, and preserve Pango markup. The result includes formatted text and update metadata.

```cpp
#include "renderer/widgets/IWidget.hpp"

// --- $TIME substitution ---
auto r1 = IWidget::formatString("$TIME");
// r1.formatted    = "14:30"   (current HH:MM)
// r1.updateEveryMs = 1000     (update every second)
// r1.alwaysUpdate  = false
```

```cpp
// --- $LAYOUT substitution ---
// The fallback array provides display names for each xkb layout index.
// If the active layout index is 0, shows "en"; index 1 shows "ru".
auto r2 = IWidget::formatString("$LAYOUT[en,ru]");
// r2.formatted    = "en"  (or whichever layout is active)
// r2.alwaysUpdate = true  (re-evaluated on every layout change)
```

```cpp
// --- $PAMFAIL / $FAIL substitution ---
// Replaced with the current PAM failure text from g_pAuth.
auto r3 = IWidget::formatString("Error: $PAMFAIL");
// r3.formatted = "Error: Authentication failure"  (or "Error: " if no fail)
```

```cpp
// --- cmd[] substitution: shell command with optional periodic refresh ---
// Syntax: cmd[update:MILLISECONDS] SHELL_COMMAND
auto r4 = IWidget::formatString("cmd[update:60000] date +\"%A, %B %d\"");
// r4.formatted     = "Monday, January 06"  (result of running the shell command)
// r4.updateEveryMs = 60000
// r4.cmd           = true
```

```cpp
// One-shot command (no update interval)
auto r5 = IWidget::formatString("cmd[] whoami");
// r5.formatted     = "alice"
// r5.updateEveryMs = 0
// r5.cmd           = true
```

```cpp
// --- Pango markup passthrough ---
// Markup tags are preserved and passed to pango for rendering.
auto r6 = IWidget::formatString("<b>Hello</b> <span color='#ff0000'>World</span>");
// r6.formatted = "<b>Hello</b> <span color='#ff0000'>World</span>"
```

```cpp
// --- Combined example (label widget internal usage) ---
// labelPreFormat is the raw config string; formatString is called each timer tick:
std::string rawText = "cmd[update:1000] date +%H:%M:%S";
IWidget::SFormatResult result = IWidget::formatString(rawText);
if (result.updateEveryMs > 0) {
    // Plant a timer to re-call formatString after result.updateEveryMs ms
}
if (result.cmd) {
    // result.formatted is the command to run; actual text comes from its stdout
    std::string output = spawnSync(result.formatted);
}
```

--------------------------------

### Build hyprlock with CMake

Source: https://github.com/hyprwm/hyprlock/blob/main/README.md

Configure and build the hyprlock project using CMake. Ensure all dependencies are met before building.

```sh
cmake --no-warn-unused-cli -DCMAKE_BUILD_TYPE:STRING=Release -S . -B ./build
cmake --build ./build --config Release --target hyprlock -j`nproc 2>/dev/null || getconf _NPROCESSORS_CONF`
```

--------------------------------

### Retrieve Widget Configurations

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Retrieves all configured widget instances. The result is a vector of SWidgetConfig structs, sorted by zindex. Each struct contains the widget type, monitor, and a map of its specific values.

```cpp
// --- Retrieving all widget instance configs ---
// Returns a flat vector sorted by zindex. Each entry has:
//   .type    — "background" | "shape" | "image" | "input-field" | "label"
//   .monitor — monitor selector string
//   .values  — unordered_map<string, any> with all per-widget key values
std::vector<CConfigManager::SWidgetConfig> widgets = cfg->getWidgetConfigs();

for (auto& w : widgets) {
    std::println("Widget type={} monitor={}", w.type, w.monitor);
    if (w.type == "label") {
        auto text = std::any_cast<Hyprlang::STRING>(w.values.at("text"));
        std::println("  text = {}", text);
    }
    if (w.type == "background") {
        auto passes = std::any_cast<Hyprlang::INT>(w.values.at("blur_passes"));
        std::println("  blur_passes = {}", passes);
    }
}
```

--------------------------------

### Size and Position Syntax

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Specify size and position using absolute pixels or viewport percentages. Position is an offset from the anchor point defined by halign and valign.

```ini
# Absolute pixels: "W, H"
size     = 400, 90
position = -30, 0
```

```ini
# Percentage of the viewport dimension: "W%, H%"
size     = 20%, 5%
position = 0%, -2%
```

```ini
# Mixed
size = 400, 5%
```

--------------------------------

### CHyprlock Password Buffer and State Queries

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Provides methods to query the state of the password buffer, authentication progress, and the application's internal state like fading or termination.

```cpp
// --- Password buffer queries ---
size_t len        = g_pHyprlock->getPasswordBufferLen();        // actual char count
size_t displayLen = g_pHyprlock->getPasswordBufferDisplayLen(); // may differ with IME
bool   waiting    = g_pHyprlock->passwordCheckWaiting();        // PAM in progress
auto   failReason = g_pHyprlock->passwordLastFailReason();      // optional<string>

// --- State queries ---
bool fading      = g_pHyprlock->isFadingOutOrTerminating();
bool terminating = g_pHyprlock->isTerminating();
bool locked      = g_pHyprlock->isLockAquired();
```

--------------------------------

### Render background immediately

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Forces hyprlock to render the background immediately without waiting for screencopy frames. This can be useful for faster startup.

```sh
hyprlock --immediate-render
```

--------------------------------

### Create Keyboard Layout Indicator Label in Hyprlock

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Display the current keyboard layout using the $LAYOUT variable and allow switching layouts on click. The 'onclick' field executes a 'hyprctl' command to cycle through layouts.

```ini
# Keyboard layout indicator with click-to-switch
label {
    monitor =
    # $LAYOUT[fallback1, fallback2, ...] shows current xkb layout name
    text    = $LAYOUT[en, ru]
    font_size = 24
    position  = 250, -20
    halign    = center
    valign    = center
    # Run hyprctl command on click
    onclick   = hyprctl switchxkblayout all next
}
```

--------------------------------

### Reading Configuration Values from std::any Prop Map

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Demonstrates how to extract configuration values of different types (INT, FLOAT, STRING, custom types) from the `prop` map within a widget's `configure` method. Requires `std::any_cast` for basic types and specific helper functions for custom types like layout and gradient configurations.

```cpp
// INT values
    int blurPasses = std::any_cast<Hyprlang::INT>(prop.at("blur_passes"));

    // FLOAT values
    float noise = std::any_cast<Hyprlang::FLOAT>(prop.at("noise"));

    // STRING values
    std::string path = std::any_cast<Hyprlang::STRING>(prop.at("path"));

    // Custom LAYOUTCONFIG value (CLayoutValueData*)
    auto* layoutData = CLayoutValueData::fromAnyPv(prop.at("size"));
    Vector2D absoluteSize = layoutData->getAbsolute(viewport);

    // Custom GRADIENTCONFIG value (CGradientValueData*)
    auto* grad = CGradientValueData::fromAnyPv(prop.at("outer_color"));
    // grad->m_vColors[i] are CHyprColor values
    // grad->m_fAngle is the gradient angle in radians
    // grad->m_vColorsOkLabA contains OkLab+A packed floats for GPU upload
```

--------------------------------

### spawnSync / spawnAsync

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Utility functions for running shell commands. `spawnSync` blocks and captures stdout, while `spawnAsync` runs commands in the background.

```APIDOC
## `spawnSync` / `spawnAsync` — Shell Command Helpers

### Description
Utility functions for running shell commands, used by dynamic labels and reload commands.

### `spawnSync`

#### Description
Runs a command and captures its standard output. This function is blocking.

#### Usage Examples
```cpp
// Used for cmd[] label text and image reload_cmd.
std::string output = spawnSync("date +\"%A, %d %B %Y\"");
// output = "Monday, 06 January 2025\n"
// Note: trailing newlines are preserved; strip with trim() if needed.

std::string wallpaperPath = spawnSync("echo ~/Pictures/wallpaper.png");
// wallpaperPath = "/home/alice/Pictures/wallpaper.png\n"

// Error handling: returns empty string if the command fails or produces no output.
std::string bad = spawnSync("nonexistent_command_xyz");
// bad = ""
```

### `spawnAsync`

#### Description
Executes a command in a non-blocking, fire-and-forget manner.

#### Usage Examples
```cpp
// Used for onclick handlers.
spawnAsync("hyprctl switchxkblayout all next");
spawnAsync("notify-send 'Locked!' 'Screen is now locked'");
spawnAsync("playerctl pause");
```

### `getUsernameForCurrentUid`

#### Description
Gets the username associated with the current effective user ID.

#### Usage Example
```cpp
std::string username = getUsernameForCurrentUid();
// username = "alice"  (used by CPam for pam_start)
```

### `absolutePath`

#### Description
Resolves paths, including tilde expansion and relative path resolution against a base directory.

#### Usage Examples
```cpp
// second arg is the base directory for relative resolution
std::string p1 = absolutePath("~/Pictures/bg.png", "");
// p1 = "/home/alice/Pictures/bg.png"

std::string p2 = absolutePath("./theme.conf", "/home/alice/.config/hypr");
// p2 = "/home/alice/.config/hypr/theme.conf"
```
```

--------------------------------

### Create and Animate PHLANIMVAR Variables

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Creates animated variables (float, Vector2D, etc.) and interpolates them towards a goal value. Animations can be instantly warped to their goal value.

```cpp
// Create an animated variable and attach it to the animation tree node.
// VarType can be: float, Vector2D, CHyprColor, CGradientValueData
PHLANIMVAR<float> opacity;
auto config = g_pConfigManager->m_AnimationTree.getConfig("fadeIn");
g_pAnimationManager->createAnimation(/*initial=*/0.0f, opacity, config);

// Animate: set the goal value; the variable interpolates toward it each tick.
*opacity = 1.0f; // sets goal; actual value changes over time
float current = opacity->value(); // get current interpolated value

// Instant warp (no animation)
opacity->warp();  // snaps to current goal immediately

// Check if animation is in progress
bool running = !opacity->isBeingAnimated() == false;

// The animation tree hierarchy (from ConfigManager::init()):
// global
// ├── fade
// │   ├── fadeIn
// │   └── fadeOut
// └── inputField
//     ├── inputFieldColors
//     ├── inputFieldFade
//     ├── inputFieldWidth
//     └── inputFieldDots
```

--------------------------------

### PAM authentication configuration

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Enables and configures the Pluggable Authentication Modules (PAM) backend for hyprlock. Specify the PAM service module name.

```ini
auth {
    pam {
        # Enable PAM authentication. Default: true (1)
        enabled = true

        # PAM service module name (file in /etc/pam.d/). Default: "hyprlock"
        module = hyprlock
    }

    fingerprint {
        # Enable fingerprint via libfprint D-Bus. Default: false (0)
        enabled = true

        # Text shown on input-field placeholder when waiting for fingerprint scan
        ready_message = Scan fingerprint to unlock

        # Text shown when the sensor is actively scanning
        present_message = Scanning...

        # Milliseconds to wait between retries on a no-match. Default: 250
        retry_delay = 250
    }
}
```

--------------------------------

### Define and Assign Animations in Hyprlock

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Configure custom cubic bezier curves and assign them to animation slots like fade or input field animations. Ensure the 'enabled' switch is set to true to activate the animation system.

```ini
animations {
    # Master enable/disable switch. Default: true (1)
    enabled = true

    # Define a named cubic bezier: bezier = NAME, P1X, P1Y, P2X, P2Y
    # The control points are in the [0,1] range (CSS cubic-bezier convention).
    bezier = linear,  1,    1,    0,    0
    bezier = easeOut, 0.16, 1,    0.3,  1
    bezier = snap,    0.23, 1,    0.32, 1

    # Assign to animation slots:
    #   animation = SLOT, ENABLED(0|1), SPEED, BEZIER_NAME
    # Speed is a multiplier; higher = faster.
    # Available slots (hierarchical — child inherits parent):
    #   global
    #   ├── fade
    #   │   ├── fadeIn      (lock screen fade in on start)
    #   │   └── fadeOut     (lock screen fade out on unlock)
    #   └── inputField
    #       ├── inputFieldColors  (border color transitions)
    #       ├── inputFieldFade    (input field appear/disappear)
    #       ├── inputFieldWidth   (width changes)
    #       └── inputFieldDots    (dot count animation)
    animation = fadeIn,           1, 5,  linear
    animation = fadeOut,          1, 5,  linear
    animation = inputFieldDots,   1, 2,  linear
    animation = inputFieldColors, 1, 8,  easeOut
}
```

--------------------------------

### Utility Functions for User and Path

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Retrieve the current username using `getUsernameForCurrentUid` and resolve paths with `absolutePath`, which handles tilde expansion and relative paths based on a provided directory.

```cpp
// --- getUsernameForCurrentUid: get the username for the effective UID ---
std::string username = getUsernameForCurrentUid();
// username = "alice"  (used by CPam for pam_start)
```

```cpp
// --- absolutePath: resolve ~ and relative paths ---
// second arg is the base directory for relative resolution
std::string p1 = absolutePath("~/Pictures/bg.png", "");
// p1 = "/home/alice/Pictures/bg.png"

std::string p2 = absolutePath("./theme.conf", "/home/alice/.config/hypr");
// p2 = "/home/alice/.config/hypr/theme.conf"
```

--------------------------------

### Image Widget for Avatars and Reloading

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Display images with customizable size, rounding, and borders. Supports dynamic image paths via shell commands and periodic reloading from disk or command output.

```ini
image {
    monitor =

    # Path to the image file. Supports ~/ expansion.
    path = ~/Pictures/avatar.png
    # Dynamic path via shell command
    # path = cmd[update:3600000] echo ~/avatars/$(whoami).png

    # Rendered square size in pixels
    size = 150

    # Corner rounding (-1 = full circle, 0 = square, N = px radius)
    rounding = -1

    # Border width in pixels (0 = no border)
    border_size = 4

    # Border color (gradient supported)
    border_color = rgba(221, 221, 221, 1.0)
    # border_color = rgba(33ccffee) rgba(00ff99ee) 45deg

    position = 0, 200
    halign   = center
    valign   = center

    # Rotation in degrees
    rotate = 0

    # Reload image every N seconds from disk (-1 = disabled)
    reload_time = 3600
    # Shell command whose stdout is used as the new path (overrides disk check)
    reload_cmd  = echo ~/Pictures/avatar.png

    zindex = 0

    shadow_passes = 1
    shadow_size   = 6
    shadow_color  = rgba(0, 0, 0, 0.7)
    shadow_boost  = 1.2

    # Command to run on click
    onclick = xdg-open ~/
}
```

--------------------------------

### PAM Authentication Backend Flow with CPam

Source: https://context7.com/hyprwm/hyprlock/llms.txt

CPam implements the IAuthImplementation using POSIX PAM, running `pam_authenticate` in a separate thread. It interacts with the main thread via condition variables for input and state updates. Use `g_pAuth->submitInput()` to unblock the PAM thread and `g_pAuth->checkWaiting()` to monitor its status.

```cpp
// CPam runs automatically when g_pAuth->start() is called.
// The following shows the internal flow for understanding and integration:

// Conversation state (accessible via getLastPrompt / getLastFailText):
CPam::SPamConversationState state;
// state.prompt    — current PAM prompt text (e.g. "Password:", "OTP:")
// state.failText  — PAM failure message (e.g. from pam_faillock)
// state.waitingForPamAuth — true while pam_authenticate is blocking
// state.inputRequested    — true when PAM conv callback is waiting for input

// PAM module is configured via:
//   auth:pam:module = hyprlock   (→ /etc/pam.d/hyprlock)
// The conversation loop:
//   1. pam_start("hyprlock", username, &conv, &pamh)
//   2. pam_authenticate() → conv callback → waitForInput() blocks on CV
//   3. User types password → submitInput() → handleInput() notifies CV
//   4. pam_authenticate returns PAM_SUCCESS → enqueueUnlock()
//      or PAM_AUTH_ERR → enqueueFail(failText) → loop restarts

// Interacting through CAuth:
g_pAuth->submitInput("mypassword");          // unblocks the PAM CV
bool waiting = g_pAuth->checkWaiting();      // true while PAM is in pam_authenticate
auto prompt  = g_pAuth->getPrompt(AUTH_IMPL_PAM);   // "Password:" etc.
auto fail    = g_pAuth->getFailText(AUTH_IMPL_PAM);  // "Authentication failure"

// PAM config file example (/etc/pam.d/hyprlock):
// auth     include  system-auth
// account  include  system-auth
// password include  system-auth
// session  include  system-auth
```

--------------------------------

### Print version and exit

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Prints the version of hyprlock and exits. The short flag `-V` is also available.

```sh
hyprlock --version
```

```sh
hyprlock -V
```

--------------------------------

### Create Static Clock Label in Hyprlock

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Display a static clock using the built-in $TIME variable. Configure font, color, and position for the label. The 'text' field directly uses the variable for real-time updates.

```ini
# Static clock using built-in $TIME variable
label {
    monitor =
    text      = $TIME          # HH:MM format, updates every second
    font_size  = 90
    font_family = Monospace
    color      = rgba(255, 255, 255, 1.0)

    # Position is an offset from the anchor defined by halign/valign
    # Values can be absolute pixels or percentages: "50%, 10%"
    position = -30, 0
    halign   = right
    valign   = top

    # text_align: left | right | center (multi-line text alignment)
    text_align = right

    # Rotation in degrees (clockwise)
    rotate = 0

    # Z-order
    zindex = 0

    # Drop shadow
    shadow_passes = 2
    shadow_size   = 4
    shadow_color  = rgba(0, 0, 0, 0.8)
    shadow_boost  = 1.2

    # Shell command to run when this label is clicked
    onclick = 
}
```

--------------------------------

### IWidget Interface Definition

Source: https://context7.com/hyprwm/hyprlock/llms.txt

Defines the virtual interface for all Hyprlock widgets, including methods for configuration, drawing, and asset updates. Implemented by Background, Label, Image, PasswordInputField, and Shape widgets.

```cpp
class IWidget {
  public:
    struct SRenderData {
        float opacity = 1; // Global fade opacity [0.0, 1.0] from CRenderer
    };

    // Called once when the widget is constructed for an output.
    // `prop` maps config key names to std::any values (Hyprlang::INT/FLOAT/STRING or void* for custom types).
    virtual void configure(const std::unordered_map<std::string, std::any>& prop,
                           const SP<COutput>& pOutput) = 0;

    // Called every frame for this output. Return true if another frame is needed
    // (e.g., animation is in progress).
    virtual bool draw(const SRenderData& data) = 0;

    // Called from CAsyncResourceManager when an async-loaded texture is ready.
    // NEVER call rendering functions from within this callback.
    virtual void onAssetUpdate(ResourceID id, ASP<CTexture> newAsset) = 0;

    // Optional overrides:
    virtual CBox getBoundingBoxWl() const { return CBox(); }
    virtual void onClick(uint32_t button, bool down, const Vector2D& pos) {}
    virtual void onHover(const Vector2D& pos) {}

    // Check if a Wayland-coordinate point falls inside this widget's bounding box
    bool containsPoint(const Vector2D& pos) const;

    // --- Static helpers used by widget implementations ---

    // Convert halign/valign + offset + size into absolute screen position.
    // `ang` is widget rotation in radians.
    static Vector2D posFromHVAlign(const Vector2D& viewport, const Vector2D& size,
                                   const Vector2D& offset, const std::string& halign,
                                   const std::string& valign, const double& ang = 0);

    // Clamp rounding so it does not exceed half of the shortest box side.
    static int roundingForBox(const CBox& box, int roundingConfig);
    // Same for a border box given its thickness.
    static int roundingForBorderBox(const CBox& borderBox, int roundingConfig, int thickness);

    // Parse "left" | "center" | "right" into Hyprgraphics::CTextResource::eTextAlignmentMode
    static Hyprgraphics::CTextResource::eTextAlignmentMode parseTextAlignment(const std::string&);

    // Parse a label text string for variable substitution and dynamic update directives.
    // Returns formatted text, update interval (ms), and flags.
    struct SFormatResult {
        std::string formatted;
        float       updateEveryMs    = 0;   // >0: set a repeating timer
        bool        alwaysUpdate     = false;
        bool        cmd              = false; // true: spawn formatted as shell command
        bool        allowForceUpdate = false;
    };
    static SFormatResult formatString(std::string in);
};
```

--------------------------------

### IWidget Interface

Source: https://context7.com/hyprwm/hyprlock/llms.txt

The IWidget interface defines the core methods that all widgets must implement, including configuration, drawing, and asset updates. It also includes optional overrides for interaction and helper methods for positioning and parsing.

```APIDOC
## `IWidget` — Widget Interface (`src/renderer/widgets/IWidget.hpp`)

All widgets inherit from `IWidget`. This interface defines the contract for configuration, rendering, and event handling. The static helpers are used internally by all widget implementations.

```cpp
// IWidget virtual interface — implemented by Background, Label, Image,
// PasswordInputField, Shape.

class IWidget {
  public:
    struct SRenderData {
        float opacity = 1; // Global fade opacity [0.0, 1.0] from CRenderer
    };

    // Called once when the widget is constructed for an output.
    // `prop` maps config key names to std::any values (Hyprlang::INT/FLOAT/STRING or void* for custom types).
    virtual void configure(const std::unordered_map<std::string, std::any>& prop,
                           const SP<COutput>& pOutput) = 0;

    // Called every frame for this output. Return true if another frame is needed
    // (e.g., animation is in progress).
    virtual bool draw(const SRenderData& data) = 0;

    // Called from CAsyncResourceManager when an async-loaded texture is ready.
    // NEVER call rendering functions from within this callback.
    virtual void onAssetUpdate(ResourceID id, ASP<CTexture> newAsset) = 0;

    // Optional overrides:
    virtual CBox getBoundingBoxWl() const { return CBox(); }
    virtual void onClick(uint32_t button, bool down, const Vector2D& pos) {}
    virtual void onHover(const Vector2D& pos) {}

    // Check if a Wayland-coordinate point falls inside this widget's bounding box
    bool containsPoint(const Vector2D& pos) const;

    // --- Static helpers used by widget implementations ---

    // Convert halign/valign + offset + size into absolute screen position.
    // `ang` is widget rotation in radians.
    static Vector2D posFromHVAlign(const Vector2D& viewport, const Vector2D& size,
                                   const Vector2D& offset, const std::string& halign,
                                   const std::string& valign, const double& ang = 0);

    // Clamp rounding so it does not exceed half of the shortest box side.
    static int roundingForBox(const CBox& box, int roundingConfig);
    // Same for a border box given its thickness.
    static int roundingForBox(const CBox& borderBox, int roundingConfig, int thickness);

    // Parse "left" | "center" | "right" into Hyprgraphics::CTextResource::eTextAlignmentMode
    static Hyprgraphics::CTextResource::eTextAlignmentMode parseTextAlignment(const std::string&);

    // Parse a label text string for variable substitution and dynamic update directives.
    // Returns formatted text, update interval (ms), and flags.
    struct SFormatResult {
        std::string formatted;
        float       updateEveryMs    = 0;   // >0: set a repeating timer
        bool        alwaysUpdate     = false;
        bool        cmd              = false; // true: spawn formatted as shell command
        bool        allowForceUpdate = false;
    };
    static SFormatResult formatString(std::string in);
};

// --- Usage: reading config values from the std::any prop map ---
// Inside a widget's configure():

void MyWidget::configure(const std::unordered_map<std::string, std::any>& prop,
                         const SP<COutput>& pOutput) {
    // INT values
    int blurPasses = std::any_cast<Hyprlang::INT>(prop.at("blur_passes"));

    // FLOAT values
    float noise = std::any_cast<Hyprlang::FLOAT>(prop.at("noise"));

    // STRING values
    std::string path = std::any_cast<Hyprlang::STRING>(prop.at("path"));

    // Custom LAYOUTCONFIG value (CLayoutValueData*)
    auto* layoutData = CLayoutValueData::fromAnyPv(prop.at("size"));
    Vector2D absoluteSize = layoutData->getAbsolute(viewport);

    // Custom GRADIENTCONFIG value (CGradientValueData*)
    auto* grad = CGradientValueData::fromAnyPv(prop.at("outer_color"));
    // grad->m_vColors[i] are CHyprColor values
    // grad->m_fAngle is the gradient angle in radians
    // grad->m_vColorsOkLabA contains OkLab+A packed floats for GPU upload
}
```
```