### Install, Enable, Disable, Uninstall, and Update Plugins

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Use PluginService to manage the lifecycle of plugins. Install from metadata, enable/disable, uninstall to remove, and update to the latest version.

```qml
import qs.Services.Noctalia

// Install a plugin from an available plugin metadata object
PluginService.installPlugin(pluginMetadata, false, function(success, error, registeredKey) {
    if (success) {
        console.log("Installed:", registeredKey); // "catwalk"
    } else {
        console.log("Error:", error);
    }
});

// Enable / disable
PluginService.enablePlugin("catwalk");
PluginService.disablePlugin("catwalk");

// Uninstall (removes files + registry entry)
PluginService.uninstallPlugin("catwalk", function(success, error) {
    if (success) console.log("Uninstalled");
});

// Update a single plugin to latest version
PluginService.updatePlugin("catwalk", function(success, error) {
    console.log(success ? "Updated" : "Failed: " + error);
});

// Update all plugins with pending updates
PluginService.updateAllPlugins(function() {
    console.log("All plugins updated");
});
```

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

### List Installed Plugins

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Retrieve a list of all installed plugin IDs.

```APIDOC
## getAllInstalledPluginIds

### Description
Returns an array of strings, where each string is the ID of an installed plugin.

### Method
`PluginRegistry.getAllInstalledPluginIds(): string[]`
```

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

### Settings Migration Example Structure

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Define a QML QtObject with a `migrate` function to handle settings version updates. The migration function receives an adapter, logger, and raw JSON settings.

```qml
// Commons/Migrations/Migration59.qml (example structure)
QtObject {
    function migrate(adapter, Logger, rawJson) {
        Logger.i("Migration59", "Running migration to v59");
        // Example: rename a setting key
        if (rawJson && rawJson.bar && rawJson.bar.oldKey !== undefined) {
            adapter.bar.newKey = rawJson.bar.oldKey;
        }
        return true; // return false on failure
    }
}

// MigrationRegistry.qml lists all migrations
// migrations map: { 27: Migration27 {}, 28: Migration28 {}, ..., 59: Migration59 {} }

// Settings.runVersionedMigrations() iterates versions > adapter.settingsVersion
// and calls migration.migrate(adapter, Logger, rawJson) for each
```

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

### Manage Plugin State and Information

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Use these functions to check if a plugin is downloaded or enabled, list all installed plugin IDs, and retrieve a plugin's manifest details. Ensure the plugin ID is correct.

```qml
var installed = PluginRegistry.isPluginDownloaded("catwalk");  // → true/false
```

```qml
var enabled   = PluginRegistry.isPluginEnabled("catwalk");     // → true/false
```

```qml
var ids = PluginRegistry.getAllInstalledPluginIds();
// → ["catwalk", "abc123:my-custom-plugin", ...]
```

```qml
var manifest = PluginRegistry.getPluginManifest("catwalk");
// manifest.name, manifest.version, manifest.author, manifest.description
// manifest.entryPoints.main / barWidget / panel / desktopWidget / launcherProvider
```

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

### Enable or Disable Plugins

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Control the active state of installed plugins by setting their enabled status. Use the correct plugin ID.

```qml
PluginRegistry.setPluginEnabled("catwalk", true);
```

```qml
PluginRegistry.setPluginEnabled("catwalk", false);
```

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

### Refresh Plugin List and Check for Updates

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Reload the list of available plugins from all sources and check for pending updates against installed versions.

```qml
// Reload available plugin list from all sources
PluginService.refreshAvailablePlugins();

// Check for updates (compares installed versions vs remote registry)
PluginService.checkForUpdates();
// → updates stored in PluginService.pluginUpdates:
// { "catwalk": { currentVersion: "1.0.0", availableVersion: "1.2.0" } }
```

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

### PluginService - Plugin Management

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

The PluginService singleton provides methods for managing plugins at runtime. This includes installing, enabling, disabling, uninstalling, updating, and refreshing the list of available plugins.

