# Services Catalog

70+ QML singletons that handle everything that isn't pure UI. Each service is registered in `services/qmldir` (or `services/deferred/qmldir`) and available as a singleton import everywhere.

> Only some services expose an IPC handler. The real IPC targets are listed where they exist; if a service has no `IPC target:` note, it has no `IpcHandler` and is not callable from the `inir` CLI. To regenerate the authoritative list: `grep -rl IpcHandler services/ | xargs grep -oP 'target:\s*"\K[^"]+'`.

## Compositor

| Service | What it does |
|---------|-------------|
| **NiriService** | Niri IPC via Unix socket. Tracks workspaces, windows, outputs, keyboard layouts. Event-driven with reactive properties. IPC target: `keyboard` (layout switching). |
| **CompositorService** | Detects compositor (Niri/Hyprland/GNOME), provides sorted toplevel windows and compositor-agnostic APIs. |
| **HyprlandData** | Hyprland window, workspace, monitor, and layer data via `hyprctl`. |
| **HyprlandKeybinds** | Parses Hyprland config for keybind cheatsheet. |
| **HyprlandXkb** | Keyboard layout tracking for Hyprland. |

## Audio and Media

| Service | What it does |
|---------|-------------|
| **Audio** | PipeWire integration. Default sink/source, volume, mute, per-app mixer. EasyEffects virtual sink detection. IPC target: `audio`. |
| **MprisController** | MPRIS player management. Filters real players, deduplicates YT Music instances, tracks active player with grace period for track transitions. IPC target: `mpris`. |
| **YtMusic** | YouTube Music player. Search, queue, playback via mpv + yt-dlp. IPC target: `ytmusic`. |
| **SongRec** | Music recognition via SongRec (Shazam-like audio fingerprinting). |

## System

| Service | What it does |
|---------|-------------|
| **Network** | NetworkManager integration. WiFi networks, connection status, signal strength. |
| **BluetoothStatus** | Bluetooth adapter and device status via BlueZ D-Bus. |
| **Battery** | UPower integration. Percentage, charging state, charge limit control, low/critical thresholds. |
| **Brightness** | Monitor brightness via brightnessctl (laptop) and ddcutil (external monitors). Per-screen control. IPC target: `brightness`. |
| **PowerProfilePersistence** | Restores the user's power profile on startup. |
| **GameMode** | Fullscreen detection with auto/manual activation. Suppresses animations, notifications, blur when gaming. IPC target: `gamemode`. |
| **Idle** | Idle management via swayidle. Screen-off, lock, and suspend timeouts. Set `idle.onBattery.enable` to apply a separate, shorter set of timeouts while a laptop runs unplugged. |
| **ResourceUsage** | CPU, RAM, GPU, temperature, disk polling. History arrays for graphs. Auto-stop timer (15s) when no consumers active. |
| **ScreenTime** | Optional focused-app usage tracking. Local JSON storage, daily totals, hourly buckets, 3/14 day range aggregation. Disabled unless `sidebar.screenTime.enable` is true. |
| **SystemInfo** | Distro name, username, desktop environment detection. |
| **ShellLayoutController** | Validates and persists bar, dock, taskbar and sidebar placement across panel families. IPC target: `shellLayout`. |
| **Privacy** | Mic and screen sharing detection via PipeWire link analysis. |

## Theming and Appearance

| Service | What it does |
|---------|-------------|
| **ThemeService** | Theme orchestration. Applies presets, triggers wallpaper-based regeneration, manages auto vs manual mode. |
| **MaterialThemeLoader** | Watches `colors.json` (generated by the color pipeline) and loads Material 3 colors into Appearance tokens. |
| **ThemePresets** | 46 built-in theme presets (Catppuccin, Gruvbox, Nord, Angel, etc.) with full M3 color definitions. |
| **Wallpapers** | Wallpaper management. Multi-monitor support, video wallpapers, backdrop system, auto-cycling. |
| **WallpaperListener** | Multi-monitor wallpaper config resolver. |
| **IconThemeService** | Icon theme management. Syncs to GTK, KDE, Qt5ct, Qt6ct. Smart Electron app icon resolution. |
| **FontSyncService** | Syncs shell fonts to GTK/KDE desktop settings. |
| **AwwwBackend** | awww animated wallpaper daemon integration. |
| **GowallService** | gowall wallpaper color extraction and palette generation. |

## Data and Storage

