GPAL.cs

// =============================================================================
// GPAL - Generally Positive Automation Library
// Copyright © 2026 Software Decisions, Inc. All rights reserved.
//
// This file is part of GPAL.
// Licensed under the Business Source License 1.1
//
// Primary development, architecture, and vision by Michael B. Vederman,
// CEO of Software Decisions, Inc., Texas.
//
// Internal development maintained privately.
// Public releases appear on GitHub: https://github.com/SoftwareDecisionsInc/GPAL.
//
// See LICENSE for full terms, including Additional Use Grant.
// =============================================================================
 
using DocumentFormat.OpenXml.Office.CustomUI;
using GenerallyPositive.Application;
using GenerallyPositive.Browser;
using GenerallyPositive.GPALForm;
using OpenQA.Selenium;
using OpenQA.Selenium.Remote;
using System;
using System.Collections;
using System.Collections.Generic;
using System.Data.SqlClient;
using System.Diagnostics;
using System.Drawing;
using System.Drawing.Imaging;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Runtime.CompilerServices;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Automation;
using System.Windows.Forms;
using static GenerallyPositive.Browser.Browser;
using static GenerallyPositive.Enums;
using static GenerallyPositive.GPALForm.GPALForm;
 
namespace GenerallyPositive
{
    public class GPAL
    {
        private static Stopwatch _appTimer;
        private static DateTime _startTime;
        
        #region <Virtual Keys>
        public static byte VK_ALT { [Keys(Description = "Virtual key code for Alt, for use with keybd_event")] get { return 0x12; } }
        public static byte VK_DELETE { [Keys(Description = "Virtual key code for Delete, for use with keybd_event")] get { return 0x2e; } }
        public static byte VK_F10 { [Keys(Description = "Virtual key code for F10, for use with keybd_event")] get { return 0x79; } }
        public static byte VK_PRIOR { [Keys(Description = "Virtual key code for Page Up, for use with keybd_event")] get { return 0x21; } } // page up - to scroll up a page
        public static byte VK_NEXT { [Keys(Description = "Virtual key code for Page Down, for use with keybd_event")] get { return 0x22; } }  // page down - to scroll down a page
        public static byte VK_END { [Keys(Description = "Virtual key code for End, for use with keybd_event")] get { return 0x23; } }  // end key
        public static byte VK_HOME { [Keys(Description = "Virtual key code for Home, for use with keybd_event")] get { return 0x24; } } // home key
        public static byte VK_DOWN { [Keys(Description = "Virtual key code for the Down Arrow, for use with keybd_event")] get { return 0x28; } } // down arrow
        public static byte VK_UP { [Keys(Description = "Virtual key code for the Up Arrow, for use with keybd_event")] get { return 0x26; } } // up arrow
        public static byte VK_TAB { [Keys(Description = "Virtual key code for Tab, for use with keybd_event")] get { return 0x09; } } // tab
        public static byte VK_RETURN { [Keys(Description = "Virtual key code for Enter, for use with keybd_event")] get { return 0x0D; } } // enter
        public static byte VK_SHIFT_RIGHT { [Keys(Description = "Virtual key code for the right Shift, for use with keybd_event")] get { return 0xA1; } }
        public static byte VK_SHIFT_LEFT { [Keys(Description = "Virtual key code for the left Shift, for use with keybd_event")] get { return 0xA0; } }
        public static byte VK_CONTROL_LEFT { [Keys(Description = "Virtual key code for the left Control, for use with keybd_event")] get { return 0xA2; } }
        public static byte VK_CONTROL_RIGHT { [Keys(Description = "Virtual key code for the right Control, for use with keybd_event")] get { return 0xA3; } }
        public static byte VK_LWIN { [Keys(Description = "Virtual key code for the left Windows key, for use with keybd_event")] get { return 0x5B; } }
        public static byte VK_RWIN { [Keys(Description = "Virtual key code for the right Windows key, for use with keybd_event")] get { return 0x5C; } }
        public static byte VK_SCROLL { [Keys(Description = "Scroll Lock key virtual keycode (VK) for use with keybd_event")] get { return 0x91; } }
        public static byte VK_LMENU { [Keys(Description = "Left Alt key virtual keycode (VK) for use with keybd_event")] get { return 0xA4; } }
        public static byte VK_RMENU { [Keys(Description = "Right Alt key virtual keycode (VK) for use with keybd_event")] get { return 0xA5; } }
        public static byte VK_APPS { [Keys(Description = "Application (Menu) key virtual keycode (VK) for use with keybd_event")] get { return 0x5D; } }
        public static byte VK_SPACE { [Keys(Description = "Virtual key code for the space bar, for use with keybd_event")] get { return 0x20; } }
        public static byte VK_BACK { [Keys(Description = "Virtual key code for Backspace, for use with keybd_event")] get { return 0x08; } }
        [Keys(Description = "keybd_event flag marking an extended key, such as the right-hand Alt and Control")]
        public static uint KEYEVENTF_EXTENDEDKEY { [Keys(Description = "keybd_event flag marking an extended key, such as the right-hand Alt and Control")] get { return 0x0001; } }
        public static uint KEYEVENTF_KEYUP { [Keys(Description = "keybd_event flag that sends the release of a key rather than the press")] get { return 0x0002; } }
        #endregion <Virtual Keys>
        #region <Working Variables>
        private static List<Application.Application> ApplicationList { get; } = new List<Application.Application>();
        private static List<Browser.Browser> BrowserList { get; } = new List<Browser.Browser>();
        private static List<Selector> SelectorList { get; } = new List<Selector>();
        private static List<GPALForm.GPALForm> FormList { get; } = new List<GPALForm.GPALForm>();
        private static List<IGPALAI> AIList { get; } = new List<IGPALAI>();
        private static List<GPALFile> FileList { get; } = new List<GPALFile>();
        private static List<IGPALMail> MailList { get; } = new List<IGPALMail>();
        public static List<IGPALLogger> LoggerList { get; } = new List<IGPALLogger>();
        private static List<GPALControl> ControlList { get; } = new List<GPALControl>();
        private static List<IGPALGrid<string>> GridList { get; } = new List<IGPALGrid<string>>();
 
        private static bool SettingsLoaded 
        { 
            get
            {
                return gpalSettings.SettingsLoaded;
            }
 
            set
            {
                gpalSettings.SettingsLoaded = value;
            }
        }
        // deep copy cannot copy to properties
        private static GPALSettings gpalSettings = new GPALSettings(true);    // this will be initialized if we can't load from GPAL.yaml
        private static string _settingsFilePath = "GPAL.yaml";
        public static GPALSettings GPALSettings
        {
            [GPALSettings(Description = "The global settings GPAL is running with")] get
            {
                return gpalSettings;
            }
            set
            {
                gpalSettings = value;
            }
        }
        private static Browser.ElementAssistant elementAssistant { get; } = new Browser.ElementAssistant();
        private static Application.ElementAssistant applicationElementAssistant { get; } = new Application.ElementAssistant();
 
        private static Browser.Browser tmpBrowser { get; set; } = null;
        private static Application.Application tmpApplication { get; set; } = null;
        private static bool UncaughtExceptionHandlerSet { get; set; } = false;
 
        private static int applicationCount = 1;
        private static int browserCount = 1;
        private static int selectorCount = 1;
        private static int formCount = 1;
        private static int controlCount = 1;    // will not count each type of control (but should we?)
        private static int executableCount = 1;
        private static int restClientCount = 1;
 
        private static readonly string applicationName = "Application";
        private static readonly string browserName = "Browser";
        private static readonly string chartName = "Chart";
        private static readonly string selectorName = "Selector";
        private static readonly string formName = "Form";
        private static readonly string buttonName = "Button";
        private static readonly string checkboxName = "Checkbox";
        private static readonly string inputName = "Input";
        private static readonly string labelName = "Label";
        private static readonly string linkLabelName = "LinkLabel";
        private static readonly string spacerName = "Spacer";
        private static readonly string radioButtonName = "Radiobutton";
        private static readonly string textAreaName = "TextArea";
        private static readonly string richTextBoxName = "RichTextBox";
        private static readonly string executableName = "Executable";
        private static readonly string restClientName = "RESTClient";
 
        private static bool inPublishEvent = false;
        // which loggers are part way through a write on this thread, so one can be kept from receiving what it
        // raised while writing without keeping it from the others
        [ThreadStatic] private static HashSet<IGPALLogger> loggersWriting;
        #endregion <Working Variables>
        #region Constructor
        static bool inStaticInit = false;
        // Private constructor to prevent instantiation
        private GPAL() { }
        static GPAL()
        {
            if (false == inStaticInit)
            {
                inStaticInit = true;
 
                // Initialize timer
                _startTime = DateTime.Now;
                _appTimer = Stopwatch.StartNew();
 
                GPAL.LoadSettings();
 
                if (ConsoleEvents.HasFlag(GPALEventType.INFO))
                {
                    PublishSimpleEvent(GPALEventType.INFO, $">>> GPAL v[{GPAL.Version}]");
                    PublishSimpleEvent(GPALEventType.INFO, $">>> Application Start Time: [{_startTime.ToString("yyyy-MM-dd HH:mm:ss")}] <<<");
                }
                else if (ConsoleEvents.HasFlag(GPALEventType.NOTICE))
                {
                    PublishSimpleEvent(GPALEventType.NOTICE, $">>> GPAL v[{GPAL.Version}]");
                    PublishSimpleEvent(GPALEventType.NOTICE, $">>> Application Start Time: [{_startTime.ToString("yyyy-MM-dd HH:mm:ss")}] <<<");
                }
 
                SetCatchUncaughtExceptions();
 
                inStaticInit = false;
            }
        }
        #endregion Constructor
        #region <Exception & Information EventHandler>
        public class GPALEventArgs : System.EventArgs
        {
            public Enums.GPALEventType GPALEventType { get; set; }
            public dynamic GPALObject { get; set; }
            public Enums.GPALObjectType GPALObjectType { get; set; }
            public UnitOfWork CurrentUOW { get; set; }
            public string Message { get; set; }
            public Exception ExceptionRaised { get; set; }
            public Image ScreenShot { get; set; }
            public IWebDriver BrowserDriver { get; set; }
            public Selector Selector { get; set; }
            public GPALElement GPALElement { get; set; }
            public List<GPALElement> WebElements { get; set; }
            public AutomationElement AutomationElement { get; set; }
            public List<GPALAutomationElement> AutomationElements { get; set; }
            public SelectorSettings.SelectorPathEntry SelectorPathEntry { get; set; }
            public IGPALGrid<string> Tokens { get; set; }
            public List<IGPALGrid<string>> TokenList { get; set; }
            public SqlCommand SqlCommand { get; set; }
            public dynamic Data { get; set; }
            public DateTime DateTimeStamp { get; set; }
        }
 