```APIDOC
## PluginService - Plugin Management

### Description
Manages the lifecycle of plugins within the Noctalia Shell, including installation, loading, unloading, enabling, disabling, updating, and hot-reloading.

### Methods

#### `installPlugin(pluginMetadata, boolean, function)`
Installs a plugin from an available plugin metadata object. The boolean parameter is not described. The function callback receives `success`, `error`, and `registeredKey`.

#### `enablePlugin(pluginKey)`
Enables the specified plugin.

#### `disablePlugin(pluginKey)`
Disables the specified plugin.

#### `uninstallPlugin(pluginKey, function)`
Uninstalls the specified plugin, removing its files and registry entry. The function callback receives `success` and `error`.

#### `updatePlugin(pluginKey, function)`
Updates a single plugin to its latest version. The function callback receives `success` and `error`.

#### `updateAllPlugins(function)`
Updates all plugins that have pending updates. The function callback is executed upon completion.

#### `refreshAvailablePlugins()`
Reloads the list of available plugins from all configured sources.

#### `checkForUpdates()`
Compares installed plugin versions against the remote registry to identify available updates. Updates are stored in `PluginService.pluginUpdates`.

#### `togglePluginHotReload(pluginKey)`
Enables or disables file watching for a specific plugin, typically used in development mode.

#### `reloadPlugin(pluginKey)`
Forces a hot reload of the specified plugin.

### Plugin API Object
Available inside plugin QML via the `pluginApi` property:

- `pluginApi.pluginId`: The unique identifier of the plugin.
- `pluginApi.pluginDir`: The directory path of the plugin.
- `pluginApi.pluginSettings`: An object containing the plugin's settings.
- `pluginApi.saveSettings()`: Persists the current plugin settings.
- `pluginApi.openPanel(screen, buttonItem)`: Opens a panel associated with the screen.
- `pluginApi.closePanel(screen)`: Closes a panel associated with the screen.
- `pluginApi.togglePanel(screen, buttonItem)`: Toggles the visibility of a panel.
- `pluginApi.openLauncher(screen)`: Opens a launcher for the screen.
- `pluginApi.toggleLauncher(screen)`: Toggles the visibility of a launcher.
- `pluginApi.withCurrentScreen(callback)`: Executes a callback function with the current screen context.
- `pluginApi.tr(key, substitutions)`: Performs plugin-scoped translations.
- `pluginApi.trp(key, count)`: Performs plural translations.
```

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

### I18n - Date Formatting

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Get locale-aware date format strings for display using I18n.dateFormat().

```qml
// Get locale-aware date format string for lock screen / clock
var fmt = I18n.dateFormat(); // → "dddd, MMMM d" (English)
```

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

### Get Plugin Manifest

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Retrieve the manifest details for a specific plugin.

```APIDOC
## getPluginManifest

### Description
Retrieves the manifest object for a given plugin ID.

### Method
`PluginRegistry.getPluginManifest(pluginId: string): object`

### Response
- **manifest.name** (string) - The name of the plugin.
- **manifest.version** (string) - The version of the plugin.
- **manifest.author** (string) - The author of the plugin.
- **manifest.description** (string) - A description of the plugin.
- **manifest.entryPoints** (object) - An object detailing the plugin's entry points.
```

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

### Style - Per-Screen Bar Sizing and Colors

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Get specific bar heights for different screens using Style.getBarHeightForScreen(). Access derived color tokens and opacity values.

```qml
// Per-screen bar sizing (respects screen overrides)
var screenH = Style.getBarHeightForScreen("HDMI-A-1");

// Derived colors
var accent = Style.capsuleColor;          // Qt.alpha(mSurfaceVariant, capsuleOpacity)
var panelOpacity = Style.effectivePanelOpacity; // 0.93 unless performance mode is on
```

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

### List Discovered Color Schemes

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Access the ColorSchemeService.schemes property to get a list of file paths for all discovered color schemes.

```qml
// List all discovered scheme file paths
console.log(ColorSchemeService.schemes); // ["/.../Catppuccin/Catppuccin.json", ...]
```

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

### Get Display Name from Scheme File Path

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Use ColorSchemeService.getBasename() to extract the display name of a color scheme from its file path.

```qml
// Get display name from path
var name = ColorSchemeService.getBasename("/path/to/Noctalia-default/Noctalia-default.json");
// → "Noctalia (default)"
```

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

### Noctalia Shell Startup Sequence

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

This QML code outlines the simplified startup order for `shell.qml`, detailing the initialization phases of services and modules. Critical services are loaded synchronously, while deferred services are initialized later using `Qt.callLater`.