| Service | What it does |
|---------|-------------|
| **Notifications** | Notification management with persistent storage, popup control, grouping, DND mode, GameMode integration. IPC target: `notifications`. |
| **Cliphist** | Clipboard history with fuzzy search. Uses cliphist backend. IPC target: `cliphistService`. |
| **Events** | Local calendar events with categories, priorities, reminders, recurrence. JSON storage. |
| **CalendarSync** | External calendar sync via ICS/iCal URLs. Fetches with curl, parses in JS. Supports Google Calendar, Outlook, Nextcloud, any CalDAV. |
| **Weather** | Open-Meteo weather data with GPS, manual coordinates, or city name location. |
| **Todo** | Todo list with JSON + markdown sync. |
| **Notepad** | Persistent plaintext notepad. |
| **KeyringStorage** | Secure API key storage via GNOME Keyring (secret-tool). |
| **DateTime** | Date/time formatting, uptime tracking. |

## Desktop Integration

| Service | What it does |
|---------|-------------|
| **Autostart** | Autostart manager. Reads/writes the managed section of `~/.config/niri/config.d/50-startup.kdl`. Niri's own `spawn-at-startup` directives are the source of truth, not a Config JSON list. IPC target: `autostart`. |
| **TrayService** | System tray with workarounds for problematic apps (Vesktop, Steam, etc.). |
| **PolkitService** | PolicyKit authentication agent for privileged operations. |
| **Hyprsunset** | Night light via wlsunset (Niri) or hyprsunset (Hyprland). Scheduled or manual. |
| **EasyEffects** | EasyEffects audio effects toggle. Supports native and flatpak. |
| **RecorderStatus** | Screen recording status detection (wf-recorder). |
| **MascotMood** | Session-long personality mood for the mascot, with time-of-day seeding and jittered changes. IPC target: `mascotMood`. |
| **SessionWarnings** | Detects running package managers before logout. |
| **ConflictKiller** | Kills conflicting system trays and notification daemons on startup. |
| **FirstRunExperience** | First-run wizard trigger. |

## Application Management

| Service | What it does |
|---------|-------------|
| **AppLauncher** | Default app slot manager (terminal, browser, file manager, etc.). |
| **AppSearch** | Desktop entry fuzzy search with icon substitution mappings. |
| **AppCatalog** | Curated software catalog with multi-distro install support. IPC target: `appCatalog`. |
| **LauncherSearch** | Overview search with prefix routing (apps, actions, calculator, packages). |
| **TaskbarApps** | Dock/taskbar app list (merged pinned + open windows). |
| **MinimizedWindows** | Niri window minimization via hidden workspace. IPC target: `minimize`. |
| **WindowPreviewService** | Window preview caching for task view. |
| **GlobalActions** | Modular action registry for keyboard-driven workflows. User-extensible. IPC target: `globalActions`. |

## Content

| Service | What it does |
|---------|-------------|
| **Ai** | LLM chat. Gemini, OpenAI, Mistral, OpenRouter, Ollama. Tool use, streaming, conversation history. IPC target: `ai`. |
| **AnimeService** | AniList GraphQL API. Anime schedule, seasonal listing. |
| **Wallhaven** | Wallhaven.cc wallpaper search with rate limiting. |
| **Booru** | Multi-booru image board API (yande.re, konachan, danbooru, etc.). |
| **VoiceSearch** | Voice recording + Gemini transcription + web search. IPC target: `voiceSearch`. |
| **Emojis** | Emoji picker data. |
| **PackageSearch** | Async package manager search (pacman + AUR). IPC target: `packageSearch`. |

## Utilities

| Service | What it does |
|---------|-------------|
| **TimerService** | Pomodoro timer with persistent state. |
| **Updates** | System update checker (Arch only, uses `checkupdates`). |
| **ShellUpdates** | iNiR update checker. Git-based, tracks commits behind remote. IPC target: `shellUpdate`. |
| **Ydotool** | Virtual keyboard input for on-screen keyboard. |
| **LatexRenderer** | LaTeX math rendering via MicroTeX. |
| **Translation** | i18n string lookup. Auto language detection, 15 languages. |
| **DevNavigation** | Deterministic development navigation for loading lazy surfaces and internal settings views. IPC target: `dev`. |
| **CustomWidgets** | User-installed custom widget management (scan/create/list/remove from the widgets dir). IPC target: `customWidgets`. |
| **MemoryPressureService** | Monitors JSGCHeap accumulation (Qt V4 memfd leak); notifies and offers a shell restart. IPC target: `memory`. |
| **WidgetPowerManager** | Pauses desktop-widget rendering on game mode / fullscreen / present windows / edit mode. IPC target: `widgetpower`. |

## For contributors

Services are stability boundaries. Changes to a service API affect every module that consumes it.

Before modifying a service:

1. Check consumer count: `grep -r "ServiceName\." modules/ services/`
2. Prefer add-only changes to public APIs
3. Register new services in `services/qmldir`
4. Add IPC targets to [IPC Reference](IPC.md) if applicable