{
  config,
  pkgs,
  lib,
  ...
}:

# QuickShell autostart app manager: lets the user pick from the gear
# quick-settings panel which installed apps start at login. The candidate
# *pool* is declared here (services.quickshell-apps.apps) and seeded into
# ~/.config/quickshell/autostartseed.json; runtime on/off state and any apps
# added from the UI live in ~/.cache/quickshell/autostart.json. The Hyprland
# login autostart runs `qs-apps run` (see home-manager/modules/hyprland.nix)
# to launch whatever is enabled.
{
  options.services.quickshell-apps = {
    enable = lib.mkEnableOption "QuickShell autostart app manager (runtime toggle from the gear panel)";

    apps = lib.mkOption {
      type = lib.types.listOf (
        lib.types.submodule {
          options = {
            name = lib.mkOption {
              type = lib.types.str;
              description = "Display name shown in the gear panel.";
            };
            cmd = lib.mkOption {
              type = lib.types.str;
              description = "Command to launch the app (shell-style, argv 0 must name the binary).";
            };
          };
        }
      );
      default = [ ];
      description = "Candidate pool the user can toggle/start from the shell.";
    };
  };

  config = lib.mkIf config.services.quickshell-apps.enable {
    # Store the manager in the Nix store with the procps tools baked in (the
    # Hyprland login autostart PATH is not guaranteed to have pgrep/pkill).
    xdg.configFile."quickshell/qs-apps.py".text =
      builtins.replaceStrings
        [
          "@pgrep@"
          "@pkill@"
        ]
        [
          "${pkgs.procps}/bin/pgrep"
          "${pkgs.procps}/bin/pkill"
        ]
        (builtins.readFile ./quickshell-apps.py);

    # Nix-declared pool. The runtime state file is authoritative for on/off
    # and for UI-added apps; the manager merges this in on every load, adding
    # new entries as disabled.
    xdg.configFile."quickshell/autostartseed.json".text = builtins.toJSON (
      map (app: {
        name = app.name;
        cmd = app.cmd;
      }) config.services.quickshell-apps.apps
    );

    home.file.".local/bin/qs-apps" = {
      executable = true;
      text = ''
        #!/bin/sh
        exec ${pkgs.python3}/bin/python3 \
          ${config.home.homeDirectory}/.config/quickshell/qs-apps.py "$@"
      '';
    };
  };
}