```qml
// shell.qml startup order (simplified)
ShellRoot {
    // Phase 1: loaded synchronously at startup
    // PluginRegistry.init() — called immediately in Component.onCompleted

    // Phase 2: waits for i18nLoaded && settingsLoaded && shellStateLoaded
    // Critical services (block first frame):
    WallpaperService.init()
    ImageCacheService.init()
    AppThemeService.init()
    ColorSchemeService.init()
    DarkModeService.init()

    // Deferred services (Qt.callLater — don't block first frame):
    LocationService.init()
    NightLightService.apply()
    IdleInhibitorService.init()
    IdleService.init()
    PowerProfileService.init()
    HostService.init()
    NotificationRulesService.init()
    GitHubService.init()
    SupporterService.init()
    CustomButtonIPCService.init()
    IPCService.init(screenDetector)

    // Modules instantiated after services:
    // Overview, Background, DesktopWidgets, AllScreens (bar + panels),
    // Dock, Notification, ToastOverlay, OSD, LockScreen, FadeOverlay,
    // SettingsPanelWindow, LauncherOverlayWindow (optional)

    // After 1500 ms:
    // HooksService.init(), FontService.init(), UpdateService.init()
    // → show setup wizard (fresh install) or changelog
}
```

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

### Launch Noctalia Shell with QuickShell

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

These commands demonstrate how to launch Noctalia Shell using `quickshell`, including options for enabling debug mode and overriding the configuration directory.

```bash
// Launch noctalia with quickshell:
// quickshell -p /path/to/noctalia-shell

// With debug mode:
// NOCTALIA_DEBUG=1 quickshell -p /path/to/noctalia-shell

// Override config directory:
// NOCTALIA_CONFIG_DIR=~/.config/my-noctalia quickshell -p /path/to/noctalia-shell
```

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

### Icons - Accessing Available Icons and Aliases

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Retrieve all available icon names and their codepoints via Icons.icons, and all defined aliases via Icons.aliases.

```qml
// Check available icons
var allIcons = Icons.icons;    // { "settings": "\uXXXX", "bell": "\uXXXX", ... }
var aliases  = Icons.aliases;  // { "gear": "settings", ... }
```

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

### Generate Theme from Wallpaper with AppThemeService

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Initiate theme generation from the current wallpaper using AppThemeService.generateFromWallpaper(). This process uses an external color extractor.

```qml
import qs.Services.Theming

// Generate theme from wallpaper (uses Settings.colorSchemes.monitorForColors or primary screen)
AppThemeService.generateFromWallpaper();
```

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

### ShellState Runtime State Management

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

This QML code demonstrates how to interact with the `ShellState` singleton to read and update transient runtime data, such as notification timestamps, changelog versions, UI states, and launcher usage statistics. It also shows how to record telemetry data and trigger a manual save.

```qml
import qs.Commons

// Read notification last-seen timestamp
var notifState = ShellState.getNotificationsState();
console.log(notifState.lastSeenTs); // Unix timestamp (ms)

// Update notification state
ShellState.setNotificationsState({ lastSeenTs: Date.now() });

// Changelog state
var clState = ShellState.getChangelogState();
// clState.lastSeenVersion → e.g. "1.5.2"
ShellState.setChangelogState({ lastSeenVersion: "1.5.2" });

// UI state (settings sidebar expanded)
ShellState.setSettingsSidebarExpanded(true);
var expanded = ShellState.getSettingsSidebarExpanded(); // → true

// Launcher app usage (most-used sorting)
ShellState.recordLauncherUsage("org.kde.konsole");
var count = ShellState.getLauncherUsageCount("org.kde.konsole"); // → 1
ShellState.migrateLauncherUsage("old-key", "new-key"); // merge counts

// Telemetry instance ID
ShellState.setTelemetryInstanceId("some-uuid");
var id = ShellState.getTelemetryInstanceId();

// Manual save (debounced by 500ms automatically)
ShellState.save();

// Full snapshot of all settings + runtime state (used by IPC/telemetry)
var snapshot = ShellState.buildStateSnapshot();
// snapshot.settings → all Settings.data fields as plain JS object
// snapshot.state.doNotDisturb, snapshot.state.wallpapers, etc.

```

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

### Manage persistent configuration with Settings singleton

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

The Settings singleton manages persistent configuration stored in `~/.config/noctalia/settings.json`. Changes are debounced and saved to disk, and the file is hot-watched for external modifications. Settings can be read, mutated, and defaults can be compared. Per-screen overrides for settings are also supported.