        internal static EventHandler<GPALEventArgs> ExceptionEventHandler { get; set; }
        internal static EventHandler<GPALEventArgs> InformationEventHandler { get; set; }
        #endregion <Exception & Information EventHandler>
        #region <Globals>
        internal static EventHandler<GPALEventArgs> ExceptionHandler
        {
            get
            {
                return ExceptionEventHandler;
            }
        }
        internal static EventHandler<GPALEventArgs> InformationHandler
        {
            get
            {
                return InformationEventHandler;
            }
        }
        #endregion <Globals>
        #region <GPAL Object Getters>
        public static Cryptography Cryptography
        {
            [Component(Description = "Encrypt, decrypt, hash, sign and verify data", Submenu = "Security")] get => new Cryptography();
        }
        public static Base64Helper Base64Helper
        {
            [Component(Description = "Encode and decode Base64", Submenu = "Security")] get => new Base64Helper();
        }
        public static IAllowAIProvider AI
        {
            [Component(Description = "Entry point for the GPAL AI subsystem, providing a fluent interface for AI tasks", Submenu = "Services")] get
            {
                GPALAI ai = new GPALAI();
                AIList.Add(ai);
                return ai;
            }
        }
 
        public static IGPALYouTube YouTube { [Component(Description = "Upload videos to YouTube, manage playlists and search", Submenu = "Google")] get => new Browser.GPALYouTube(); }
 
        // OCR is on the roadmap: it registers the same way GPAL.Image does, and is left here until then
        //private static Func<OCRInterfaces.IGPALOCR> _ocrFactory;
        //[Action(Description = "Register the OCR provider from the GenerallyPositive.OCR package")]
        //public static void RegisterOCR(Func<OCRInterfaces.IGPALOCR> factory) => _ocrFactory = factory;
        //public static OCRInterfaces.IGPALOCR OCR { [Component(Description = "Read text from an image, once an OCR provider is registered", Submenu = "System")] get => _ocrFactory != null
        //    ? _ocrFactory()
        //    : throw new InvalidOperationException("OCR provider not registered. Add the GenerallyPositive.OCR NuGet and call GPAL.RegisterOCR(() => new GPALOCR())."); }
 
        // what finds an image on the screen, handed in by the GPAL.Image package. Without it an image selector
        // finds nothing and says why, so GPAL itself carries none of OpenCV's weight
        internal static IImageMatcher ImageMatcher { get; private set; }
 
        [Action(Description = "Register the image matcher from the GPAL.Image package, which image selectors need")]
        public static void RegisterImageMatcher(IImageMatcher imageMatcher) => ImageMatcher = imageMatcher;
 
        internal static ImageHelper imageHelper;
        public static IImageHelper ImageHelper
        {
            [Component(Description = "Screenshots and image matching", Submenu = "System")] get
            {
                if (null == imageHelper)
                    imageHelper = new ImageHelper();
                return imageHelper;
            }
        }

        public static IAllowFileName File
        {
            [Component(Description = "A file, or several, for a step to read from or write to, such as FillInFrom or SaveTo", Submenu = "Data")]
            get
            {
                GPALFile file = new GPALFile();
                FileList.Add(file);
                return (IAllowFileName)file;
            }
        }

        public static IAllowGridActions<string> Grid
        {
            [Component(Description = "A grid of rows and columns that steps fill in from and save data into", Submenu = "Data")]
            get
            {
                IGPALGrid<string> grid = new GPALGrid<string>();
                GridList.Add(grid);
                return grid;
            }
        }

        public static IAllowLoggingSettings Logger
        {
            [Component(Description = "A logger that records the events GPAL publishes", Submenu = "System")]
            get
            {
                IGPALLogger logger = (IGPALLogger)new GPALLogger();
                LoggerList.Add(logger);
                return (IAllowLoggingSettings)logger;
            }
        }

        public static IAllowEmailServerSettings Mail
        {
            [Component(Description = "Send and receive email over SMTP, POP or IMAP", Submenu = "Services")]
            get
            {
                GPALMail mail = new GPALMail();
                MailList.Add(mail);
                return (IAllowEmailServerSettings)mail;
            }
        }

        public static IAllowConverterInput Converter
        {
            [Fluent(Description = "Convert data from one shape to another: file, grid, database, class, and the CSV, JSON, XML, YAML and Excel formats")]
            get
            {
                GPALConverter converter = new GPALConverter();
                return (IAllowConverterInput)converter;
            }
        }        

        public static IAllowApplicationOpenOrParameters Application
        {
            [Fluent(Description = "Start or attach to a desktop application and automate it")]
            get
            {
                tmpApplication = new Application.Application();
                tmpApplication.Name = applicationName + applicationCount++.ToString();
                ApplicationList.Add(tmpApplication);
                return tmpApplication;
            }
        }

        public static IAllowBrowserTypeOrGoto Browser
        {
            [Fluent(Description = "Start or attach to a browser and automate it on Selenium, Puppeteer or OttoMagic")]
            get
            {
                tmpBrowser = new Browser.Browser();
                tmpBrowser.Name = browserName + browserCount++.ToString();
 
                CheckVersions();
                
                // if we already have a browser and instantiate a new one, it MUST use the same automation engine as the first browser instantiated.
                if (0 < BrowserList.Count)
                    tmpBrowser.WithAutomationEngine(BrowserList[0].AutomationEngine);
 
                BrowserList.Add(tmpBrowser);
                tmpBrowser.BrowserSettings.MagicHelper = new GenerallyPositive.Browser.MagicHelper(tmpBrowser);   // one helper per browser, talking to that browser's port
                return tmpBrowser;
            }
        }

        public static IAllowClipboardInput Clipboard
        {
            [Component(Description = "Read or set the Windows clipboard", Submenu = "Data")]
            get
            {
                GPALClipboard clipboard = new GPALClipboard();
                return (IAllowClipboardInput)clipboard;
            }
        }
        public static IAllowDatabaseSettings Database
        {
            [Component(Description = "Read from and write to a database table or stored procedure", Submenu = "Data")]
            get
            {
                GPALDatabase database = new GPALDatabase();
                return (IAllowDatabaseSettings)database;
            }
        }
        public static IAllowSelectorSettings Selector
        {
            [Component(Description = "Describe how to find an element in a browser or an application", Submenu = "Selectors")]
            get
            {
                Selector tmpSelector = null;
                if (null != tmpBrowser)
                    tmpSelector = new Selector(tmpBrowser);
                else if (null != tmpApplication)
                    tmpSelector = new Selector(tmpApplication);
                else
                    tmpSelector = new Selector();
                tmpSelector.Name = selectorName + selectorCount++.ToString();
                SelectorList.Add(tmpSelector);
                return tmpSelector;
            }
        }

        public static IAllowRequestSettings Request
        {
            [Component(Description = "Describe an API request for Fetch to send from inside the page, carrying the session the browser already has", Submenu = "Browser")]
            get
            {
                return new GPALRequest();
            }
        }
        public static IAllowExecutableSetup Launcher
        {
            [Component(Description = "Start a program or open a document, with arguments, and optionally read what it prints", Submenu = "System")]
            get
            {
                Launcher launcher = new Launcher
                {
                    Name = executableName + executableCount++.ToString()
                };
                return launcher;
            }
 
        }
        public static IAllowRESTEndpoint RESTClient
        {
            [Component(Description = "Call a REST API: base url, endpoint, parameters and credentials", Submenu = "Services")]
            get
            {
                RESTClient restClient = new RESTClient
                {
                    Name = restClientName + restClientCount++.ToString()
                };
                return restClient;
            }
        }

        public static IAllowCredentialServiceType Credentials
        {
            [Component(Description = "Credentials from a password manager, an API key or an OAuth provider", Submenu = "Security")]
            get => new Credentials((Browser.Browser)Browser);   // TODO: CAVEAT: BUG: implement correct, this browser is a placeholder
        }
        public static IAllowGiven Gherkin
        {
            [Component(Description = "Write a workflow as Given, When and Then steps", Submenu = "System")]
            get => new Gherkin();
        }
        public static IAllowSpreadsheetSelection GoogleSheets
        {
            [Component(Description = "Read and write a Google Sheets spreadsheet", Submenu = "Google")]
            get => new GoogleSheets();
        }

        public static IAllowDriveCredentials GoogleDrive
        {
            [Component(Description = "Work with files in Google Drive", Submenu = "Google")]
            get => new GoogleDrive();
        }
        public static IGPALExcel Excel
        {
            [Component(Description = "Read and write an Excel workbook", Submenu = "Data")]
            get => new GPALExcel();
        }
        public static IAllowGPALUrlForUrl Url
        {
            [Component(Description = "A url, and the website storage on it to read or change", Submenu = "Browser")]
            get => new GPALUrl(null);
        }
 
        #region Internal GPAL factory for ActivatorHelper
        internal static GPALElement Element
        {
            get => new GPALElement();
        }
        internal static GPALFileSettings FileSettings
        {
            get => new GPALFileSettings();
        }
        internal static GPALMailSettings MailSettings
        {
            get => new GPALMailSettings();
        }
        internal static GPALSettings Settings
        {
            get => new GPALSettings();
        }
        #endregion Internal GPAL factory for ActivatorHelper
        #endregion <GPAL Objects>
        #region Shorthand Helpers
        [Component(Description = "An Excel workbook for the given file", Submenu = "Data")]
        public static IGPALExcel ExcelFor(GPALFile excelFile)
        {
            return new GPALExcel().WithFile(excelFile).ToGPALObject();
        }
 
