Skip to content

README.md

Latest commit

 

History

History
178 lines (124 loc) · 6.4 KB

README.md

File metadata and controls

178 lines (124 loc) · 6.4 KB
Raw

QuickSwitcher (v1.2.0)

Version License Platform Electron Node

QuickSwitcher Demo

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.