```qml
import qs.Commons

// Read a setting
var pos = Settings.data.bar.position;          // "top" | "bottom" | "left" | "right"
var opacity = Settings.data.bar.backgroundOpacity; // 0.93 by default

// Mutate a setting (auto-saves after 500 ms)
Settings.data.bar.position = "bottom";
Settings.data.general.animationSpeed = 1.5;
Settings.data.colorSchemes.darkMode = false;

// Force immediate save
Settings.saveImmediate();

// Detect settings loaded event
Connections {
    target: Settings
    function onSettingsLoaded() {
        console.log("Settings ready, version:", Settings.settingsVersion); // 59
    }
}

// Compare current value against default
var changed = Settings.isValueChanged("bar.position", Settings.data.bar.position);
// → false (still "top")

// Get default value
var def = Settings.getDefaultValue("general.animationSpeed"); // → 1.0

// Per-screen bar overrides
Settings.setScreenOverride("HDMI-A-1", "position", "left");
Settings.setScreenOverride("HDMI-A-1", "density", "compact");
var pos2 = Settings.getBarPositionForScreen("HDMI-A-1"); // → "left"
Settings.clearScreenOverride("HDMI-A-1", "position");    // revert to global

// Environment variables that control paths:
// NOCTALIA_CONFIG_DIR  – config directory (default: ~/.config/noctalia/)
// NOCTALIA_CACHE_DIR   – cache directory  (default: ~/.cache/noctalia/)
// NOCTALIA_SETTINGS_FILE – full path to settings.json
// NOCTALIA_DEBUG=1     – enable debug logging
```

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

### Apply Custom Color Scheme by File Path

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Apply a custom color scheme by providing the full file path to the scheme's JSON file using ColorSchemeService.applyScheme().

```qml
// Apply by file path
ColorSchemeService.applyScheme("/home/user/.config/noctalia/colorschemes/MyScheme/MyScheme.json");
```

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

### Style - Typography and Spacing

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Access design tokens for typography (font size, weight) and spacing (margins) via the Style singleton. Values scale with scaleRatio.

```qml
import qs.Commons

// Typography
Text {
    font.pixelSize: Style.fontSizeL    // 13 px (unscaled)
    font.weight: Style.fontWeightSemiBold  // 600
}

// Spacing / margins (scale with scaleRatio)
Rectangle {
    anchors.margins: Style.marginM    // ~9 px at 1×
    radius: Style.radiusS             // ~12 px at 1×
}
```

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

### Manage Plugin Sources (Git Repositories)

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Add, remove, or enable/disable Git repositories as sources for Noctalia plugins. The `addPluginSource` function requires a unique name for the source.

```qml
PluginRegistry.addPluginSource("My Plugins", "https://github.com/user/my-noctalia-plugins");
```

```qml
PluginRegistry.removePluginSource("https://github.com/user/my-noctalia-plugins");
```

```qml
PluginRegistry.setSourceEnabled("https://github.com/noctalia-dev/noctalia-plugins", true);
```

```qml
var sources = PluginRegistry.getEnabledSources();
// → [{ name: "Noctalia Plugins", url: "...", enabled: true }]
```

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

### AppThemeService

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Generates application themes from wallpapers or predefined color schemes and processes them for application.

```APIDOC
## AppThemeService — Wallpaper Color Generation

A singleton that triggers color palette generation either from the current wallpaper (using an external color extractor) or from a predefined scheme, then hands the result to `TemplateProcessor` for writing application theme files.

### Generate theme from wallpaper
```qml
import qs.Services.Theming

// Uses Settings.colorSchemes.monitorForColors or primary screen
AppThemeService.generateFromWallpaper();
```

### Generate from currently active predefined scheme
```qml
AppThemeService.generate();
```

### Force-generate from a specific scheme data object
```qml
// e.g. after loading a JSON file
AppThemeService.generateFromPredefinedScheme(schemeDataObject);
```

### Automatic triggers
These are triggered automatically when:
- `Settings.colorSchemes.darkMode` changes
- `Settings.colorSchemes.generationMethod` changes ("tonal-spot", "content", etc.)
- `WallpaperService` emits `wallpaperChanged` and `useWallpaperColors` is true
- `Settings.colorSchemes.monitorForColors` changes
```

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

### Configure Noctalia Shell with Nix

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

This Nix configuration sets up Noctalia Shell with custom settings for the bar, general appearance, color schemes, and plugins. It also defines user templates for application integration.

```nix
{
  imports = [ inputs.noctalia-shell.homeModules.default ];

  programs.noctalia-shell = {
    enable = true;

    settings = {
      bar = {
        position = "bottom";
        barType = "floating";
        backgroundOpacity = 0.95;
      };
      general = {
        animationSpeed = 1.5;
        radiusRatio = 1.2;
      };
      colorSchemes = {
        darkMode = true;
        useWallpaperColors = true;
        generationMethod = "tonal-spot";
      };
    };

    colors = {
      mPrimary = "#aaaaaa";
      mSurface = "#111111";
      mSurfaceVariant = "#191919";
      mOnSurface = "#828282";
      mOutline = "#3c3c3c";
      mError = "#dddddd";
      mShadow = "#000000";
    };

    plugins = {
      sources = [{
        enabled = true;
        name = "Noctalia Plugins";
        url = "https://github.com/noctalia-dev/noctalia-plugins";
      }];
      states = {
        catwalk = {
          enabled = true;
          sourceUrl = "https://github.com/noctalia-dev/noctalia-plugins";
        };
      };
      version = 2;
    };

    pluginSettings = {
      catwalk = {
        minimumThreshold = 25;
        hideBackground = true;
      };
    };

    user-templates = {
      templates = {
        neovim = {
          input_path = "~/.config/noctalia/templates/template.lua";
          output_path = "~/.config/nvim/generated.lua";
          post_hook = "pkill -SIGUSR1 nvim";
        };
      };
    };
  };
}
```

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