        [Component(Description = "Credentials for the given service", Submenu = "Security")]
        public static ICredentials CredentialsFor(CredentialServiceType credentialServiceType)
        {
            return new Credentials((Browser.Browser)Browser).WithService(credentialServiceType).ToGPALObject();
        }
        [Component(Description = "A Google Sheets spreadsheet, opened by name or id", Submenu = "Google")]
        public static IGoogleSheets GoogleSheetsFor(string spreadsheetName)
        {
            return new GoogleSheets().WithSpreadsheet(spreadsheetName).ToGPALObject();
        }
        [Component(Description = "Google Drive, signed in with the given credentials", Submenu = "Google")]
        public static IGoogleDrive GoogleDriveFor(ICredentials credentials)
        {
            return new GoogleDrive().WithCredentials(credentials).ToGPALObject();
        }
        [Component(Description = "A grid whose rows are objects of the given class", Submenu = "Data")]
        public static IGPALGrid<T> GridForType<T>()
        {
            return new GPALGrid<T>();
        }
        [Component(Description = "A selector that finds an element by CSS, optionally named", Submenu = "Selectors")]
        public static Selector CssSelector(string css, string selectorName = null)
        {
            if (null != selectorName)
                return Selector.WithCSS(css).WithSelectorName(selectorName).ToGPALObject();
            else
                return Selector.WithCSS(css).ToGPALObject();
        }
 
        [Component(Description = "A selector that finds an element by XPath, optionally named", Submenu = "Selectors")]
        public static Selector XPathSelector(string xpath, string selectorName = null)
        {
            if (null != selectorName)
                return Selector.WithXPath(xpath).WithSelectorName(selectorName).ToGPALObject();
            else
                return Selector.WithXPath(xpath).ToGPALObject();
        }
        [Component(Description = "A GPALFile for the given path", Submenu = "Data")]
        public static GPALFile FileFor(string path)
        {
            return File.WithFileName(path).ToGPALObject();
        }
        // New browser shorthand methods
        [Component(Description = "Start a browser with no window on the given url", Submenu = "Browser")]
        public static IBrowser BrowserGet(GPALUrl url)
        {
            return Browser
                .Get(url) // Headless navigation
                .ToGPALObject();
 
        }
        [Component(Description = "Start a browser window on the given url", Submenu = "Browser")]
        public static IBrowser BrowserGoto(GPALUrl url)
        {
            return Browser
                .GoTo(url) // Windowed navigation
                .ToGPALObject();
        }
        [Component(Description = "A button with the given text, for a GPAL form", Submenu = "Form Controls/Buttons and Choices")]
        public static GPALButton ButtonFor(string text)
        {
            var c = new GPALButton { Name = buttonName + controlCount++.ToString() };
            c.IsDefault = false;
            c.Text = text;
            ControlList.Add(c);
            return c;
        }
        [Component(Description = "A label with the given text, for a GPAL form", Submenu = "Form Controls/Text")]
        public static GPALLabel LabelFor(string text)
        {
            var c = new GPALLabel { Name = labelName + controlCount++.ToString() };
            c.Text = text;
            ControlList.Add(c);
            return c;
        }
        [Component(Description = "Empty space this many pixels tall between two controls on a GPAL form", Submenu = "Form Controls/Layout")]
        public static GPALSpacer SpacerFor(int pixels)
        {
            var c = new GPALSpacer { Name = spacerName + controlCount++.ToString() };
            c.Height = pixels;
            ControlList.Add(c);
            return c;
        }
        [Component(Description = "A link for a GPAL form that opens this address in the default browser, showing the address as its text", Submenu = "Form Controls/Text")]
        public static GPALLinkLabel LinkLabelFor(string url)
        {
            var c = new GPALLinkLabel { Name = linkLabelName + controlCount++.ToString() };
            c.Url = url;
            c.Text = url;
            ControlList.Add(c);
            return c;
        }
        [Component(Description = "A one-line input box for a GPAL form, optionally with starting text", Submenu = "Form Controls/Text")]
        public static GPALInput InputFor(string text = "")
        {
            var c = new GPALInput { Name = inputName + controlCount++.ToString() };
            c.Text = text;
            ControlList.Add(c);
            return c;
        }
        [Component(Description = "A multi-line text box for a GPAL form, optionally with starting text", Submenu = "Form Controls/Text")]
        public static GPALTextArea TextAreaFor(string text = "")
        {
            var c = new GPALTextArea { Name = textAreaName + controlCount++.ToString() };
            c.Text = text;
            ControlList.Add(c);
            return c;
        }
        [Component(Description = "A rich text box for a GPAL form that renders Markdown, optionally with starting text", Submenu = "Form Controls/Text")]
        public static GPALRichTextBox RichTextBoxFor(string text = "")
        {
            var c = new GPALRichTextBox { Name = richTextBoxName + controlCount++.ToString() };
            c.Text = text;
            ControlList.Add(c);
            return c;
        }
        [Component(Description = "A checkbox with the given text, for a GPAL form, checked or not", Submenu = "Form Controls/Buttons and Choices")]
        public static GPALCheckbox CheckboxFor(string text, bool isChecked = false)
        {
            var c = new GPALCheckbox { Name = checkboxName + controlCount++.ToString() };
            c.Text = text;
            c.IsChecked = isChecked;
            ControlList.Add(c);
            return c;
        }
        [Component(Description = "A radio button with the given text, for a GPAL form, selected or not", Submenu = "Form Controls/Buttons and Choices")]
        public static GPALRadioButton RadioButtonFor(string text, bool isChecked = false)
        {
            var c = new GPALRadioButton { Name = radioButtonName + controlCount++.ToString() };
            c.Text = text;
            c.IsChecked = isChecked;
            ControlList.Add(c);
            return c;
        }
        [Component(Description = "A tab with the given title, for a GPAL form", Submenu = "Form Controls/Layout")]
        public static GPALTab TabFor(string text)
        {
            var c = new GPALTab { Name = radioButtonName + controlCount++.ToString() };
            c.Text = text;
            ControlList.Add(c);
            return c;
        }
        [Component(Description = "A chart for a GPAL form, optionally with a title", Submenu = "Form Controls/Lists and Data")]
        public static GPALChart ChartFor(string title = "")
        {
            var c = new GPALChart { Name = chartName + controlCount++.ToString() };
            if (!string.IsNullOrEmpty(title)) c.WithTitle(title);
            ControlList.Add(c);
            return c;
        }
        [Component(Description = "A drop-down list with the given items, for a GPAL form", Submenu = "Form Controls/Buttons and Choices")]
        public static GPALComboBox ComboBoxFor(params string[] items)
        {
            var c = new GPALComboBox { Name = "ComboBox" + controlCount++.ToString() };
            if (items != null && items.Length > 0) c.WithItems(items);
            return c;
        }
        [Component(Description = "A data grid with the given columns, for a GPAL form", Submenu = "Form Controls/Lists and Data")]
        public static GPALDataGridView DataGridViewFor(params string[] columns)
        {
            var c = new GPALDataGridView { Name = "DataGridView" + controlCount++.ToString() };
            if (columns != null && columns.Length > 0) c.WithColumns(columns);
            return c;
        }
        [Component(Description = "A list view with the given columns, for a GPAL form", Submenu = "Form Controls/Lists and Data")]
        public static GPALListView ListViewFor(params string[] columns)
        {
            var c = new GPALListView { Name = "ListView" + controlCount++.ToString() };
            if (columns != null && columns.Length > 0) c.WithColumns(columns);
            return c;
        }
        [Component(Description = "A picture box showing the given image file, for a GPAL form", Submenu = "Form Controls/Lists and Data")]
        public static GPALPicture PictureFor(GPALFile file)
        {
            var c = new GPALPicture { Name = "Picture" + controlCount++.ToString() };
            c.WithImage(file);
            return c;
        }
        [Component(Description = "A slider from 0 to the given maximum, for a GPAL form", Submenu = "Form Controls/Buttons and Choices")]
        public static GPALSlider SliderFor(int maximum = 100)
        {
            var c = new GPALSlider { Name = "Slider" + controlCount++.ToString() };
            c.WithMaximum(maximum);
            return c;
        }
        [Component(Description = "A progress bar from 0 to the given maximum, for a GPAL form", Submenu = "Form Controls/Lists and Data")]
        public static GPALProgressBar ProgressBarFor(int maximum = 100)
        {
            var c = new GPALProgressBar { Name = "ProgressBar" + controlCount++.ToString() };
            c.WithMaximum(maximum);
            return c;
        }
        [Component(Description = "A status strip with the given text, for a GPAL form", Submenu = "Form Controls/Menus and Bars")]
        public static GPALStatusStrip StatusStripFor(string text = "Ready")
        {
            var c = new GPALStatusStrip { Name = "StatusStrip" + controlCount++.ToString() };
            c.Text = text;
            return c;
        }
        [Component(Description = "A number box held between the given minimum and maximum, for a GPAL form", Submenu = "Form Controls/Buttons and Choices")]
        public static GPALNumericUpDown NumericUpDownFor(decimal minimum = 0, decimal maximum = 100)
        {
            var c = new GPALNumericUpDown { Name = "NumericUpDown" + controlCount++.ToString() };
            c.WithMinimum(minimum);
            c.WithMaximum(maximum);
            return c;
        }
        [Component(Description = "A date and time picker for a GPAL form, optionally set to a value", Submenu = "Form Controls/Buttons and Choices")]
        public static GPALDateTimePicker DateTimePickerFor(DateTime? value = null)
        {
            var c = new GPALDateTimePicker { Name = "DateTimePicker" + controlCount++.ToString() };
            if (value.HasValue) c.WithValue(value.Value);
            return c;
        }
        [Component(Description = "An empty tree view for a GPAL form", Submenu = "Form Controls/Lists and Data")]
        public static GPALTreeView TreeViewFor()
        {
            return new GPALTreeView { Name = "TreeView" + controlCount++.ToString() };
        }
        [Component(Description = "A file or folder picker with the given dialog title, for a GPAL form", Submenu = "Form Controls/Buttons and Choices")]
        public static GPALFileSelector FileSelectorFor(string title = "Select File/Folder")
        {
            var c = new GPALFileSelector { Name = "FileSeleector" + controlCount++.ToString() };
            c.WithTitle(title);
            return c;
        }
        [Component(Description = "A layout panel with the given columns and rows, for a GPAL form", Submenu = "Form Controls/Layout")]
        public static GPALTableLayoutPanel TableLayoutPanelFor(int columns = 1, int rows = 1)
        {
            var c = new GPALTableLayoutPanel { Name = "TableLayoutPanel" + controlCount++.ToString() };
            c.WithColumnCount(columns);
            c.WithRowCount(rows);
            return c;
        }
        #endregion Shorthand Helpers
        #region <ElementAssitant>
        [ElementAssitant(Description = "Work with the elements a browser selector found, from inside a callback")]
        public static Browser.IAllowElementSetting ElementAssistant(Selector selector)
        {
            elementAssistant.Browser = selector.Browser;
            elementAssistant.ForSelector(selector);
            return elementAssistant;
        }

