Application.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.
// =============================================================================
 
//extern alias mUIA;
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.Linq;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
using System.Windows.Automation;
using GenerallyPositive.Browser;
using GenerallyPositive.GPALForm;
using static GenerallyPositive.Enums;
 
namespace GenerallyPositive.Application
{
    public class Application
        : IApplication
    {
        public delegate CallIfStatus CallIfDelegate(Application application, List<IGPALAutomationElement> foundElements, List<IGPALAutomationElement> matchedElements, Selector selector, bool matchedAll);
        public delegate CallIfStatus CallAfterFillInDelegate(Application application, IGPALGrid<string> tokens, int tokenIdx);
 
        #region <Working Variables>
        internal ApplicationSettings applicationSettings { get; set; }
        private dynamic persistenceList;
        internal UnitOfWork CurrentUOW { get; set; }  = null;
        private UnitOfWork persistentUOW = null;
        #endregion <Working Variables>
        public Application ToGPALObject()
        {
            return this;
        }

        internal Application()
        {
            CurrentUOW = new UnitOfWork();
            persistentUOW = new UnitOfWork();
            persistenceList = new List<UnitOfWork>
            {
                persistentUOW
            };
            applicationSettings = new ApplicationSettings(this);
        }
        #region <Private>
        private bool CheckWaitFor()
        {
            bool matchFound = true;
            List<GPALAutomationElement> foundElements = null;
 
            // an earlier action on this same unit of work already waited these selectors in successfully, so
            // waiting again is redundant - nothing can have moved under us, since any selector added after an
            // action starts a fresh unit of work. the action still resolves its own elements either way.
            if (null != CurrentUOW.WaitForSatisfied)
            {
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Selectors for this unit of work already found at [{CurrentUOW.WaitForSatisfied:HH:mm:ss.fff}], skipping redundant wait.", this, GPALObjectType.Application);
                return true;
            }
 
            if (WaitTime.Never < CurrentUOW.WaitForInMs)
            {
                // we are waiting on selector(s)
                foundElements = ElementHelper.WaitFor(this, CurrentUOW.WaitForInMs, out matchFound);
 
                if (0 < foundElements?.Count)
                    CurrentUOW.WaitForSatisfied = DateTime.Now;
            }
 
            return matchFound;
        }
        private bool InAction(bool checkWaitFor)
        {
            ApplicationHelper.TopProcess(this.Process); // ensure the browser window is on top, can use selenium or hardware (mouse click) topping. firefox will only top with hardware
 
            CurrentUOW.ActionCalled = true;
 
            SelectorListMaintenanceSweep(CurrentUOW); // purge any nodes marked 'deleteme' before iterating list
            SelectorListMaintenanceSweep(persistentUOW); // purge any nodes marked 'deleteme' before iterating list
            CheckPersistentSelectors(); // check if there are persistent selectors to deal with
 
            // TODO: CAVEAT: WaitFor will call the CallIf handlers, which might result in unexpected behavior?
            if (true == checkWaitFor)
                CheckWaitFor();
 
            // always attempt the gated action, same as the browser side. WaitFor only holds the workflow until
            // something turns up, it is not a match test - and the action does its own element lookup anyway,
            // so a genuinely missing element surfaces there where it gets logged and can be debugged, rather
            // than the action being silently skipped here.
            return true;
        }
        private static void SelectorListMaintenanceSweep(dynamic CurrentUOW)
        {
            for (int idx = 0; idx < CurrentUOW.WithSelectorList.Count; idx++)
                if (true == CurrentUOW.WithSelectorList[idx].DeleteMe)
                    CurrentUOW.WithSelectorList.RemoveAt(idx);
 
            for (int idx = 0; idx < CurrentUOW.InSelectorList.Count; idx++)
                if (true == CurrentUOW.InSelectorList[idx].DeleteMe)
                    CurrentUOW.InSelectorList.RemoveAt(idx);
        }
        private void CheckPersistentSelectors()
        {
            // all we have to do is walk the list, try to find the element and the callif callbacks will do the work
            if (0 < (persistentUOW.WithSelectorList?.Count ?? 0))
                foreach (Selector selector in persistentUOW.WithSelectorList)
                    ElementHelper.FindElements(this, persistentUOW, selector, out bool matchedAll, out List<GPALAutomationElement> elems);
        }
        #endregion <Private>
        #region <Application Actions>
        public IAllowAllApplicationAndAllSelector Maximize
        {
            get
            {
                if (null != Process)
                    ApplicationHelper.ShowWindow(Process.MainWindowHandle, 3);    // 1= SW_NORMAL - show normal, 3 = max, 2 = min
                return this;
            }
        }

        public IAllowAllApplicationAndAllSelector Minimize
        {
            get
            {
                ApplicationHelper.ShowWindow(Process.MainWindowHandle, 2);    // 1= SW_NORMAL - show normal, 3 = max, 2 = min
                return this;
            }
        }

        public IAllowAllApplicationAndAllSelector Restore
        {
            get
            {
                ApplicationHelper.ShowWindow(Process.MainWindowHandle, 1);    // 1= SW_NORMAL - show normal, 3 = max, 2 = min
                return this;
            }
        }

        public IAllowAllApplicationAndAllSelector ResizeWindow(int width, int height)
        {
            if (true == InAction(true))
                ApplicationHelper.ResizeWindow(ApplicationSettings.LastWindowHandle, width, height);
            return this;
        }

        public IAllowAllApplicationAndAllSelector MoveWindow(int x, int y)
        {
            if (true == InAction(true))
                ApplicationHelper.MoveWindow(ApplicationSettings.LastWindowHandle, x, y);
            return this;
        }

        public IAllowSelectorActionOrAnySelector AppendFrom(GPALDatabase inputDatabase)
        {
            DatabaseHelper.TokenizeDatabase(CurrentUOW, inputDatabase);
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, inputDatabase.Tokens, WriteMode.Append);
            return this;
        }