### Generate and Parse Composite Plugin Keys

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Utilities for handling composite keys, which are used for third-party plugins and typically include a source hash combined with the plugin ID. Ensure the input format is correct for parsing.

```qml
var key = PluginRegistry.generateCompositeKey("my-plugin", "https://github.com/user/repo");
// → "abc123:my-plugin"
```

```qml
var parsed = PluginRegistry.parseCompositeKey("abc123:my-plugin");
// → { sourceHash: "abc123", pluginId: "my-plugin", isOfficial: false }
```

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

### Noctalia Shell Configuration Schema

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

This JSON5 configuration file defines all customizable settings for the Noctalia Shell, including bar appearance, general preferences, color schemes, wallpaper settings, notifications, dock behavior, idle states, and plugin options. Modify this file to tailor the shell to your preferences.

```json5
// ~/.config/noctalia/settings.json (abbreviated)
{
  "bar": {
    "barType": "simple",           // "simple" | "floating" | "framed" 
    "position": "top",             // "top" | "bottom" | "left" | "right" 
    "density": "default",          // "mini" | "compact" | "default" | "comfortable" | "spacious" 
    "displayMode": "always_visible", // "always_visible" | "auto_hide" 
    "backgroundOpacity": 0.93,
    "showCapsule": true,
    "capsuleOpacity": 1.0,
    "outerCorners": true,
    "hideOnOverview": false,
    "fontScale": 1.0,
    "widgets": {
      "left":   [{"id":"Launcher"},{"id":"Clock"},{"id":"ActiveWindow"}],
      "center": [{"id":"Workspace"}],
      "right":  [{"id":"Tray"},{"id":"Battery"},{"id":"Volume"},{"id":"ControlCenter"}]
    },
    "screenOverrides": [
      { "name": "HDMI-1", "position": "left", "density": "compact" } 
    ]
  },
  "general": {
    "scaleRatio": 1.0,
    "radiusRatio": 1.0,
    "animationSpeed": 1.0,
    "animationDisabled": false,
    "enableShadows": true,
    "enableBlurBehind": true,
    "language": "",                // "" = auto-detect from system locale
    "clockFormat": "hh\nmm"
  },
  "colorSchemes": {
    "darkMode": true,
    "useWallpaperColors": false,
    "predefinedScheme": "Noctalia (default)",
    "generationMethod": "tonal-spot",
    "schedulingMode": "off",       // "off" | "auto" | "manual" 
    "manualSunrise": "06:30",
    "manualSunset": "18:30"
  },
  "wallpaper": {
    "enabled": true,
    "directory": "~/Pictures/Wallpapers",
    "transitionDuration": 1500,
    "transitionType": ["fade","disc","stripes","wipe","pixelate","honeycomb"],
    "automationEnabled": false,
    "randomIntervalSec": 300,
    "useWallhaven": false,
    "wallhavenQuery": "landscape"
  },
  "notifications": {
    "enabled": true,
    "location": "top_right",
    "lowUrgencyDuration": 3,
    "normalUrgencyDuration": 8,
    "criticalUrgencyDuration": 15
  },
  "dock": {
    "enabled": true,
    "position": "bottom",
    "displayMode": "auto_hide",    // "always_visible" | "auto_hide" | "exclusive" 
    "dockType": "floating"         // "floating" | "attached" 
  },
  "idle": {
    "enabled": false,
    "screenOffTimeout": 600,
    "lockTimeout": 660,
    "suspendTimeout": 1800
  },
  "hooks": {
    "enabled": false,
    "wallpaperChange": "notify-send 'Wallpaper changed'",
    "darkModeChange": "",
    "startup": "~/.config/noctalia/startup.sh"
  },
  "plugins": {
    "autoUpdate": false,
    "notifyUpdates": true
  }
}

```

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

### ColorSchemeService

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Manages predefined color schemes by discovering scheme files, applying them, and updating configuration.