        [ElementAssitant(Description = "Work with the elements an application selector found, from inside a callback")]
        public static Application.IAllowForSelector ElementAssistant(Application.Application application)
        {
            applicationElementAssistant.Application = application;
            return applicationElementAssistant;
        }
        #endregion <ElementAssitant>
        #region <Form Controls>
        public static IAllowFormSettings Form
        {
            [Fluent(Description = "Build a form of controls to give a workflow a user interface")]
            get
            {
                GPALForm.GPALForm tmpForms = new GPALForm.GPALForm()
                {
                    FormName = formName + formCount++.ToString(),
                };
                FormList.Add(tmpForms);
                return tmpForms;
            }
        }

        public static IAllowControlSettingsAndDefault Button
        {
            [Forms(Description = "A button for a GPAL form, calling back when it is clicked", Submenu = "Buttons and Choices")]
            get
            {
                GPALButton tmpControl = new GPALButton
                {
                    Name = buttonName + controlCount++.ToString(),
                    IsDefault = false
                };
                //CAVEAT: very strange bug, isdefault keeps getting set to true
                tmpControl.IsDefault = false;
                ControlList.Add(tmpControl);
                return tmpControl;
            }
        }

        public static IAllowControlSettingsAndChartSettings Chart
        {
            [Forms(Description = "A chart for a GPAL form", Submenu = "Lists and Data")]
            get
            {
                GPALChart tmpControl = new GPALChart
                {
                    Name = chartName + controlCount++.ToString()
                };
                ControlList.Add(tmpControl);
                return tmpControl;
            }
        }

        public static IAllowControlSettingsAndChecked Checkbox
        {
            [Forms(Description = "A checkbox for a GPAL form, calling back when it is checked or cleared", Submenu = "Buttons and Choices")]
            get
            {
                GPALCheckbox tmpControl = new GPALCheckbox
                {
                    Name = checkboxName + controlCount++.ToString()
                };
                ControlList.Add(tmpControl);
                return tmpControl;
            }
        }

        public static IAllowComboBoxControlSettings ComboBox
        {
            [Forms(Description = "Instantiates a new GPALComboBox for use on a GPAL form", Submenu = "Buttons and Choices")] get
            {
                GPALComboBox tmpControl = new GPALComboBox
                {
                    Name = "ComboBox" + controlCount++.ToString()   // or use your naming scheme
                };
                // ControlList.Add(tmpControl);   ← usually done in WithFormControl / AddComboBox
                return tmpControl;
            }
        }

        public static IAllowDataGridViewControlSettings DataGridView
        {
            [Forms(Description = "Instantiates a new GPALDataGridView for use on a GPAL form", Submenu = "Lists and Data")] get
            {
                GPALDataGridView tmp = new GPALDataGridView
                {
                    Name = "DataGridView" + controlCount++.ToString()
                };
                return tmp;
            }
        }

        public static IAllowDateTimePickerControlSettings DateTimePicker
        {
            [Forms(Description = "Instantiates a new GPALDateTimePicker for use on a GPAL form", Submenu = "Buttons and Choices")] get
            {
                GPALDateTimePicker tmp = new GPALDateTimePicker
                {
                    Name = "DateTimePicker" + controlCount++.ToString()
                };
                return tmp;
            }
        }

        public static IAllowFileSelectorControlSettings FileSelector
        {
            [Forms(Description = "Instantiates a new GPALFileSelector for use on a GPAL form", Submenu = "Buttons and Choices")] get
            {
                GPALFileSelector gfs = new GPALFileSelector
                {
                    Name = "FileSeleector" + controlCount++.ToString()
                };
                return gfs;
            }
        }

        public static IAllowControlSettingsPlaceholderAndPassword Input
        {
            [Forms(Description = "A one-line input box for a GPAL form, calling back when its text changes", Submenu = "Text")]
            get
            {
                GPALInput tmpControl = new GPALInput
                {
                    Name = inputName + controlCount++.ToString()
                };
                ControlList.Add(tmpControl);
                return tmpControl;
            }
        }

        public static IAllowControlSettingsAndUrl LinkLabel
        {
            [Forms(Description = "A link for a GPAL form that opens an address in the default browser", Submenu = "Text")]
            get
            {
                GPALLinkLabel tmpControl = new GPALLinkLabel
                {
                    Name = linkLabelName + controlCount++.ToString()
                };
                ControlList.Add(tmpControl);
                return tmpControl;
            }
        }

        public static IAllowControlSettingsAndFontSettings Label
        {
            [Forms(Description = "A label for a GPAL form", Submenu = "Text")]
            get
            {
                GPALLabel tmpControl = new GPALLabel
                {
                    Name = labelName + controlCount++.ToString()
                };
                ControlList.Add(tmpControl);
                return tmpControl;
            }
        }

        public static IAllowListViewControlSettings ListView
        {
            [Forms(Description = "Instantiates a new GPALListView for use on a GPAL form", Submenu = "Lists and Data")] get
            {
                GPALListView tmp = new GPALListView
                {
                    Name = "ListView" + controlCount++.ToString()
                };
                return tmp;
            }
        }

        public static IAllowNumericUpDownControlSettings NumericUpDown
        {
            [Forms(Description = "Instantiates a new GPALNumericUpDown for use on a GPAL form", Submenu = "Buttons and Choices")] get
            {
                GPALNumericUpDown tmp = new GPALNumericUpDown
                {
                    Name = "NumericUpDown" + controlCount++.ToString()
                };
                return tmp;
            }
        }

        public static IAllowPictureControlSettings Picture
        {
            [Forms(Description = "A picture control for GPAL forms", Submenu = "Lists and Data")] get
            {
                GPALPicture tmp = new GPALPicture
                {
                    Name = "Picture" + controlCount++.ToString()
                };
                return tmp;
            }
        }

        public static IAllowSliderControlSettings Slider
        {
            [Forms(Description = "A slider control for GPAL forms", Submenu = "Buttons and Choices")] get
            {
                GPALSlider tmp = new GPALSlider
                {
                    Name = "Slider" + controlCount++.ToString()
                };
                return tmp;
            }
        }

        public static IAllowProgressBarControlSettings ProgressBar
        {
            [Forms(Description = "A progress bar control for GPAL forms", Submenu = "Lists and Data")] get
            {
                GPALProgressBar tmp = new GPALProgressBar
                {
                    Name = "ProgressBar" + controlCount++.ToString()
                };
                return tmp;
            }
        }

        public static IAllowControlSettingsAndChecked RadioButton
        {
            [Forms(Description = "A radio button for a GPAL form, calling back when it is selected", Submenu = "Buttons and Choices")]
            get
            {
                GPALRadioButton tmpControl = new GPALRadioButton
                {
                    Name = radioButtonName + controlCount++.ToString()
                };
                ControlList.Add(tmpControl);
                return tmpControl;
            }
        }

        public static IAllowStatusStripControlSettings StatusStrip
        {
            [Forms(Description = "A status strip control (docked at the bottom) for GPAL forms", Submenu = "Menus and Bars")] get
            {
                GPALStatusStrip tmp = new GPALStatusStrip
                {
                    Name = "StatusStrip" + controlCount++.ToString()
                };
                return tmp;
            }
        }

        public static IAllowMenuBarControlSettings MenuBar
        {
            [Forms(Description = "A menu bar docked to the top of a GPAL form", Submenu = "Menus and Bars")] get
            {
                GPALMenuBar tmp = new GPALMenuBar
                {
                    Name = "MenuBar" + controlCount++.ToString()
                };
                return tmp;
            }
        }

        public static IAllowBarItemSettings BarItem
        {
            [Forms(Description = "A single item shared by menu bars and toolbars: text, optional image, optional shortcut key, and a callback wired to its click", Submenu = "Menus and Bars")] get
            {
                GPALBarItem tmp = new GPALBarItem
                {
                    Name = "BarItem" + controlCount++.ToString()
                };
                return tmp;
            }
        }

        public static IAllowToolbarControlSettings Toolbar
        {
            [Forms(Description = "A toolbar docked below the menu bar, holding GPAL.BarItem buttons and optional separators", Submenu = "Menus and Bars")] get
            {
                GPALToolbar tmp = new GPALToolbar
                {
                    Name = "Toolbar" + controlCount++.ToString()
                };
                return tmp;
            }
        }

        public static IAllowControlSettings Tab
        {
            [Forms(Description = "A tab page for a GPAL form", Submenu = "Layout")]
            get
            {
                GPALTab tmpControl = new GPALTab
                {
                    Name = radioButtonName + controlCount++.ToString()
                };
                ControlList.Add(tmpControl);
                return tmpControl;
            }
        }

        public static IAllowSplitterControlSettings Splitter { [Forms(Description = "Instantiates a new GPALSplitter for use on a GPAL form: two panes with a bar between them, built whole and then laid out like any other control", Submenu = "Layout")] get => new GPALSplitter(); }

        public static IAllowGroupBoxControlSettings GroupBox { [Forms(Description = "Instantiates a new GPALGroupBox for use on a GPAL form: a titled box around a set of controls, laid out like any other control", Submenu = "Layout")] get => new GPALGroupBox(); }

        public static GPALSpliter SplitRight { [Forms(Description = "Marks the end of a splitter's left pane", Submenu = "Layout")] get => new GPALSpliter(); }

        public static GPALSpliter SplitBottom { [Forms(Description = "Marks the end of a splitter's top pane", Submenu = "Layout")] get => new GPALSpliter(); }