        public IAllowSelectorActionOrAnySelector AppendFrom(GPALFile inputFile)
        {
            ((IGPALFileInternal)inputFile).TokenList = FileHelper.TokenizeFile(CurrentUOW, inputFile);
            
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, ((IGPALFileInternal)inputFile).TokenList, WriteMode.Append);
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector AppendFrom(IGPALGrid<string> inputGrid)
        {
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, inputGrid, WriteMode.Append);
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector AppendFrom(string textToUse)
        {
            if (true == InAction(true))
                ElementHelper.FillInFrom(this, textToUse, WriteMode.Append);
            return this;
        }

        public IAllowAllExceptParameters Open([Directory()] string applicationPath)
        {
            IntPtr processHandle = IntPtr.Zero;
            Process[] processes;
            StringBuilder parameters = new StringBuilder();
            bool first = true;
 
            foreach (string parameter in applicationSettings.Parameters)
            {
                if (false == first)
                    parameters.Append(" ");
                else
                    first = false;
                parameters.Append(parameter);
            }
 
            if (null != Process)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, "Unable to Open/control more than one program. Please use another Application.", this, GPALObjectType.Application);
                return this;
            }
 
            ApplicationPath = applicationPath;
 
            // CAVEAT: see if process is open and attach to it? not sure this is what we want
            // maybe we should just launch a new instance?
            try
            {
                processes = Process.GetProcessesByName(Path.GetFileNameWithoutExtension(applicationPath));
                bool attached = false;
                if (null != processes && 0 < processes.Length)
                {
                    // An already-running instance should have a window quickly; probe each briefly and
                    // skip windowless/background matches rather than blocking for the full timeout.
                    foreach (Process process in processes)
                    {
                        applicationSettings.Process = process;
                        AutomationElement existingRoot = WaitForRootAutomationElement(process, 2000);
                        if (null != existingRoot)
                        {
                            applicationSettings.RootAutomationElement = existingRoot;
                            processHandle = process.MainWindowHandle;
                            attached = true;
                            break;
                        }
                    }
                }
 
                if (false == attached)
                {
                    applicationSettings.Process = Process.Start(applicationPath, parameters.ToString());
 
                    // Do not guess with a fixed sleep: poll until the main window exists and its root
                    // automation element is actually retrievable, up to WaitForWindowTimeout seconds.
                    AutomationElement root = WaitForRootAutomationElement(applicationSettings.Process,
                        Math.Max(1, applicationSettings.WaitForWindowTimeout) * 1000);
 
                    if (null == root)
                    {
                        string msg = $"Timed out after [{applicationSettings.WaitForWindowTimeout}]s waiting for the main window / root automation element of [{applicationPath}].";
                        GPAL.PublishSimpleEvent(GPALEventType.ERROR, msg, this, GPALObjectType.Application);
                        throw new GPALException(msg);
                    }
 
                    applicationSettings.RootAutomationElement = root;
                    processHandle = applicationSettings.Process.MainWindowHandle;
                }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Unable to launch [{applicationPath}].", this, GPALObjectType.Application, ex);
                return this;
            }
 
            if (null == applicationSettings.Process)
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Unable to launch [{applicationPath}].", this, GPALObjectType.Application);
            else
            {
                ApplicationHelper.TopProcess(applicationSettings.Process);
                CurrentUOW.ActionCalled = true;
            }
 
            return this;
        }

        private AutomationElement WaitForRootAutomationElement(Process process, int timeoutMs)
        {
            if (null == process)
                return null;
 
            Stopwatch stopwatch = Stopwatch.StartNew();
 
            // Let a GUI app pump its message loop and create its window. This throws immediately for a
            // process with no message loop (e.g. a console app), so it never wastes the timeout on those.
            try { process.WaitForInputIdle(timeoutMs); } catch { /* no message loop; fall through to polling */ }
 
            while (stopwatch.ElapsedMilliseconds < timeoutMs)
            {
                try
                {
                    process.Refresh();
                    IntPtr handle = process.MainWindowHandle;
                    if (IntPtr.Zero != handle)
                    {
                        AutomationElement root = AutomationElement.FromHandle(handle);
                        if (null != root)
                            return root;
                    }
                }
                catch
                {
                    // Window/handle not ready yet (or transiently invalid); keep polling until timeout.
                }
 
                Thread.Sleep(100);
            }
 
            return null;
        }
        public void Close()
        {
            Process.Close();
            Process = null;
        }

        public IAllowSelectorActionOrAnySelector FillInFrom(GPALDatabase inputDatabase)
        {
            DatabaseHelper.TokenizeDatabase(CurrentUOW, inputDatabase);
 
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, CurrentUOW.InputDatabase.Tokens, WriteMode.Overwrite);
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector FillInFrom(GPALFile inputFile)
        {
            ((IGPALFileInternal)inputFile).TokenList = FileHelper.TokenizeFile(CurrentUOW, inputFile);
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, ((IGPALFileInternal)CurrentUOW.InputFile).TokenList, WriteMode.Overwrite);
            return this;
        }

        public IAllowSelectorActionOrAnySelector FillInFrom(IGPALGrid<string> inputGrid)
        {
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, (IGPALGrid<string>)inputGrid, WriteMode.Overwrite);
            return this;
        }

        public IAllowSelectorActionOrAnySelector FillInFrom(string textToUse)
        {
            if (true == InAction(true))
                ElementHelper.FillInFrom(this, textToUse, WriteMode.Overwrite);
            return this;
        }

        public IAllowSelectorActionOrAnySelector Focus(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.Focus(this);
            return this;
        }

        public IAllowSelectorActionOrAnySelector Hover(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.Hover(this, CurrentUOW);
            return this;
        }

        public IAllowSelectorActionOrAnySelector InsertFrom(string textToUse)
        {
            if (true == InAction(true))
                ElementHelper.FillInFrom(this, textToUse, WriteMode.Insert);
            return this;
        }

        public IAllowSelectorActionOrAnySelector InsertFrom(GPALDatabase inputDatabase)
        {
            DatabaseHelper.TokenizeDatabase(CurrentUOW, inputDatabase);
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, CurrentUOW.InputDatabase.Tokens, WriteMode.Insert);
            return this;
        }

        public IAllowSelectorActionOrAnySelector InsertFrom(IGPALGrid<string> inputGrid)
        {
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, (IGPALGrid<string>)inputGrid, WriteMode.Insert);
            return this;
        }

        public IAllowSelectorActionOrAnySelector InsertFrom(GPALFile inputFile)
        {
            ((IGPALFileInternal)inputFile).TokenList = FileHelper.TokenizeFile(CurrentUOW, inputFile);
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, ((IGPALFileInternal)CurrentUOW.InputFile).TokenList, WriteMode.Insert);
            return this;
        }

        public IAllowSelectorActionOrAnySelector LeftClick(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.LeftClick(this);
            return this;
        }

        public IAllowSelectorActionOrAnySelector LeftClick(Enums.ModifierKeys modifierKeys)
        {
            if (true == InAction(true))
                ElementHelper.LeftClick(this, modifierKeys);
            return this;
        }

        public IAllowSelectorActionOrAnySelector LeftDoubleClick(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.GenericClick(this, ClickType.LeftDoubleClick);
            return this;
        }

        public IAllowSelectorActionOrAnySelector MiddleClick(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.GenericClick(this, ClickType.MiddleClick);
            return this;
        }

        public IAllowSelectorActionOrAnySelector MoveTo(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.MoveTo(this);
            return this;
        }

        public IAllowSelectorActionOrAnySelector DragAndDrop(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.DragAndDrop(this);
            return this;
        }

        public IAllowSelectorActionOrAnySelector DragAndDrop(ModifierKeys modifierKeys)
        {
            if (true == InAction(true))
                ElementHelper.DragAndDrop(this, modifierKeys);
            return this;
        }

        public IAllowSelectorActionOrAnySelector PressModifierKey(ModifierKeys modifierKeys)
        {
            HardwareHelper.PressModifierKey(modifierKeys);
            return this;
        }

        public IAllowSelectorActionOrAnySelector ReleaseModifierKey(ModifierKeys modifierKeys)
        {
            HardwareHelper.ReleaseModifierKeys(modifierKeys);
            return this;
        }

        public IAllowSelectorActionOrAnySelector SendKey(byte VKCode)
        {
            if (true == InAction(true))
                HardwareHelper.SendKey(VKCode);
            return this;
        }

        public IAllowSelectorActionOrAnySelector SendString(string textToSend)
        {
            HardwareHelper.SendString(textToSend, GPAL.TypingDelay);
            return this;
        }

        public IAllowAllActionAndAnySelector SwitchToTab(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.SwitchToTab(this);
            return this;
        }

        public IAllowAllActionAndAnySelector SetRange(double rangeValue)
        {
            if (true == InAction(true))
                ElementHelper.SetRange(this, rangeValue);
            return this;
        }

        public IAllowSelectorActionOrAnySelector RightClick(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.GenericClick(this, ClickType.RightClick);
            return this;
        }

        public IAllowAfterWaitForAndSizeControl WaitFor(int timeoutInTicks)
        {
            // we are done waiting on any selectors since we performed an action
            // so, we just wait/sleep
            if (true == CurrentUOW.ActionCalled)
                Thread.Sleep(timeoutInTicks);
            else
                CurrentUOW.WaitForInMs = timeoutInTicks;
 
            return this;
        }

        public IAllowAfterWaitForAndSizeControl WaitForWindow(string windowTitle)
        {
            if (true == InAction(true))
                ApplicationSettings.LastWindowHandle = FormHelper.WaitForWindow(windowTitle, ApplicationSettings.WaitForWindowTimeout);
            return this;
        }

        public IAllowAfterWaitForAndSizeControl WaitForWindowRegex(string windowTitleRegex)
        {
            if (true == InAction(true))
                ApplicationSettings.LastWindowHandle = FormHelper.WaitForWindowRegex(windowTitleRegex, ApplicationSettings.WaitForWindowTimeout);
            return this;
        }

        public IAllowSelectorActionOrAnySelector ScrollHorizontalSmall(int iterations = 1)
        {
            for (; 0 < iterations; iterations--)
                ElementHelper.Scroll(this, ScrollAmount.SmallIncrement, ScrollTypes.Increments, ScrollTypes.Horizontal);
 
            for (; 0 > iterations; iterations++)
                ElementHelper.Scroll(this, ScrollAmount.SmallDecrement, ScrollTypes.Increments, ScrollTypes.Horizontal);
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector ScrollHorizontalLarge(int iterations = 1)
        {
            for (; 0 < iterations; iterations--)
                ElementHelper.Scroll(this, ScrollAmount.LargeIncrement, ScrollTypes.Increments, ScrollTypes.Horizontal);
 
            for (; 0 > iterations; iterations++)
                ElementHelper.Scroll(this, ScrollAmount.LargeDecrement, ScrollTypes.Increments, ScrollTypes.Horizontal);
            return this;
        }

        public IAllowSelectorActionOrAnySelector ScrollHorizontalPercent(int percent)
        {
            if (0 > percent || 100 < percent)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Invalid percantage value [{percent}], unable to scroll using supplied values. Normalizing to nearest endpoint.", this, GPALObjectType.Application);
                int newPercent = (0 > percent ? 0 : (100 < percent ? 100 : percent));
            }
            ElementHelper.Scroll(this, percent, ScrollTypes.Percent, ScrollTypes.Horizontal);
            return this;
        }

        public IAllowSelectorActionOrAnySelector ScrollVerticalSmall(int iterations = 1)
        {
            for (; 0 < iterations; iterations--)    // + = down
                ElementHelper.Scroll(this, ScrollAmount.SmallIncrement, ScrollTypes.Increments, ScrollTypes.Vertical);
 
            for (; 0 > iterations; iterations++)    // - = up
                ElementHelper.Scroll(this, ScrollAmount.SmallDecrement, ScrollTypes.Increments, ScrollTypes.Vertical);
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector ScrollVerticalLarge(int iterations = 1)
        {
            for (; 0 < iterations; iterations--)
                ElementHelper.Scroll(this, ScrollAmount.LargeIncrement, ScrollTypes.Increments, ScrollTypes.Vertical);
 
            for (; 0 > iterations; iterations++)
                ElementHelper.Scroll(this, ScrollAmount.LargeDecrement, ScrollTypes.Increments, ScrollTypes.Vertical);
            return this;
        }

        public IAllowSelectorActionOrAnySelector ScrollVerticalPercent(int percent)
        {
            ElementHelper.Scroll(this, percent, ScrollTypes.Percent, ScrollTypes.Vertical);
            return this;
        }
        #endregion <Application Actions>
        #region <Helpers>
        public void RemoveCallIfHandlerEverywhere(Application.CallIfDelegate func)
        {
            CurrentUOW.AppCallIfFound.Remove(func);
            CurrentUOW.AppCallIfNotFound.Remove(func);
 
            // TODO: do the same for inselectorlist
            foreach (Selector selector in CurrentUOW.WithSelectorList)
            {
                selector.SelectorSettings.AppCallIfFound.Remove(func);
                selector.SelectorSettings.AppCallIfNotFound.Remove(func);
            }
 
            foreach (Selector selector in CurrentUOW.InSelectorList)
            {
                selector.SelectorSettings.AppCallIfFound.Remove(func);
                selector.SelectorSettings.AppCallIfNotFound.Remove(func);
            }
 
            persistentUOW.AppCallIfFound.Remove(func);
            persistentUOW.AppCallIfNotFound.Remove(func);
 
            foreach (Selector selector in persistentUOW.WithSelectorList)
            {
                selector.SelectorSettings.AppCallIfFound.Remove(func);
                selector.SelectorSettings.AppCallIfNotFound.Remove(func);
            }
        }
        #endregion <Helpers>
        #region <Application Settings>
        public IAllowApplicationSettingsOrOpen WithName(string appName)
        {
            Name = appName;
            return this;
        }

        public IAllowPersistentCallBack PersistentCallIfFound(CallIfDelegate persistentCallIfFound)
        {
            persistentUOW.AppCallIfFound.Add(persistentCallIfFound);
 
            return this;
        }

        public IAllowPersistentCallBack PersistentCallIfNotFound(CallIfDelegate persistentCallIfNotFound)
        {
            persistentUOW.AppCallIfNotFound.Add(persistentCallIfNotFound);
 
            return this;
        }

        public IAllowPersistence WithPersistentSelector(Selector selector)
        {
            // when would we ever add another persistent uow?
            // normal uow is once action is called, any withselector is on the next uow, but persistents don't act like this
            if (true == CurrentUOW.ActionCalled)
            {
                persistentUOW = new UnitOfWork();
                persistenceList.Add(persistentUOW);
            }
 
            selector.Application = this;
            //persistentUOW.SelectorType = SelectorType.WithSelector;
            persistentUOW.WithSelectorList.Add(selector);
            return this;
        }

        public IAllowSelectorActionOrAnySelector WithSelector(Selector selector)
        {
            selector.ElementsFoundAndMatchedCount = 0;  // in case it is reused
 
            if (true == CurrentUOW.ActionCalled)
            {
                CurrentUOW = new UnitOfWork();
            }
 
            // clone so if this selector is reused, each UOW list will be unique and we won't change the selector by changing the browser it is associated with
            // NOTE: cloning disassociates with actual program selector, so we can't set any queryable properties on Selector like 'ElementsFoundAndMatchedCount'
            // ApplicationSettings.MySelector = new Selector(this, selector);    // MySelector temp hold for other browser syntax
            ApplicationSettings.MySelector = selector;
 
            CurrentUOW.WithSelectorList.Add(ApplicationSettings.MySelector);
 
            return this;
        }
        // TODO: How to deal with tokens. To consume a row for each row, but to also repeat the same token down the page?
        public IAllowAfterAnySelectorExceptWithAll WithAllThatMatch(int rowCount = int.MaxValue)
        {
            CurrentUOW.WithAllThatMatch = rowCount;
            return this;
        }
 
        #region <GetGrid / SaveTo / Pagination>
        // ─────────────────────────────────────────────────────────────────────────────────────
        // Data extraction out of a desktop application, mirroring the Browser GetGrid API.
        // A single selector that resolves to a UIA grid/table control is read structurally via
        // GridPattern/TablePattern; otherwise each selector is a column and repeating matches are
        // the rows (the WithAllThatMatch model). Missing cells use GPAL.ErrorPlaceholder. The
        // result lands in CurrentUOW.RetGrid so SaveTo*/pagination reuse the shared, engine-neutral
        // helpers (FileHelper.SaveToDelimited, GPAL.Converter) exactly as the Browser side does.
        // ─────────────────────────────────────────────────────────────────────────────────────
        public IAllowWithHeaderOrFileActions GetGrid(ref IGPALGrid<string> returnGrid)
        {
            CurrentUOW.GetGridCalled = true;
            CurrentUOW.RetGrid.Clear();
 
            if (!TryGetGridFromControl())
                GetGridFromSelectors();
 
            // Do not take ownership of a grid the caller passed in:
            //  - null in -> hand them GPAL's internal grid.
            //  - grid in -> add our rows into THEIR grid and keep their reference so repeated GetGrid calls accumulate.
            if (null == returnGrid)
                returnGrid = (IGPALGrid<string>)CurrentUOW.RetGrid;
            else
                returnGrid.Add((IGPALGrid<string>)CurrentUOW.RetGrid);
 
            return this;
        }
 
        // Table-native: a single selector that resolves to a control exposing the UIA GridPattern
        // is read cell-by-cell via GetItem(row, col); TablePattern column headers become the header
        // row. Returns false when this is not a grid control so the selector-column path runs.
        private bool TryGetGridFromControl()
        {
            if (1 != CurrentUOW.WithSelectorList.Count
                || SelectorType.Selector != CurrentUOW.WithSelectorList[0].selectorSettings.SelectorType)
                return false;
 
            Selector sel = CurrentUOW.WithSelectorList[0];
            bool matchedAll; List<GPALAutomationElement> matched;
            var found = ElementHelper.FindElements(this, CurrentUOW, sel, out matchedAll, out matched);
            AutomationElement ae = (null != found && found.Count > 0) ? found[0].Ae : null;
            object gpObj;
            if (null == ae || !ae.TryGetCurrentPattern(GridPattern.Pattern, out gpObj))
                return false;
 
            GridPattern grid = (GridPattern)gpObj;
            int rows = grid.Current.RowCount;
            int cols = grid.Current.ColumnCount;
 
            List<string> headers = null;
            object tpObj;
            if (ae.TryGetCurrentPattern(TablePattern.Pattern, out tpObj))
            {
                AutomationElement[] colHeaders = ((TablePattern)tpObj).Current.GetColumnHeaders();
                if (null != colHeaders && colHeaders.Length > 0)
                {
                    headers = new List<string>();
                    foreach (AutomationElement h in colHeaders)
                        headers.Add(h.GetText() ?? string.Empty);
                }
            }
 
            int cap = (int.MaxValue == CurrentUOW.WithAllThatMatch)
                        ? int.MaxValue : CurrentUOW.WithAllThatMatch;
 
            for (int r = 0; r < rows && CurrentUOW.RetGrid.Count() < cap; r++)
            {
                var row = new List<string>(cols);
                for (int c = 0; c < cols; c++)
                {
                    string text;
                    try
                    {
                        AutomationElement cell = grid.GetItem(r, c);
                        text = (null != cell) ? (cell.GetText() ?? string.Empty) : GPAL.ErrorPlaceholder;
                    }
                    catch
                    {
                        text = GPAL.ErrorPlaceholder;
                    }
                    row.Add(text);
                }
                CurrentUOW.RetGrid.AddRow(row);
            }
 
            if (null != headers && headers.Count > 0
                && (null == CurrentUOW.HeaderList || 0 == CurrentUOW.HeaderList.Count))
                CurrentUOW.HeaderList = headers;
 
            GPAL.PublishSimpleEvent(GPALEventType.INFO, $"GetGrid: [{sel.Name}] resolved to a UIA grid ([{rows}] x [{cols}]).", this, GPALObjectType.Application);
            return true;
        }
 
        // Column-per-selector extraction: each selector is a column, repeating matches are the rows.
        // Mirrors the Browser column-zip (pad short columns, dedup rows, honor WithAllThatMatch and
        // multi-page paging) but reads cells with the UIA .Ae.GetText() the app side already uses.
        private void GetGridFromSelectors()
        {
            var names = new List<string>();
            foreach (Selector s in CurrentUOW.WithSelectorList)
                names.Add(s.Name);
 
            var seenRows = new HashSet<string>();
            bool capReached = false;
            int cap = (int.MaxValue == CurrentUOW.WithAllThatMatch)
                        ? int.MaxValue : CurrentUOW.WithAllThatMatch;
 
            for (int page = 0; page < CurrentUOW.PageCount && !capReached; page++)
            {
                var columns = new List<List<string>>();
                int maxRows = 0;
 
                foreach (Selector sel in CurrentUOW.WithSelectorList)
                {
                    var col = new List<string>();
                    if (SelectorType.Selector == sel.selectorSettings.SelectorType)
                    {
                        bool matchedAll; List<GPALAutomationElement> matched;
                        var found = ElementHelper.FindElements(this, CurrentUOW, sel, out matchedAll, out matched);
                        List<GPALAutomationElement> elems =
                            (!matchedAll && null != matched && matched.Count > 0)
                                ? matched
                                : (null != found ? found.ToList() : new List<GPALAutomationElement>());
                        foreach (GPALAutomationElement e in elems)
                            col.Add((null != e.Ae) ? (e.Ae.GetText() ?? string.Empty) : GPAL.ErrorPlaceholder);
                    }
                    else if (SelectorType.Data == sel.selectorSettings.SelectorType)
                        col.Add(sel.SelectorPath);
                    else if (SelectorType.DataFunc == sel.selectorSettings.SelectorType)
                        col.Add(sel.selectorSettings.DataFunction());
 
                    columns.Add(col);
                    if (col.Count > maxRows) maxRows = col.Count;
                }
 
                // pad short columns so every row has a cell per column
                for (int i = 0; i < columns.Count; i++)
                    while (columns[i].Count < maxRows)
                        columns[i].Add($"{GPAL.ErrorPlaceholder} : {names[i]}");
 
                for (int r = 0; r < maxRows && !capReached; r++)
                {
                    var row = new List<string>(columns.Count);
                    for (int c = 0; c < columns.Count; c++)
                        row.Add(columns[c][r]);
 
                    string key = string.Join("", row);
                    if (!seenRows.Add(key))
                        continue;   // duplicate row from a prior page/scroll pass
                    CurrentUOW.RetGrid.AddRow(row);
                    if (CurrentUOW.RetGrid.Count() >= cap)
                        capReached = true;
                }
 
                if (!capReached && page < CurrentUOW.PageCount - 1)
                    if (!ApplicationHelper.GotoNextPage(this))
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.INFO, $"GetGrid: no next page after page [{page + 1}].", this, GPALObjectType.Application);
                        break;
                    }
            }
 
            if (null == CurrentUOW.HeaderList || 0 == CurrentUOW.HeaderList.Count)
                CurrentUOW.HeaderList = names;
        }

        public IAllowWithHeaderOrFileActions WithHeader(string header)
        {
            if (true == CurrentUOW.GetGridCalled)
            {
                CurrentUOW.GetGridCalled = false;
                CurrentUOW.HeaderList.Clear();
            }
            CurrentUOW.HeaderList.Add(header);
            return this;
        }

        public IAllowWithHeaderOrFileActions WithGridToSave(IGPALGrid<string> gridToSave)
        {
            CurrentUOW.RetGrid = gridToSave;
            return this;
        }

        public IAllowWithPagesAndGridActions WithNextPageButton(Selector selector)
        {
            CurrentUOW.NextPageButton = selector;
            return this;
        }

        public IAllowWithPagesAndGridActions WithInfiniteScroll
        {
            get
            {
                CurrentUOW.InfiniteScroll = true;
                return this;
            }
        }

        public IAllowGetGridAndFillInFrom WithPages(int numberOfPages)
        {
            CurrentUOW.PageCount = numberOfPages;
            return this;
        }
 
        // Resolve the output column names for a grid save, handed to the Converter as column metadata
        // (WithColumnNames), NOT injected as a data row. Precedence, highest first, with a short higher list
        // topped up from the next level down:
        //   1. CurrentUOW.HeaderList  - the workflow's .WithHeader columns (override)
        //   2. the output GPALFile's ColumnList - the file's own columns (wildcard/.Next replication of the
        //      first entry happens at expansion time, so entry 0 is representative here)
        //   3. selector names - the ultimate global, always defined
        // Whether the names are written is governed by the output file's FirstLineIsColumnNames.
        private List<string> ResolveHeaderColumns(GPALFile file)
        {
            List<string> selectorNames = CurrentUOW.WithSelectorList?.Where(s => null != s.Name).Select(s => s.Name).ToList()
                ?? new List<string>();
 
            List<string> fileColumns = new List<string>();
            IGPALGrid<string> columnList = ((IGPALFileInternal)file).FileSettings.ColumnList;
            if (null != columnList && 0 < columnList.Count() && null != columnList[0])
                fileColumns = new List<string>(columnList[0]);
 
            List<string> resolved = (null != CurrentUOW.HeaderList && 0 < CurrentUOW.HeaderList.Count)
                ? new List<string>(CurrentUOW.HeaderList)
                : new List<string>();
            for (int i = resolved.Count; i < fileColumns.Count; i++)
                resolved.Add(fileColumns[i]);
            for (int i = resolved.Count; i < selectorNames.Count; i++)
                resolved.Add(selectorNames[i]);
            return resolved;
        }

        public IAllowAllActionAndAnySelector SaveTo(GPALFile file)
        {
            GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Saving [{CurrentUOW.RetGrid?.Rows ?? 0}] rows of window data to [{file?.Filename}].", this, GPALObjectType.Application);
 
            var converter = GPAL.Converter.WithInput(CurrentUOW.RetGrid).WithColumnNames(ResolveHeaderColumns(file));
            // Naming headers via WithHeader is clear intent to write them; declare it so the output emits a
            // header row unless the output file explicitly turns it off (WithFirstLineIsColumnNames(false)).
            if (null != CurrentUOW.HeaderList && 0 < CurrentUOW.HeaderList.Count)
                converter.WithFirstLineHasColumnNames(true);
            converter.SaveTo(file);
            return this;
        }

        public IAllowAllActionAndAnySelector AppendTo(GPALFile file)
        {
            GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Appending [{CurrentUOW.RetGrid?.Rows ?? 0}] rows of window data to [{file?.Filename}].", this, GPALObjectType.Application);
 
            GPAL.Converter.WithInput(CurrentUOW.RetGrid).WithColumnNames(ResolveHeaderColumns(file)).AppendTo(file);
            return this;
        }
        #endregion <GetGrid / SaveTo / Pagination>
        public IAllowAfterWaitForAndSizeControl WithWaitForWindowTimeout(int waitTimeInSeconds)
        {
            ApplicationSettings.WaitForWindowTimeout = waitTimeInSeconds;
            return this;
        }

        public IAllowApplicationSettingsOrOpen WithParameter(string parameter)
        {
            ApplicationSettings.Parameters.Add(parameter);
            return this;
        }

        public IAllowApplicationSettingsOrOpen WithUseHardware(bool trueFalse)
        {
            ApplicationSettings.UseHardware = trueFalse;
            return this;
        }

        public IAllowAfterAnySelector CallIfFound(Application.CallIfDelegate callIfFoundDelegate)
        {
            CurrentUOW.AppCallIfFound.Add(callIfFoundDelegate);
            return this;
        }

        public IAllowAfterAnySelector CallIfNotFound(Application.CallIfDelegate callIfNotFoundDelegate)
        {
            CurrentUOW.AppCallIfNotFound.Add(callIfNotFoundDelegate);
            return this;
        }

        public IAllowAfterAnySelector CallAfterFillIn(CallAfterFillInDelegate callAfterFillIn)
        {
            CurrentUOW.AppCallAfterFillIn = callAfterFillIn;
            return this;
        }
        #region <Getters/Setters>
        public Process Process
        {
            get
            {
                return applicationSettings.Process;
            }
            internal set
            {
                applicationSettings.Process = value;
            }
        }

        public object ManagedRootAutomationElement
        {
            get
            {
                return applicationSettings.ManagedRootAutomationElement;
            }
 
            internal set
            {
                applicationSettings.ManagedRootAutomationElement = value;
            }
        }

        public AutomationElement RootAutomationElement
        {
            get
            {
                return applicationSettings.RootAutomationElement;
            }
 
            internal set
            {
                applicationSettings.RootAutomationElement = value;
            }
        }

        public string Name
        {
            get
            {
                return ApplicationSettings.Name;
            }
 
            internal set
            {
                ApplicationSettings.Name = value;
            }
        }

        public string ApplicationPath
        {
            get
            {
                return applicationSettings.ApplicationPath;
            }
            internal set
            {
                applicationSettings.ApplicationPath = value;
            }
        }

        internal ApplicationSettings ApplicationSettings
        {
            get 
            { 
                return applicationSettings; 
            }
        }
        #endregion <Getters/Setters>
        #endregion <Application Settings>
    }
}