```APIDOC
## ColorSchemeService — Predefined Color Schemes

A singleton that discovers `.json` color scheme files in `Assets/ColorScheme/` and user-downloaded schemes in `~/.config/noctalia/colorschemes/`, writes the active palette to `~/.config/noctalia/colors.json`, and triggers template regeneration.

### Apply a predefined scheme by name
```qml
import qs.Services.Theming

ColorSchemeService.setPredefinedScheme("Catppuccin");
ColorSchemeService.setPredefinedScheme("Dracula");
ColorSchemeService.setPredefinedScheme("Nord");
ColorSchemeService.setPredefinedScheme("Noctalia (default)");
```

### Available built-in schemes
`Ayu`, `Catppuccin`, `Dracula`, `Eldritch`, `Gruvbox`, `Kanagawa`, `Noctalia (default)`, `Nord`, `Rose Pine`, `Tokyo Night`

### Apply by file path
```qml
ColorSchemeService.applyScheme("/home/user/.config/noctalia/colorschemes/MyScheme/MyScheme.json");
```

### List all discovered scheme file paths
```qml
console.log(ColorSchemeService.schemes);
// Output: ["/.../Catppuccin/Catppuccin.json", ...]
```

### Get display name from path
```qml
var name = ColorSchemeService.getBasename("/path/to/Noctalia-default/Noctalia-default.json");
// → "Noctalia (default)"
```

### Color scheme JSON format
```json
{
  "dark": {
    "mPrimary": "#fff59b",
    "mOnPrimary": "#0e0e43",
    "mSecondary": "#a9aefe",
    "mOnSecondary": "#0e0e43",
    "mTertiary": "#9BFECE",
    "mOnTertiary": "#0e0e43",
    "mError": "#FD4663",
    "mOnError": "#0e0e43",
    "mSurface": "#070722",
    "mOnSurface": "#f3edf7",
    "mSurfaceVariant": "#11112d",
    "mOnSurfaceVariant": "#7c80b4",
    "mOutline": "#21215F",
    "mShadow": "#070722",
    "mHover": "#9BFECE",
    "mOnHover": "#0e0e43"
  },
  "light": {
    "mPrimary": "#5d65f5",
    "mSurface": "#e6e8fa"
  }
}
```
```

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

### Plugin State Checks

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Check if a plugin is downloaded and enabled.

```APIDOC
## isPluginDownloaded

### Description
Checks if a plugin with the given ID is downloaded.

### Method
`PluginRegistry.isPluginDownloaded(pluginId: string): boolean`

## isPluginEnabled

### Description
Checks if a plugin with the given ID is enabled.

### Method
`PluginRegistry.isPluginEnabled(pluginId: string): boolean`
```

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

### Log messages with Logger singleton

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Use the Logger singleton to format timestamped, ANSI-colored log lines to the Qt console. Four levels are available: debug (conditional), info, warning, and error. A module name is prepended and right-padded to 14 characters. The callStack() function can be used for debugging.

```qml
import qs.Commons

// Info message — always visible
Logger.i("MyModule", "Shell started");
// [14:02:33] MyModule Service started

// Debug message — only when NOCTALIA_DEBUG=1
Logger.d("MyModule", "Raw value:", someValue);

// Warning
Logger.w("MyModule", "Config not found, using defaults");

// Error
Logger.e("MyModule", "Failed to connect:", errorMsg);

// Print current call stack (for debugging)
Logger.callStack();
```

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

### Generate Theme from Active Predefined Scheme

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Trigger theme generation based on the currently active predefined color scheme using AppThemeService.generate().

```qml
// Generate from currently active predefined scheme
AppThemeService.generate();
```

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

### Plugin Sources Management

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Manage Git repository sources for plugins.

```APIDOC
## addPluginSource

### Description
Adds a new Git repository as a source for plugins.

### Method
`PluginRegistry.addPluginSource(name: string, url: string): void`

## removePluginSource

### Description
Removes a previously added plugin source.

### Method
`PluginRegistry.removePluginSource(url: string): void`

## setSourceEnabled

### Description
Enables or disables a plugin source.

### Method
`PluginRegistry.setSourceEnabled(url: string, enabled: boolean): void`

## getEnabledSources

### Description
Retrieves a list of currently enabled plugin sources.

### Method
`PluginRegistry.getEnabledSources(): Array<{ name: string, url: string, enabled: boolean }>`
```

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

### I18n - Language Management and Reactivity

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Change the current language at runtime using I18n.setLanguage(). Components bound to I18n.tr() will automatically update. Listen for language changes using Connections.