        public static IAllowControlSettingsAndPlaceholder TextArea
        {
            [Forms(Description = "A multi-line text box for a GPAL form, calling back when its text changes", Submenu = "Text")]
            get
            {
                GPALTextArea tmpControl = new GPALTextArea
                {
                    Name = textAreaName + controlCount++.ToString()
                };
                ControlList.Add(tmpControl);
                return tmpControl;
            }
        }

        public static IAllowRichTextBoxControlSettings RichTextBox
        {
            [Forms(Description = "A rich text box for a GPAL form that renders Markdown", Submenu = "Text")]
            get
            {
                GPALRichTextBox tmpControl = new GPALRichTextBox
                {
                    Name = richTextBoxName + controlCount++.ToString()
                };
                ControlList.Add(tmpControl);
                return tmpControl;
            }
        }

        public static IAllowTreeViewControlSettings TreeView
        {
            [Forms(Description = "Instantiates a new GPALTreeView for use on a GPAL form", Submenu = "Lists and Data")] get
            {
                GPALTreeView tmp = new GPALTreeView
                {
                    Name = "TreeView" + controlCount++.ToString()
                };
                return tmp;
            }
        }
        #endregion <Form Controls>
        #region <Getters/Setters>
        public static bool UseHardware
        {
            [GPALSettings(Description = "Whether GPAL uses the real mouse and keyboard by default")] get => gpalSettings.UseHardware;
        }
        public static bool UseJavaSCript
        {
            [GPALSettings(Description = "Whether GPAL interacts through injected JavaScript by default")] get => gpalSettings.UseJavaScript;
        }

        public static Browser.IAllowScheduledWorkflow Workflow
        {
            [Component(Description = "Run whole workflows at once, each owning the browser or application it drives", Submenu = "System")]
            get
            {
                return new Browser.WorkflowScheduler();
            }
        }

        public static Browser.IHiddenDesktops HiddenDesktop
        {
            [Component(Description = "The hidden desktops this program made, to peek at, return from or close", Submenu = "System")]
            get
            {
                return new Browser.GPALHiddenDesktops();
            }
        }
        public static string Version
        {
            [Data(Description = "The version of GPAL that is running")] get => GPALSettings.Version;
        }
        public static string OAuthTokenUrl
        {
            [Data(Description = "Where an OAuth redirect lands and the token is read back from, e.g. http://localhost:3117/")] get
            {
                return gpalSettings.OAuthTokenUrl;
            }
            set
            {
                gpalSettings.OAuthTokenUrl = value;
            }
        }
        internal static List<IGPALLogger> PublishToLoggers
        {
            get
            {
                return GPALSettings.PublishToLoggers;
            }
        }
        // The text area set by WithPublishToControl, or null
        internal static GPALTextArea PublishControl
        {
            get
            {
                return GPALSettings.PublishControl;
            }
        }
 
        // Rolling line cap, so a long run does not grow the control without bound
        private const int PublishControlMaxLines = 2_000;
 
        internal static bool PublishToConsole
        {
            get
            {
                return GPALSettings.PublishToConsole;
            }
            set
            {
                GPALSettings.PublishToConsole = value;
            }
        }
        internal static bool PublishToDebug
        {
            get
            {
                return GPALSettings.PublishToDebug;
            }
        }
        internal static GPALEventType ConsoleEvents
        {
            get => GPALSettings.ConsoleEvents;
            set => GPALSettings.ConsoleEvents = value;
        }
        internal static GPALEventType DebugEvents
        {
            get => GPALSettings.DebugEvents;
        }
        internal static bool PublishStackTrace
        {
            get
            {
                return GPALSettings.PublishStackTrace;
            }
        }
        internal static string ErrorPlaceholder
        {
            get
            {
                return GPALSettings.ErrorPlaceholder;
            }
        }
        internal static string DriverLocation
        {
            get
            {
                return GPALSettings.DriverLocation;
            }
        }
        internal static bool SimulateMouse
        {
            get
            {
                return GPALSettings.SimulateMouse;
            }
        }
        internal static string TempProfileDirectory
        {
            get
            {
                return GPALSettings.TempProfileDirectory;
            }
        }
        internal static List<Browser.Browser> Browsers
        {
            get
            {
                return BrowserList;
            }
        }
        internal static int MatchingPercentage
        {
            get
            {
                return GPALSettings.MatchingPercentage;
            }
        }
        internal static int TypingDelay
        {
            get
            {
                return GPALSettings.TypingDelay;
            }
        }
        internal static bool StopOnNotFound
        {
            get
            {
                return GPALSettings.StopOnNotFound;
            }
        }
        internal static bool NoFallbackRecoveryActions
        {
            get
            {
                return gpalSettings.NoFallbackRecoveryActions;
            }
        }
        #endregion <Getters/Setters>
        #region <Helpers>
        [Helper(Description = "Load GPAL's settings from GPAL.yaml or the given file, creating it with the defaults if it is missing")]
        public static void LoadSettings(GPALFile settingsFile = null)
        {
            bool hold = GPAL.PublishToConsole;
            GPALEventType events = GPAL.GPALSettings.ConsoleEvents;
 
            try
            {
                if (settingsFile != null)
                {
                    _settingsFilePath = settingsFile.Filenames[0];
                    SettingsLoaded = false;
                }
 
                if (false == SettingsLoaded)
                {
                    SettingsLoaded = true;
                    string currentVersion = System.Reflection.Assembly.GetExecutingAssembly().GetName().Version.ToString();
                    GPALFile resolvedFile = _settingsFilePath;
 
                    if (true == System.IO.File.Exists(resolvedFile.Filenames[0]))
                    {
                        // load setting which contains default events to publish
                        GPAL.Converter.WithInput(resolvedFile).SaveTo(ref gpalSettings);
 
                        hold = GPAL.PublishToConsole;
                        events = GPAL.GPALSettings.ConsoleEvents;
 
                        // NOTE: CAVEAT: WE CANNOT EVER send anything on stdio when we are running as a browser Native App - that will disconnect it as garbage received
                        if ("1" == Environment.GetEnvironmentVariable("GPAL_IS_SILENT"))
                            GPAL.PublishToConsole = false;
 
                        GPAL.PublishSimpleEvent(GPALEventType.INFO, $"[{resolvedFile.Filenames[0]}] loaded, using settings.", gpalSettings, GPALObjectType.Other);
 
                        if (false == gpalSettings.Version.Equals(currentVersion))
                        {
                            GPAL.PublishSimpleEvent(GPALEventType.INFO, $"[{resolvedFile.Filenames[0]}] updated to current GPAL version [{currentVersion}].", gpalSettings, GPALObjectType.Other);
                            gpalSettings.Version = currentVersion;
                            SaveSettings();
                        }
                    }
                    else    // if file doesn't exist, initialize default settings and save a settings file, the user can then tweak those settings for next run/load
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"[{resolvedFile.Filenames[0]}] does not exist. Using default settings and creating GPAL.yaml.", gpalSettings, GPALObjectType.Other);
                        SaveSettings();
                    }
                }
 
