QuickSwitcher (v1.2.0)

Minimal, GPU-accelerated transient overlay wallpaper switcher engineered for Hyprland, Wayland, and cross-platform desktop environments (GNOME, KDE Plasma, XFCE, MATE, generic X11, Windows, and macOS).

---

Architectural Highlights

• Transient Bottom Overlay: Lightweight bottom strip with single-instance enforcement and disabled background window throttling.
• Compositor-Accelerated Scrolling: Horizontal track navigation offloaded to Chromium's GPU rasterizer and compositor thread.
• Asynchronous Thumbnail Pipeline: High-resolution wallpapers (4K/8K) are downsampled asynchronously to cached 800px previews via C++ decoders (nativeImage) with ImageMagick and ffmpeg fallbacks, preventing high-resolution image bloat in renderer memory.
• Non-Blocking Background Worker Queue: Immediate filesystem directory scanning with background concurrency-limited video frame extraction (MAX_CONCURRENT_FFMPEG = 4) streaming live thumb-ready updates.
• Opaque ID Architecture & TOCTOU Defense: Raw filesystem paths are isolated to the main process. Renderer IPC operates strictly over opaque SHA-256 tokens revalidated against inode, size, and mtime before execution. See SECURITY.md.
• Process Ownership Verification: Safe mpvpaper process lifecycle tracking using /proc/<pid>/stat start-time and /proc/<pid>/exe verification to eliminate PID recycling hazards.

---

Desktop Environment Support Matrix

QuickSwitcher automatically detects the active desktop environment and dispatches to the native tool:

Environment	Static Formats	Animated / Video	Backend Integration
Hyprland / Wayland	Yes	Yes	swww / hyprpaper / mpvpaper
GNOME / Cinnamon	Yes	Fallback	gsettings (org.gnome.desktop.background)
MATE	Yes	Fallback	gsettings (org.mate.background)
KDE Plasma	Yes	Fallback	plasma-apply-wallpaperimage
XFCE	Yes	Fallback	xfconf-query (xfce4-desktop)
Generic X11	Yes	Fallback	feh
Windows 10 / 11	Yes	Fallback	SystemParametersInfoW (PowerShell)
macOS	Yes	Fallback	AppleScript (osascript)

---

Keybindings & Controls

Shortcut / Input	Description
Click / Enter	Apply selected wallpaper and dismiss overlay
Right Click	Open delete confirmation modal
h / l or Left / Right	Navigate wallpaper cards
/	Focus search input
Escape	Dismiss QuickSwitcher
Mouse Wheel	Horizontal track scrolling

---

Requirements

• Node.js: >= 20.0.0 (LTS recommended)
• Electron: >= 34.0.0
• Linux Tools (Optional / Recommended): ffmpeg (video previews), imagemagick (fast thumbnailing), swww or hyprpaper (Wayland), mpvpaper (video wallpapers).

---

Installation & Setup

1. Install System Dependencies

Arch Linux:

sudo pacman -S nodejs npm electron ffmpeg mpvpaper swww hyprpaper imagemagick

Ubuntu / Debian:

sudo apt update && sudo apt install -y nodejs npm ffmpeg imagemagick

Fedora:

sudo dnf install -y nodejs npm ffmpeg ImageMagick

2. Clone and Build

git clone https://github.com/ArchEnjoyerakazonix/QuickSwitcher.git ~/.config/quickswitcher
cd ~/.config/quickswitcher
npm ci

# Build local standalone unpacked binary (recommended for instant startup)
npm run pack

3. Integration & Launching

Hyprland Setup

Add the overlay toggle keybinding and floating window rules to ~/.config/hypr/hyprland.conf:

# Toggle QuickSwitcher overlay (using packaged binary for instant startup)
bind = CTRL SUPER, W, exec, ~/.config/quickswitcher/dist/linux-unpacked/quickswitcher

# Floating overlay window rules
windowrulev2 = float, title:^(QuickSwitcher)$
windowrulev2 = pin, title:^(QuickSwitcher)$
windowrulev2 = move 0 100%-300, title:^(QuickSwitcher)$

Development runner fallback:

bind = CTRL SUPER, W, exec, npm --prefix ~/.config/quickswitcher start

Application Menus & Other Desktop Environments (GNOME, KDE, XFCE, Sway)

On first launch, QuickSwitcher automatically creates and registers quickswitcher.desktop in ~/.local/share/applications/. It becomes instantly searchable and launchable via system app menus and launchers (Rofi, Wofi, KRunner, GNOME Dash, XFCE App Finder).

---

Offline Thumbnail Pre-Generation

To pre-cache thumbnails for large wallpaper directories ahead of time:

node scripts/generate-thumbs.js

---

Testing & Verification

QuickSwitcher includes unit tests, integration tests, and containerized multi-distro sandboxes:

# Check syntax
npm run check

# Run unit and integration tests with coverage
npm test

# Run multi-environment container tests (Debian/Ubuntu, Alpine, Node 20/22)
npm run test:containers

# Full verification pass
npm run verify

---

Security Model

Detailed information regarding threat modeling, context isolation, TOCTOU mitigations, and PID ownership validation is documented in SECURITY.md.

---

Configuration & Storage Paths

• Linux Config: ~/.config/QuickSwitcher/
  • favorites.json: Persisted favorites list.
  • custom_folders.json: User-registered wallpaper directories.
  • state.json: Active wallpaper tracking.
  • mpvpaper_pids.json: Tracked video process registry.
• Linux Cache: ~/.cache/quickswitcher-thumbs/ (hashed preview cache).
• Windows Config: %APPDATA%\QuickSwitcher\
• macOS Config: ~/Library/Application Support/QuickSwitcher/

---

Contributing & Issues

Contributions, bug reports, and suggestions are welcome!

• Bug Reports & Features: Open an issue on GitHub Issues.
• Pull Requests: Ensure all checks and tests pass with npm run verify before submitting.

---

License

MIT License. See LICENSE for details.