```qml
// Change language at runtime
I18n.setLanguage("de");   // German
I18n.setLanguage("zh-CN"); // Simplified Chinese

// Available languages:
// "en","en-GB","cs","de","es","fr","hu","it","ja","ko-KR","ku",
// "nl","nn-HN","nn-NO","pl","pt","ru","sv","tr","uk-UA","vi","zh-CN","zh-TW"

// React to language changes
Connections {
    target: I18n
    function onLanguageChanged(newLanguage) {
        console.log("Language switched to:", newLanguage);
    }
}
```

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

### Apply Predefined Color Schemes with ColorSchemeService

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Use ColorSchemeService.setPredefinedScheme() to apply built-in color schemes by name. This updates the active palette and triggers template regeneration.

```qml
import qs.Services.Theming

// Apply a predefined scheme by name (updates colors.json + templates)
ColorSchemeService.setPredefinedScheme("Catppuccin");
ColorSchemeService.setPredefinedScheme("Dracula");
ColorSchemeService.setPredefinedScheme("Nord");
ColorSchemeService.setPredefinedScheme("Noctalia (default)");
```

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

### Force Generate Theme from Scheme Data Object

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Use AppThemeService.generateFromPredefinedScheme() to force theme generation from a specific scheme data object, useful after loading a JSON file.

```qml
// Force-generate from a specific scheme data object (e.g. after loading a JSON file)
AppThemeService.generateFromPredefinedScheme(schemeDataObject);
```

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

### I18n - Basic Translation Lookup

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Use I18n.tr() for basic string lookups with dot-notation keys. Supports interpolation for dynamic values.

```qml
import qs.Commons

// Basic translation lookup (dot-notation key path)
var label = I18n.tr("panels.settings.title");
// → "Settings" (in English)

// With interpolations
var msg = I18n.tr("panels.plugins.install-success", { "plugin": "catwalk" });
// → "Plugin catwalk installed successfully"
```

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

### Icons - Resolve Icon Name to Codepoint

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Use Icons.get() to resolve icon names or aliases to their corresponding Unicode codepoint strings for use in Text elements.

```qml
import qs.Commons

// Resolve icon name to codepoint string
var code = Icons.get("settings");          // → "\uXXXX"
var code2 = Icons.get("gear");             // alias → resolves to "settings" codepoint
```

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

### Composite Key Helpers

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Generate and parse composite keys for third-party plugins.

```APIDOC
## generateCompositeKey

### Description
Generates a composite key for a plugin, typically used for third-party plugins.

### Method
`PluginRegistry.generateCompositeKey(pluginId: string, repositoryUrl: string): string`

## parseCompositeKey

### Description
Parses a composite key into its source hash and plugin ID components.

### Method
`PluginRegistry.parseCompositeKey(compositeKey: string): { sourceHash: string, pluginId: string, isOfficial: boolean }`
```

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

### Style - Animation and Bar Geometry

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Utilize Style tokens for animation durations, respecting animationSpeed and animationDisabled settings. Access bar geometry properties like height and font size.

```qml
// Animation durations (respect animationSpeed + animationDisabled)
NumberAnimation { duration: Style.animationNormal }  // 300 ms default
NumberAnimation { duration: Style.animationFast   }  // 150 ms default
NumberAnimation { duration: Style.animationSlow   }  // 450 ms default

// Bar geometry
var h = Style.barHeight;           // 31 px at "default" density (horizontal)
var ch = Style.capsuleHeight;      // 25 px at "default" density
var fs = Style.barFontSize;        // derived bar font size in px
```

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

### I18n - Pluralization and Existence Check

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Use I18n.trp() for pluralized translations based on count. Check for translation existence with I18n.hasTranslation() before use.

```qml
// Pluralization  (singular key / <key>-plural convention)
var txt = I18n.trp("panels.plugins.update-available", 3);
// → "3 updates available"  (uses "panels.plugins.update-available-plural")

// Check whether a key exists before using it
if (I18n.hasTranslation("optional.feature.label")) {
    label.text = I18n.tr("optional.feature.label");
}
```

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

### Hot Reload Plugins for Development

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Enable file watching for automatic reloads or force a manual reload of a plugin during development. Requires NOCTALIA_DEBUG=1.

```qml
// Hot reload (dev mode, requires NOCTALIA_DEBUG=1)
PluginService.togglePluginHotReload("catwalk"); // enable file watching
PluginService.reloadPlugin("catwalk");           // force reload
```

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

### Enable/Disable Plugin

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Set the enabled state for a specific plugin.

```APIDOC
## setPluginEnabled

### Description
Sets the enabled state for a plugin.

### Method
`PluginRegistry.setPluginEnabled(pluginId: string, enabled: boolean): void`
```

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