                AIProvidersConfig.TryAutoLoad();
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"[{_settingsFilePath}] load error. Try deleting it and restarting.", gpalSettings, GPALObjectType.Other, ex);
            }
            finally
            {
                GPAL.PublishToConsole = hold;
                GPAL.GPALSettings.ConsoleEvents = events;
            }
        }
        [Helper(Description = "Save GPAL's current settings to GPAL.yaml or the given file")]
        public static void SaveSettings(GPALFile settingsFile = null)
        {
            if (settingsFile != null) _settingsFilePath = settingsFile.Filenames[0];
            GPAL.Converter.WithInput(GPALSettings).SaveTo((GPALFile)_settingsFilePath);
        }
        [Helper(Description = "Take a screenshot and keep it on the browser's settings")]
        public static IAllowGraphicSettings CaptureScreen(Browser.IBrowser browser)
        {
            ((ImageHelper)GPAL.ImageHelper).CaptureScreen(browser).ToBitmap(out ((Browser.Browser)browser).BrowserSettings.ScreenShot);
 
            return ImageHelper;
        }

        // https://stackoverflow.com/questions/44153/can-you-use-reflection-to-find-the-name-of-the-currently-executing-method/67372375#67372375
        [MethodImpl(MethodImplOptions.NoInlining)]
        [Helper(Description = "The name of the method that called it, for event messages")]
        public static string MyMethodName()
        {
            var st = new StackTrace();
            var sf = st.GetFrame(1);
            string name = sf.GetMethod().Name;
 
            if (name.Equals("MoveNext"))
            {
                // We're inside an async method
                name = sf.GetMethod().ReflectedType.Name
                         .Split(new char[] { '<', '>' }, StringSplitOptions.RemoveEmptyEntries)[0];
            }
 
            return name;
        }

        [MethodImpl(MethodImplOptions.NoInlining)]
        [Helper(Description = "Publish an event to the information or exception handlers")]
        public static void PublishSimpleEvent(GPALEventType gPALEventType, string msg, dynamic gPALObject = null, Enums.GPALObjectType gPALObjectType = GPALObjectType.None, Exception ex = null)
        {
            // Early-out BEFORE the costly new StackTrace()/reflection below: skip entirely when no sink will
            // consume this event level. Console/Debug are level-masked here (ConsoleEvents/DebugEvents), so a
            // high-volume low level like DEEPDEBUG no longer pays for a full stack capture when it is not in the
            // Each destination is tested against its own mask. Masked-out events return below before the
            // StackTrace is taken, which is most of the cost of a published event
            // Decided once and used for both the mask and the handler, which have to agree. An event belongs
            // to the exception channel when it carries an exception or is typed EXCEPTION
            bool toExceptionChannel = null != ex || true == gPALEventType.HasFlag(GPALEventType.EXCEPTION);
 
            // Tested per handler, so an event bound for one is not published when only the other is attached
            bool handlerWants = true == toExceptionChannel
                              ? null != ExceptionHandler && gpalSettings.ExceptionHandlerEvents.HasFlag(gPALEventType)
                              : null != InformationHandler && gpalSettings.InformationHandlerEvents.HasFlag(gPALEventType);
            bool consoleWants = true == GPAL.PublishToConsole && gpalSettings.ConsoleEvents.HasFlag(gPALEventType);
            bool debugWants = true == GPAL.PublishToDebug && gpalSettings.DebugEvents.HasFlag(gPALEventType);
            bool controlWants = null != GPAL.PublishControl && gpalSettings.ControlEvents.HasFlag(gPALEventType);
            bool loggerWants = 0 < GPAL.PublishToLoggers.Count;
 
            if (false == handlerWants && false == consoleWants && false == debugWants && false == controlWants && false == loggerWants)
                return;
 
            if (true == handlerWants || true == controlWants || true == consoleWants || true == debugWants || true == loggerWants)
            {
                var st = new StackTrace();
                var sf = st.GetFrame(1);
                string name = sf.GetMethod().Name;
                DateTime dateTime = DateTime.Now;
                string stackTrace = null != ex && true == GPAL.PublishStackTrace ? $"[{ex.StackTrace}]" : string.Empty;
 
                if (name.Equals("MoveNext"))
                {
                    // We're inside an async method
                    name = sf.GetMethod().ReflectedType.Name
                             .Split(new char[] { '<', '>' }, StringSplitOptions.RemoveEmptyEntries)[0];
                }
 
                // padded inside the tag to the length of WARNING, CAUTION and FAILURE, so the method names line up down
                // the log. EXCEPTION and DEEPDEBUG run two past it, which makes an exception easy to spot
                string outMessage = $"[{dateTime.ToString("yyyy-MM-dd HH:mm:ss.ffff")}][{gPALEventType,-7}][{name}]: {msg}";
                Bitmap ss = null;
 
                // NOTE: we now only capture a screen image on error or exception
                if (GPALEventType.ERROR == gPALEventType || GPALEventType.EXCEPTION == gPALEventType)
                    if (false == inPublishEvent && false == handlingTermination)
                    {
                        try
                        {
                            inPublishEvent = true;  // avoid reentrant calls from events published in different paths calling capture screen
                            if (true == gpalSettings.TakeEventScreenshot)
                                if (typeof(Browser.Browser) == gPALObject?.GetType())
                                    ((ImageHelper)GPAL.ImageHelper).CaptureScreen(gPALObject).ToBitmap(out ss);
                                else
                                    ((ImageHelper)GPAL.ImageHelper).CaptureScreen().ToBitmap(out ss);
                        }
                        catch // (Exception ex2)
                        {
                            //    Console.WriteLine($"Unable to get screenshot in PublishSimpleEvent. [{ex2.Message}]");
                            //    Debug.WriteLine($"Unable to get screenshot in PublishSimpleEvent. [{ex2.Message}]");
                            // if we are using ottomagic, nothing will be started up to call capture-visible-tab, so ignore
                        }
                        finally
                        {
                            inPublishEvent = false;
                        }
                    }
 
                GPALEventArgs args = new GPALEventArgs()
                {
                    GPALEventType = gPALEventType,
                    GPALObject = gPALObject,
                    GPALObjectType = gPALObjectType,
                    CurrentUOW = (Enums.GPALObjectType.UnitOfWork == gPALObjectType ? (UnitOfWork)gPALObject : null),
                    Message = $"{name}: {msg}",
                    ScreenShot = ss,
                    ExceptionRaised = ex,
                    Data = (Enums.GPALObjectType.Converter == gPALObjectType ? gPALObject : string.Empty),
                    DateTimeStamp = dateTime
                };
 
                // Same mask as the early-out above
                if (true == handlerWants)
                {
                    if (true == toExceptionChannel)
                        ExceptionHandler?.Invoke(gPALObject, args);
                    else
                        InformationHandler?.Invoke(gPALObject, args);
                }
 
                if (true == controlWants)
                {
                    GPAL.PublishControl.AppendLine(outMessage, PublishControlMaxLines);
 
                    // Exception text on a second line, under the same DEBUG rule the console below uses
                    if (null != ex && true == gpalSettings.ControlEvents.HasFlag(GPALEventType.DEBUG))
                        GPAL.PublishControl.AppendLine($"[{ex.Message}]{stackTrace}", PublishControlMaxLines);
                }
 
                if (true == GPAL.PublishToConsole)
                {
                    // NOTE: silent init is used by gpal rest api, we must never output anything on stdio
                    if (gpalSettings.ConsoleEvents.HasFlag(gPALEventType) && Environment.GetEnvironmentVariable("GPAL_IS_SILENT") != "1")
                    {
                        Console.WriteLine(outMessage);
 
                        // the exception text and its stack trace are diagnostics, not the event. Our message already
                        // says what failed, so turn DEBUG on when you also need to know how it failed underneath
                        if (null != ex && gpalSettings.ConsoleEvents.HasFlag(GPALEventType.DEBUG))
                            Console.WriteLine($"[{ex.Message}]{stackTrace}");
                    }
                }
 
                if (true == GPAL.PublishToDebug)
                {
                    if (gpalSettings.DebugEvents.HasFlag(gPALEventType) && Environment.GetEnvironmentVariable("GPAL_IS_SILENT") != "1")
                    {
                        Debug.WriteLine(outMessage);
 
                        // see the console block above: exception text and stack trace ride on DEBUG
                        if (null != ex && gpalSettings.DebugEvents.HasFlag(GPALEventType.DEBUG))
                            Debug.WriteLine($"[{ex.Message}]{stackTrace}");
                    }
                }
 
                // the logger decides where this lands, a file or a database, and whether it wants this type at
                // all. the event's own type is handed over so the entry is labelled with what actually happened.
                // guarded because the logger's write publishes events of its own, and those would arrive straight
                // back here
                if (0 < GPAL.PublishToLoggers.Count && true == Enum.TryParse(gPALEventType.ToString(), out Enums.LogType logType))   // Enums. because selenium has a LogType too
                {
                    if (null == loggersWriting)
                        loggersWriting = new HashSet<IGPALLogger>();
 
                    // a copy, because a logger raising an event while it writes could attach another one
                    foreach (IGPALLogger logger in GPAL.PublishToLoggers.ToList())
                    {
                        // this one is already writing, so this event is one it raised itself. handing it back is
                        // how a logger feeds itself its own failures. every other logger still gets it: a
                        // database that will not take a row says nothing about a file that will
                        if (true == loggersWriting.Contains(logger))
                            continue;
 
                        try
                        {
                            loggersWriting.Add(logger);
 
                            // through the class rather than the interface: Log is not something a workflow calls
                            // any more, it is how an event becomes an entry
                            GPALLogger writer = (GPALLogger)logger;
 
                            // the type goes in with the entry rather than being set on the logger first, so two
                            // threads publishing at once cannot swap each other's severity between the calls
                            writer.Log(msg, name, logType);
 
                            // the exception text rides on DEBUG here the same way it does in the console and
                            // debug blocks above, so a logger that only wants exceptions is not handed them.
                            // without it an EXCEPTION entry says what failed and never why, and a log file is
                            // the only account of a run nobody watched
                            if (null != ex)
                                writer.Log($"[{ex.Message}]{stackTrace}", name, Enums.LogType.DEBUG);
                        }
                        catch
                        {
                            // one logger that cannot write is not the others' problem, and not worth the run
                        }
                        finally
                        {
                            loggersWriting.Remove(logger);
                        }
                    }
                }
 
                // flush any pending output, following operations may block or delay output
                // also flush for user who might be outputting and not realizing they need to flush output. :)
                if (Environment.GetEnvironmentVariable("GPAL_IS_SILENT") != "1")
                {
                    Console.Out.Flush();
                    Debug.Flush();
                }
            }
        }

        public static void EmitTable<TRow, TCol, TValue>(
            string title,
            IDictionary<(TRow row, TCol col), TValue> data,
            string cornerLabel = "",
            Func<TValue, string> formatCell = null,
            string emptyCell = "-")
        {
            if (null == data || 0 == data.Count)
                return;
 
            formatCell = formatCell ?? (v => v?.ToString() ?? string.Empty);
 
            var rows = data.Keys.Select(k => k.row).Distinct().OrderBy(r => r, Comparer<TRow>.Default).ToList();
            var cols = data.Keys.Select(k => k.col).Distinct().OrderBy(c => c, Comparer<TCol>.Default).ToList();
 
            string Cell(TRow r, TCol c) => data.TryGetValue((r, c), out var v) ? formatCell(v) : emptyCell;
 
            int rowHeaderWidth = cornerLabel.Length;
            foreach (var r in rows)
                rowHeaderWidth = Math.Max(rowHeaderWidth, (r?.ToString() ?? string.Empty).Length);
 
            var colWidth = new Dictionary<TCol, int>();
            foreach (var c in cols)
            {
                int w = (c?.ToString() ?? string.Empty).Length;
                foreach (var r in rows)
                    w = Math.Max(w, Cell(r, c).Length);
                colWidth[c] = w;
            }
 
            var sb = new StringBuilder();
            sb.AppendLine();
            sb.AppendLine($"=== {title} ===");
 
            sb.Append(cornerLabel.PadRight(rowHeaderWidth));
            foreach (var c in cols)
                sb.Append(" | " + (c?.ToString() ?? string.Empty).PadRight(colWidth[c]));
            sb.AppendLine();
 
            sb.Append(new string('-', rowHeaderWidth));
            foreach (var c in cols)
                sb.Append("-+-" + new string('-', colWidth[c]));
            sb.AppendLine();
 
            foreach (var r in rows)
            {
                sb.Append((r?.ToString() ?? string.Empty).PadRight(rowHeaderWidth));
                foreach (var c in cols)
                    sb.Append(" | " + Cell(r, c).PadRight(colWidth[c]));
                sb.AppendLine();
            }
 
            // NOTICE rather than INFO: a table is something the workflow asked to be shown, not GPAL narrating
            // itself, so it belongs with the workflow's own output and survives a subscription that excludes ours
            PublishSimpleEvent(GPALEventType.NOTICE, sb.ToString());
        }

        public static void EmitRuntimeTable(string title, IDictionary<(BrowserType bt, AutomationEngine ae), TimeSpan> runtimes)
            => EmitTable(title + " runtime (min:sec.ms)", runtimes, "Browser",
                         ts => $"{(int)ts.TotalMinutes}:{ts.Seconds:D2}.{ts.Milliseconds:D3}");
        [GPALSettings(Description = "Global Browser CallIfFound handler called for every selector in every Unit of Work")]
        #endregion <Helpers>
        #region <GPAL Settings>
        // due to the fluent nature, we have to return an object with the interface IAllowGPALSettings
        // these are implemented in GPAL but also in GPALSettings, the object we chain to
        // but we want our language syntax to start with GPAL.
        // and then chain quietly, from GPAL to GPALSettings.
        // Problem is static classes cannot inherit interfaces, so we have to return the setting object.

        public static IAllowGPALSettings AppCallIfFound(Application.Application.CallIfDelegate callIfFound)
        {
            gpalSettings.AppCallIfFoundList.Add(callIfFound);
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Global Browser CallIfNotFound handler called for every selector in every Unit of Work")]
        public static IAllowGPALSettings AppCallIfNotFound(Application.Application.CallIfDelegate callIfNotFound)
        {
            gpalSettings.AppCallIfNotFoundList.Add(callIfNotFound);
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Global Browser CallIfFound handler called for every selector in every Unit of Work")]
        public static IAllowGPALSettings CallIfFound(Browser.Browser.CallIfDelegate callIfFound)
        {
            gpalSettings.CallIfFoundList.Add(callIfFound);
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Global Browser CallIfNotFound handler called for every selector in every Unit of Work")]
        public static IAllowGPALSettings CallIfNotFound(Browser.Browser.CallIfDelegate callIfNotFound)
        {
            gpalSettings.CallIfNotFoundList.Add(callIfNotFound);
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Print specified GPAL events to the console. [none (default)]")]
        public static IAllowGPALSettings WithPublishToConsole(GPALEventType eventType = GPALEventType.INFO | GPALEventType.WARNING | GPALEventType.ERROR | GPALEventType.EXCEPTION | GPALEventType.NOTICE | GPALEventType.CAUTION | GPALEventType.FAILURE)
        {
            GPALSettings.ConsoleEvents = eventType;
            if (GPALEventType.NONE == eventType)
                GPALSettings.PublishToConsole = false;
            else
                GPALSettings.PublishToConsole = true;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Write specified GPAL events to a text area on a form. [none (default)]")]
        public static IAllowGPALSettings WithPublishToControl(GPALTextArea control)
        {
            GPALSettings.PublishControl = control;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Which GPAL events reach the form control. [all (default)]")]
        public static IAllowGPALSettings WithControlEvents(GPALEventType eventTypes)
        {
            GPALSettings.ControlEvents = eventTypes;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Which GPAL events reach the information handler. [all (default)]")]
        public static IAllowGPALSettings WithInformationHandlerEvents(GPALEventType eventTypes)
        {
            GPALSettings.InformationHandlerEvents = eventTypes;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Which GPAL events reach the exception handler. [all (default)]")]
        public static IAllowGPALSettings WithExceptionHandlerEvents(GPALEventType eventTypes)
        {
            GPALSettings.ExceptionHandlerEvents = eventTypes;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Print specified GPAL events to the output window in VisualStudio. [none (default)]")]
        public static IAllowGPALSettings WithPublishToDebug(GPALEventType eventType = GPALEventType.INFO | GPALEventType.WARNING | GPALEventType.ERROR | GPALEventType.EXCEPTION | GPALEventType.NOTICE | GPALEventType.CAUTION | GPALEventType.FAILURE)
        {
            GPALSettings.DebugEvents = eventType;
            if (GPALEventType.NONE == eventType)
                GPALSettings.PublishToDebug = false;
            else
                GPALSettings.PublishToDebug = true;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Publish GPAL events to a logger, which writes them to whatever it was given: a file or a database.")]
        public static IAllowGPALSettings WithPublishToLogger(IGPALLogger logger)
        {
            GPALSettings.WithPublishToLogger(logger);
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Stop publishing GPAL events to a logger that was previously given one.")]
        public static IAllowGPALSettings RemoveLogger(IGPALLogger logger)
        {
            GPALSettings.RemoveLogger(logger);
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Which GPAL events reach an attached Information or Exception handler. [All (default)]")]
        public static IAllowGPALSettings WithHandlerEvents(GPALEventType eventTypes)
        {
            GPALSettings.InformationHandlerEvents = eventTypes;
            GPALSettings.ExceptionHandlerEvents = eventTypes;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Print stack trace when PublishToConsole or PublishToDebug is true. [true (default)]")]
        public static IAllowGPALSettings WithPublishStackTrace(bool trueFalse = true)
        {
            GPALSettings.PublishStackTrace = trueFalse;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Callback for failures a workflow can decide about, used by any browser without its own CallOnFail")]
        public static IAllowGPALSettings CallOnFail(Browser.Browser.CallOnFailDelegate callOnFail)
        {
            GPALSettings.CallOnFailHandlers.Add(callOnFail);
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Substitue string when data cannot be retrieved for an element [##UNABLE TO GET## (default)]")]
        public static IAllowGPALSettings WithDefaultErrorPlaceholder(string message = "##UNABLE TO GET##")
        {
            GPALSettings.ErrorPlaceholder = message;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Set the default timeout for waiting for a download to start.")]
        public static IAllowGPALSettings WithDownloadTimeoutInSec(int seconds)
        {
            GPALSettings.DownloadTimeoutInSec = seconds;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings("DO NOT use GPAL fallback actions on failure, just fail. Usually involves javascript recovery attempt. [false (default)")]
        public static IAllowGPALSettings WithNoFallbackActions(bool trueFalse = true)
        {
            GPALSettings.NoFallbackRecoveryActions = trueFalse;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Global value for selector matches so it's not set UOW at a time")]
        public static IAllowGPALSettings WithAllThatMatch(int matchCount = int.MaxValue)
        {
            GPALSettings.WithAllThatMatch = matchCount;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Automatically download and unzip the web driver that matches the version of the browser being run")]
        public static IAllowGPALSettings WithAutoUpdateWebDriver(bool trueFalse = true)
        {
            GPALSettings.AutoUpdateWebDriver = trueFalse;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Set the automation type to use for all browsers")]
        public static IAllowGPALSettings WithAutomationEngine(AutomationEngine automationEngine)
        {
            GPALSettings.AutomationEngine = automationEngine;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Global location for browser drivers. [./ (default)(same dir as exe)]")]
        public static IAllowGPALSettings WithDriverLocation(string driverPath)
        {
            GPALSettings.DriverLocation = FileHelper.EnsureDirectoryEndsWithBackslash(driverPath);
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Where GPAL writes files it created itself and nobody asked to keep. [GPALfilesSafeToDelete beside the exe (default)]")]
        public static IAllowGPALSettings WithTempDirectory(string tempPath)
        {
            GPALSettings.TempDirectory = FileHelper.EnsureDirectoryEndsWithBackslash(tempPath);
            return (IAllowGPALSettings)GPALSettings;
        }

        internal static string TempDirectory()
        {
            string tempPath = true == string.IsNullOrWhiteSpace(GPALSettings.TempDirectory)
                ? Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "GPALfilesSafeToDelete") + @"\"
                : GPALSettings.TempDirectory;
 
            if (false == Directory.Exists(tempPath))
                Directory.CreateDirectory(tempPath);
 
            return tempPath;
        }
        [GPALSettings(Description = "Intercharacter typing delay ceiling [0ms (default), no pacing]")]
        public static IAllowGPALSettings WithTypingDelay(int delayInTicks)
        {
            GPALSettings.WithTypingDelay(delayInTicks);
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Image matching similarity percentage. [80 (default)]")]
        public static IAllowGPALSettings WithImageMatchingPercentage(int matchPercent)
        {
            GPALSettings.WithImageMatchingPercentage(matchPercent);
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Nodes a YAML payload may hold before aliases are dropped for shared references. A cyclic payload always keeps them. [5000 (default), 0 never drops]")]
        public static IAllowGPALSettings WithYamlAliasLimit(int nodeLimit)
        {
            GPALSettings.WithYamlAliasLimit(nodeLimit);
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Simulate moving the mouse for every action (implies .WithHardware). [false (default)]")]
        public static IAllowGPALSettings WithSimulateMouseMovement(bool trueFalse = true)
        {
            GPALSettings.SimulateMouse = trueFalse;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Stop workflow if any selector is not found")]
        public static IAllowGPALSettings WithStopOnNotFound(bool trueFalse = true)
        {
            GPALSettings.StopOnNotFound = trueFalse;
            return (IAllowGPALSettings)GPALSettings;
        }
 
        [GPALSettings(Description = "Set the default location to store temporary profiles if browser.WithProfileDataDirectory is not used. default [C:\\profiles]")]
        public static IAllowGPALSettings WithTempProfileParentDirectory(string tempProfileDirectory)
        {
            // expanded the same way the settings object expands it, so %TEMP%\gpal means the same thing from
            // either one
            GPALSettings.TempProfileDirectory = Environment.ExpandEnvironmentVariables(tempProfileDirectory);
            return (IAllowGPALSettings) GPALSettings;
        }

        [GPALSettings(Description = "Handler to receive GPAL Exception events")]
        public static IAllowGPALSettings WithExceptionHandler(EventHandler<GPALEventArgs> eventHandler)
        {
            ExceptionEventHandler = eventHandler;
            Exception ex = new Exception("Welcome Exception :)");
            GPAL.PublishSimpleEvent(Enums.GPALEventType.EXCEPTION, $"Welcome to GPAL [{Version}] Exception Channel", null, Enums.GPALObjectType.None, ex);
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Print GPAL published information or exception messages to the output window in VisualStudio. [true (default)]")]
        public static IAllowGPALSettings WithPromptBeforeUnexpectedExit(bool trueFalse = true)
        {
            GPALSettings.PromptBeforeUnexpectedExit = trueFalse;
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Handler to receive GPAL Information events")]
        public static IAllowGPALSettings WithInformationHandler(EventHandler<GPALEventArgs> eventHandler)
        {
            InformationEventHandler = eventHandler;
            GPAL.PublishSimpleEvent(Enums.GPALEventType.INFO, $"Welcome to GPAL [{Version}] Information Channel");
            return (IAllowGPALSettings)GPALSettings;
        }

        [GPALSettings(Description = "Global setting to wait for time in ticks for an element to show up")]
        public static IAllowGPALSettings WithWaitFor(int waitForInTicks)
        {
            GPALSettings.WaitForInMs = waitForInTicks;
            return (IAllowGPALSettings)GPALSettings;
        }
 
        [GPALSettings(Description = "Take a screenshot with each published event")]
        public static IAllowGPALSettings WithTakeEventScreenshot(bool trueOrFalse)
        {
            GPALSettings.TakeEventScreenshot = trueOrFalse;
            return (IAllowGPALSettings)GPALSettings;
        }
 
 
        #endregion <GPAL Settings>
        #region <Private>
        // nmot sure why i coded this, may have been when i started to code the driver update logic but determined a better way to get the version...
        private static void CheckVersions()
        {
            if (string.Empty.Equals(tmpBrowser?.BrowserVersion))
            {
                BrowserType browserType = tmpBrowser.BrowserType;
 
                if (BrowserType.Chrome == browserType)
                {
                    DriverHelper.GetChromeVersion(out tmpBrowser.BrowserSettings.Version);
                }
                else if (BrowserType.Edge == browserType)
                {
                    DriverHelper.GetEdgeVersion(out tmpBrowser.BrowserSettings.Version);
                }
                else if (BrowserType.FireFox == browserType)
                {
                    DriverHelper.GetFirefoxVersion(out tmpBrowser.BrowserSettings.Version);
                }
 
                //ICapabilities capabilities = ((RemoteWebDriver)tmpBrowser.BrowserDriver).Capabilities;
                //tmpBrowser.BrowserVersion = capabilities.GetCapability("browserVersion")?.ToString();
 
                // Common WebDriver Capabilities:
                // "browserName"        - Name of the browser (e.g., "chrome", "firefox", "edge")
                // "browserVersion"     - Version of the browser (e.g., "120.0.6099.110")
                // "platformName"       - OS platform ("windows", "linux", "macOS")
                // "acceptInsecureCerts" - Whether SSL cert warnings are ignored (true/false)
                // "setWindowRect"      - Whether the WebDriver can resize the window (true/false)
                //
                // Chrome-Specific:
                // "goog:chromeOptions" - ChromeDriver options (e.g., args, binary path)
                // "goog:loggingPrefs"  - Logging preferences (e.g., performance, console logs)
                //
                // Edge-Specific:
                // "ms:edgeOptions"     - EdgeDriver options (e.g., args, headless mode)
                // "ms:edgeChromium"    - Whether Edge is running on Chromium (true/false)
                //
                // Firefox-Specific:
                // "moz:firefoxOptions" - FirefoxDriver options
                // "moz:headless"       - Whether running in headless mode (true/false)
                //
                // Remote/Grid Execution:
                // "webdriver.remote.sessionid" - Session ID for remote WebDriver
                // "timeouts"           - Dictionary of timeouts (implicit, pageLoad, script)
            }
        }
        private static void SetCatchUncaughtExceptions()
        {
            if (false == UncaughtExceptionHandlerSet)
            {
                CheckVersions();
 
                try
                {
                    // Set the unhandled exception mode to force errors to go through our handler. 
                    System.Windows.Forms.Application.SetUnhandledExceptionMode(UnhandledExceptionMode.CatchException);
 
                    // Add the event handler for handling thread exceptions to the event.
                    AppDomain.CurrentDomain.UnhandledException +=
                        new UnhandledExceptionEventHandler(UncaughtExceptionHandler);
 
                    // Hook cleanup handlers
                    Console.CancelKeyPress += OnCancelKeyPress;
                    AppDomain.CurrentDomain.ProcessExit += OnProcessExit;
 
                }
                catch (Exception ex)
                {
                    PublishSimpleEvent(GPALEventType.EXCEPTION, $"Unable to set uncaught exception handler", null, Enums.GPALObjectType.None, ex);
                }
 
                UncaughtExceptionHandlerSet = true;
            }
        }
 
        private static bool handlingTermination = false;
        private static void UncaughtExceptionHandler(object sender, UnhandledExceptionEventArgs args)
        {
            Exception e = (Exception)args.ExceptionObject;
 
            if (false == handlingTermination)
            {
                handlingTermination = true;
 
                // the message is what the reader needs. the exception is not passed on, because PublishSimpleEvent
                // emits ex.StackTrace from it and that is noise on top of a message we already have.
                bool ours = e is GPALException;
                string reason = true == ours ? "GPAL exception" : "uncaught exception";
 
                if (ConsoleEvents.HasFlag(GPALEventType.WARNING))
                {
                    PublishSimpleEvent(GPALEventType.WARNING, $">>> Caught {reason}: [{e.Message}][{e.StackTrace}]", null, Enums.GPALObjectType.None);
                    PublishSimpleEvent(GPALEventType.WARNING, $">>> [{reason}] Cleaning up before terminating.", null, GPALObjectType.None);
                }
                else if (ConsoleEvents.HasFlag(GPALEventType.CAUTION))
                {
                    PublishSimpleEvent(GPALEventType.CAUTION, $">>> Caught {reason}: [{e.Message}][{e.StackTrace}]", null, Enums.GPALObjectType.None);
                    PublishSimpleEvent(GPALEventType.CAUTION, $">>> [{reason}] Cleaning up before terminating.", null, GPALObjectType.None);
                }
 
                if (false == PublishToConsole)
                    GPAL.PublishSimpleEvent(GPALEventType.NOTICE, $"Terminating due to [{reason}]: [{e.Message}]");
 
                if (false == PublishToDebug)
                    Debug.WriteLine($"Terminating due to {reason}: [{e.Message}]");
 
                CleanupAndExit(true == ours ? "GPAL Exception" : "Unhandled Exception");
            }
        }
 
        private static void OnCancelKeyPress(object sender, ConsoleCancelEventArgs e)
        {
            //PublishSimpleEvent(GPALEventType.INFO, $">>> Detected Ctrl+C or Ctrl+Break.");
 
            if (false == handlingTermination)
            {
                handlingTermination = true;
 
                e.Cancel = true; // Prevents immediate termination
 
                if (false == PublishToConsole)
                    GPAL.PublishSimpleEvent(GPALEventType.NOTICE, $"Terminating due to Ctrl+C or Ctrl+Break.");
 
                if (false == PublishToDebug)
                    Debug.WriteLine($"Terminating due to Ctrl+C or Ctrl+Break.");
 
                CleanupAndExit("Ctrl+C or Ctrl+Break");
            }
        }
 
        private static void OnProcessExit(object sender, EventArgs e)
        {
            // PublishSimpleEvent(GPALEventType.INFO, $">>> Detected process exit or console X.");
 
            if (false == handlingTermination)
            {
                handlingTermination = true;
 
                if (false == PublishToConsole)
                    GPAL.PublishSimpleEvent(GPALEventType.NOTICE, $"Terminating due to Process Exit or console X.");
 
                if (false == PublishToDebug)
                    Debug.WriteLine($"Terminating due to Process Exit or console X.");
 
                CleanupAndExit("Process Exit or console X");
            }
        }
 
        private static bool _cleanupDone = false;
 
        internal static void CleanupAndExit(string reason)
        {
            if (false == _cleanupDone)  // in case we get multiple kill signals somehow, only run this once..
            {
                _cleanupDone = true;    
                try
                {
                    if (ConsoleEvents.HasFlag(GPALEventType.INFO))
                        PublishSimpleEvent(GPALEventType.INFO, $">>> [{reason}] Cleaning up before terminating.", null, GPALObjectType.None);
                    else if (ConsoleEvents.HasFlag(GPALEventType.NOTICE))
                        PublishSimpleEvent(GPALEventType.NOTICE, $">>> [{reason}] Cleaning up before terminating.", null, GPALObjectType.None);
 
                    if (false == PublishToConsole)
                        GPAL.PublishSimpleEvent(GPALEventType.NOTICE, $"[{reason}] Cleaning up before terminating.");
 
                    if (false == PublishToDebug)
                        Debug.WriteLine($"[{reason}] Cleaning up before terminating.");
 
                    BrowserHelper.KillAllRunningProcesses(true, null);
 
                    // the desktop itself lives until the last window on it is gone, so this only gives up our
                    // handle rather than closing anything still running there
                    GenerallyPositive.Browser.HiddenDesktop.CloseAll();
                }
                catch (Exception ex)
                {
                    PublishSimpleEvent(GPALEventType.EXCEPTION, $"Cleanup error", null, GPALObjectType.None, ex);
                }
 
                // Stop timer and publish end time + total runtime
                _appTimer.Stop();
                string endTime = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss");
                TimeSpan totalRuntime = _appTimer.Elapsed;
                string formattedRuntime = $"{totalRuntime.Hours:D2}:{totalRuntime.Minutes:D2}:{totalRuntime.Seconds:D2}.{totalRuntime.Milliseconds:D3}";
 
                if (ConsoleEvents.HasFlag(GPALEventType.INFO))
                {
                    PublishSimpleEvent(GPALEventType.INFO, $">>> Application End Time: [{endTime}] <<<", null, GPALObjectType.None);
                    PublishSimpleEvent(GPALEventType.INFO, $">>> Total Runtime: [{formattedRuntime}] <<<", null, GPALObjectType.None);
                }
                else if (ConsoleEvents.HasFlag(GPALEventType.NOTICE))
                {
                    PublishSimpleEvent(GPALEventType.NOTICE, $">>> Application End Time: [{endTime}] <<<", null, GPALObjectType.None);
                    PublishSimpleEvent(GPALEventType.NOTICE, $">>> Total Runtime: [{formattedRuntime}] <<<", null, GPALObjectType.None);
                }
 
                // published and nothing else, the same as the start time and the version are at startup. writing
                // these directly when console publishing was off said them anyway, which is the one thing turning
                // it off asked us not to do
 
                if (true == GPALSettings.PromptBeforeUnexpectedExit)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.NOTICE, "Press any key to exit...");
                    Debug.WriteLine("Press any key to exit...");
                    Console.ReadKey();
                }
            }
 
            // normal exit, return 0
            if (true == reason.Equals("Process Exit or console X"))
                Environment.Exit(0);
 
            Environment.Exit(0xdead);
        }
        #endregion <Private>
    }
}