### Validate Plugin Manifest

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Check if a provided plugin manifest object conforms to the expected schema. The function returns an object indicating validity and any errors.

```qml
var result = PluginRegistry.validateManifest({
    id: "my-plugin", name: "My Plugin", version: "1.0.0",
    author: "Someone", description: "Does stuff",
    entryPoints: { barWidget: "BarWidget.qml" }
});
// → { valid: true, error: null }
```

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

### Plugin API Access within Plugins

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Access the plugin API object via the `pluginApi` property within a plugin's QML. Provides methods for interacting with Noctalia and managing plugin settings.

```qml
// Plugin API object available inside plugin QML via `pluginApi` property:
// pluginApi.pluginId        → "catwalk"
// pluginApi.pluginDir       → "/home/user/.config/noctalia/plugins/catwalk"
// pluginApi.pluginSettings  → { minimumThreshold: 25, ... }
// pluginApi.saveSettings()  → persist pluginSettings to settings.json
// pluginApi.openPanel(screen, buttonItem)
// pluginApi.closePanel(screen)
// pluginApi.togglePanel(screen, buttonItem)
// pluginApi.openLauncher(screen)
// pluginApi.toggleLauncher(screen)
// pluginApi.withCurrentScreen(callback)   // call callback(screen) with cursor's screen
// pluginApi.tr("my.key", { name: "val" }) // plugin-scoped translations
// pluginApi.trp("my.key", count)          // plural translation
```

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

### Plugin Manifest Schema

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

The JSON schema defining the structure and required fields for a plugin's `manifest.json` file. This includes metadata like ID, name, version, author, description, and entry points.

```json
{
  "id": "catwalk",
  "name": "Catwalk",
  "version": "1.2.0",
  "author": "noctalia-dev",
  "description": "Animated cat walking across your bar",
  "minNoctaliaVersion": "1.3.0",
  "entryPoints": {
    "main": "Main.qml",
    "barWidget": "BarWidget.qml",
    "panel": "Panel.qml",
    "desktopWidget": "DesktopWidget.qml",
    "launcherProvider": "LauncherProvider.qml",
    "controlCenterWidget": "ControlCenterWidget.qml"
  },
  "metadata": {
    "defaultSettings": {
      "minimumThreshold": 25,
      "hideBackground": false
    }
  }
}
```

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

### Color Scheme JSON Format

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Defines the structure for color scheme JSON files, including variants for dark and light modes with specific color properties.

```json
{
  "dark": {
    "mPrimary": "#fff59b",
    "mOnPrimary": "#0e0e43",
    "mSecondary": "#a9aefe",
    "mOnSecondary": "#0e0e43",
    "mTertiary": "#9BFECE",
    "mOnTertiary": "#0e0e43",
    "mError": "#FD4663",
    "mOnError": "#0e0e43",
    "mSurface": "#070722",
    "mOnSurface": "#f3edf7",
    "mSurfaceVariant": "#11112d",
    "mOnSurfaceVariant": "#7c80b4",
    "mOutline": "#21215F",
    "mShadow": "#070722",
    "mHover": "#9BFECE",
    "mOnHover": "#0e0e43"
  },
  "light": {
    "mPrimary": "#5d65f5",
    "mSurface": "#e6e8fa"
  }
}
```

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

### Consume Noctalia Shell Nix Flake

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Include the Noctalia Shell flake as an input in your Nix flake configuration to utilize its NixOS and Home Manager modules.

```nix
# flake.nix — consume the flake
{
  inputs.noctalia-shell.url = "github:noctalia-dev/noctalia-shell";
}
```

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

### Icons - Usage in Text Element and Font Reload

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Set the font family to Icons.fontFamily and use the resolved codepoint for the text. Icons.reloadFont() can be called to hot-reload the font.

```qml
// Use in a Text element
Text {
    font.family: Icons.fontFamily          // "noctalia-tabler-icons"
    font.pixelSize: 16
    text: Icons.get("bell")
}

// Hot-reload the font (called automatically after Quickshell.reloadCompleted)
Icons.reloadFont();
```

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

### Manifest Validation

Source: https://context7.com/noctalia-dev/noctalia-shell/llms.txt

Validate a plugin manifest object against the schema.

```APIDOC
## validateManifest

### Description
Validates a given manifest object.

### Method
`PluginRegistry.validateManifest(manifest: object): { valid: boolean, error: string | null }`

### Response
- **valid** (boolean) - Indicates if the manifest is valid.
- **error** (string | null) - An error message if the manifest is invalid, otherwise null.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.