PuppeteerCommunicator.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 System;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Drawing;
using System.IO;
using System.Linq;
using System.Net.WebSockets;
using System.Runtime.InteropServices;
using System.Text;
//using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using static GenerallyPositive.Browser.Puppeteer;
using static GenerallyPositive.Enums;
 
// written with help from grok
namespace GenerallyPositive.Browser
{
    public class WindowSession
    {
        public string BrowserContextId { get; set; }
        public ConcurrentQueue<KeyValuePair<string, string>> TabQueue { get; set; }
        public int ActiveTabIndex { get; set; }
 
        public WindowSession(string browserContextId, ConcurrentQueue<KeyValuePair<string, string>> tabQueue, int activeTabIndex = 0)
        {
            BrowserContextId = browserContextId;
            TabQueue = tabQueue ?? new ConcurrentQueue<KeyValuePair<string, string>>();
            ActiveTabIndex = activeTabIndex;
        }
    }
 
    public class PuppeteerCommunicator
    {
        private string _puppeteerUrl;
        private ClientWebSocket _webSocket;
 
        public string webSocketUrl { get; private set; }
 
        private int _activeWindowIndex = 0;

        public int ServerResponseCode { 
            get => Browser.ServerResponseCode; 
            set => Browser.ServerResponseCode = value; 
        }

        private Dictionary<string, long> FrameIdToContextId { get; set; } = new Dictionary<string, long>(StringComparer.Ordinal);
        private string CurrentFrameSessionId { get; set; }

        private long? CurrentContextId { get; set; }
        private string CurrentFrameId { get; set; }
        // Root that scoped selectors resolve against: a shadow root from InShadowDom or an element from
        // InElement. Holds a remote object, which is valid only in the execution context it came from and is
        // cleared when that context changes
        private string CurrentRootObjectId { get; set; }

        internal async Task EnablePageEvents()
        {
            await SendCommand<object>(DevToolsMethods.PageEnable, new { }, GetEffectiveSessionId()).ConfigureAwait(false);
        }
 
        private ConcurrentDictionary<long, TaskCompletionSource<dynamic>> _responseTasks { get;  } = new ConcurrentDictionary<long, TaskCompletionSource<dynamic>>();
        private ConcurrentQueue<(string Event, dynamic Data)> _events { get; } = new ConcurrentQueue<(string, dynamic)>();
        internal ConcurrentQueue<WindowSession> _windowSessionsQueue { get; set; } = new ConcurrentQueue<WindowSession>();
        public ConcurrentQueue<KeyValuePair<string, string>> CurrentSessions
        {
            get
            {
                var tabQueue = GetActiveWindowTabQueue();
                return tabQueue ?? new ConcurrentQueue<KeyValuePair<string, string>>();
            }
        }

        public string CurrentTargetID
        {
            get => ((PuppeteerClient)PuppeteerClient)._currentTargetId;
        }
        private int _commandId = 0xdead;
        internal bool _isRunning { get; set; }
        internal bool _usePipes { get; set; }
        private CancellationTokenSource _cts;
        private readonly SemaphoreSlim _sendSemaphore = new SemaphoreSlim(1, 1); // Added for SendAsync serialization
        internal IPuppeteerClient PuppeteerClient { get; set; }
        internal Browser Browser { get; set; }
        private bool _suppressNetworkEvents { get; set; } = false;
 
        // every request the page issued while capture was on, in the order chrome reported them. off by default,
        // because recording every request of every run costs memory nobody asked to spend
        internal bool CapturingCalls { get; set; } = false;
        internal List<GPALCall> CapturedCalls { get; } = new List<GPALCall>();

        public List<GPALCall> GetCapturedCalls()
        {
            return new List<GPALCall>(CapturedCalls);
        }

        public void ClearCapturedCalls()
        {
            CapturedCalls.Clear();
        }
 
        // requestId to the call it belongs to, so the status the site answered with lands on the right one
        private readonly Dictionary<string, GPALCall> _capturedById = new Dictionary<string, GPALCall>();
        internal Task ReceiveTask { get; set; }
        internal TaskCompletionSource<bool> _readerReadyTcs { get; set; }
 
        // Per instance. Static, one browser would suppress another browser's messages
        List<string> lastErrorMessage = new List<string>();
 
        // CDP answers one of these for a node with no layout box. The element is there and simply is not drawn
        static readonly string[] NotRenderedAnswers = { "Node does not have a layout object", "Could not compute box model" };
        bool supressedMessage = false;
        string lastSessionToken;
        // Per instance. Static, one browser closing would block commands from every other browser
        bool inExit = false;
 
        internal class CastDevice
        {
            public CastDevice(string name, string id)
            {
                this.name = name;
                this.id = id;
            }
            public string name;
            public string id;
        }
 
        internal List<CastDevice> CastDevices = new List<CastDevice>();
        internal string SinkName { get; set; } = null;
 
        internal PuppeteerCommunicator(string puppeteerUrl, IBrowser browser, bool usePipes = false, bool capturingCalls = false)
        {
            // set before initializing, because initializing is what attaches to the page and turns the Network
            // domain on, and it reads this to decide whether to
            CapturingCalls = capturingCalls;
 
            Browser = (Browser)browser;
            // Per instance. The client holds the target it is bound to, so a shared one would send both
            // browsers' commands down the socket of whichever was built last
            PuppeteerClient = new PuppeteerClient();
            _usePipes = usePipes;
            _windowSessionsQueue = new ConcurrentQueue<WindowSession>(); // Initialize with new type
 
            _puppeteerUrl = puppeteerUrl;
 
            // longer than the wait inside GetWebSocketUrl, so a browser that is merely slow to open its debug
            // port is waited out rather than killed by this while that one is still counting
            var initTask = InitializeCommunication(Browser);
            bool initFinished;
 
            try
            {
                initFinished = initTask.Wait(TimeSpan.FromSeconds(45));
            }
            catch (AggregateException ex)
            {
                // Wait wraps what the init threw. the reason leaves here instead, with its own stack
                Exception reason = ex.Flatten().InnerExceptions.FirstOrDefault() ?? ex;
 
                System.Runtime.ExceptionServices.ExceptionDispatchInfo.Capture(reason).Throw();
 
                throw;   // never reached, the compiler cannot know that
            }
 
            if (false == initFinished)
            {
                string msg = $"Puppeteer communication initialization timed out talking to [{puppeteerUrl}]. Workflow canot run without it, Try again.";
 
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, msg, this, GPALObjectType.PuppeteerCommunicator);
 
                // GPAL's own, so it arrives on the GPAL channel and a workflow that catches GPALException catches
                // this too. a bare framework exception out of a constructor is nobody's to answer for
                throw new GPALException($"{GPAL.MyMethodName()}: {msg}");
            }
            ReceiveTask = initTask.GetAwaiter().GetResult(); // Already finished, this just unwraps results/
 
            //InitializeCommunication().GetAwaiter().GetResult();
 
            // the client dispatches from its own endpointMap and never makes an http request, so there was no
            // base url to give it. Whatever chooses the transport when pipes are finished, it will not be here
            PuppeteerClient.WithPuppeteerCommunicator(this);
 
            Browser.Started = true;
        }
 
        public PuppeteerCommunicator()
        {
        }

        private const int MaxConnectAttempts = 3;

        private const int ReaderStopWaitMs = 2_000;

        private int _connectAttempts;
 
        internal async Task Reconnect()
        {
            // if we lost pipes, then we closed, but ports can be closed due to bad cdp commands or other 'aborted connection' issues
            if (false == _usePipes)
            {
                if (_webSocket != null)
                {
                    try
                    {
                        _webSocket.Dispose();
                    }
                    catch { }
                }
                else
                    GPAL.PublishSimpleEvent(GPALEventType.ERROR, "Cannot restart CDP pipes. Please restart workflow", this, GPALObjectType.PuppeteerCommunicator);
 
                _cts?.Cancel();
 
                // cancelling only asks the readers to stop. disposing in the same breath races one that has
                // not unwound. WhenAny does not rethrow, so a reader that faulted is left to whoever
                // already reported it
                if (null != ReceiveTask)
                    await Task.WhenAny(ReceiveTask, Task.Delay(ReaderStopWaitMs)).ConfigureAwait(false);
 
                _cts?.Dispose();
 
                await InitializeCommunication(Browser).ConfigureAwait(false);
            }
        }
        private async Task<Task> InitializeCommunication(Browser Browser)
        {
            dynamic sessionId = null;
            dynamic session = null;
            dynamic targets = null;
            bool _foundWhatsNew = false;
            Task ourTask = null;
 
            _readerReadyTcs = new TaskCompletionSource<bool>();
            _cts = new CancellationTokenSource();
            _isRunning = true;
 
            if (true == _usePipes) // Check if pipe transport is enabled
            {
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, "Using Puppeteer Pipes", this, GPALObjectType.PuppeteerCommunicator);
                try
                {
                    // Ensure Chrome process is running with pipe transport
                    if (true == Browser?.Process?.HasExited)
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.ERROR, "Chrome process not running or exited for pipe transport", this, GPALObjectType.PuppeteerCommunicator);
                        return null;
                    }
 
                    ourTask = Task.Run(async () =>
                    {
                        try
                        {
                            await ReceivePipeMessages(_cts.Token).ConfigureAwait(false);
                        }
                        catch
                        {
                            _readerReadyTcs.TrySetCanceled();
                        }
                    }, _cts.Token);
 
                    // Wait for reader to be ready
                    //await _readerReadyTcs.Task; // - now safe
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Pipe initialization failed", this, GPALObjectType.PuppeteerCommunicator, ex);
                    return null;
                }
            }
            else // WebSocket transport
            {
                var ws = new ClientWebSocket();
                ws.Options.SetBuffer(65536, 65536); // 4MB
                ws.Options.KeepAliveInterval = TimeSpan.FromSeconds(30); // Ping every 30s
                _webSocket = ws;
                _webSocket.Options.KeepAliveInterval = TimeSpan.Zero;
                webSocketUrl = GetWebSocketUrl(_puppeteerUrl);
 
                if (string.IsNullOrEmpty(webSocketUrl))
                {
                    // no websocket url is no browser, and a communicator that cannot talk to one fails later
                    // on whatever the workflow does first rather than here where the reason is known
                    string msg = $"The browser at [{_puppeteerUrl}] never opened its debug port, so there is nothing to drive";
 
                    GPAL.PublishSimpleEvent(GPALEventType.ERROR, msg, this, GPALObjectType.PuppeteerCommunicator);
 
                    throw new GPALException($"{GPAL.MyMethodName()}: {msg}");
                }
 
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Using Puppeteer Ports Connecting to WebSocket: [{webSocketUrl}]", this, GPALObjectType.PuppeteerCommunicator);
                try
                {
                    await _webSocket.ConnectAsync(new Uri(webSocketUrl), _cts.Token).ConfigureAwait(false);
                    GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"WebSocket state after connect: [{_webSocket.State}]", this, GPALObjectType.PuppeteerCommunicator);
 
                    _connectAttempts = 0;
 
                    // Yield control for 10ms to let the connection handshake completely settle
                    await Task.Delay(10).ConfigureAwait(false);
 
                    // Use async/await inside Task.Run so .NET correctly tracks the background worker
                    ourTask = Task.Run(async () => await ReceiveMessages(_cts.Token).ConfigureAwait(false));
                }
                catch (Exception ex)
                {
                    // a socket drops for reasons worth surviving: a heavy navigation, a target being recreated,
                    // a transient error under load. a dead browser looks identical, so the retry is bounded
                    _connectAttempts++;
 
                    GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"WebSocket connection failed on attempt [{_connectAttempts}] of [{MaxConnectAttempts}]", this, GPALObjectType.PuppeteerCommunicator, ex);
 
                    if (MaxConnectAttempts <= _connectAttempts)
                    {
                        string msg = $"The browser at [{_puppeteerUrl}] refused its debug socket on [{_connectAttempts}] attempts, so there is nothing to drive";
 
                        GPAL.PublishSimpleEvent(GPALEventType.ERROR, msg, this, GPALObjectType.PuppeteerCommunicator);
 
                        throw new GPALException($"{GPAL.MyMethodName()}: {msg}");
                    }
 
                    // longer each time, because a browser still opening is the case worth waiting on and a
                    // browser that is gone costs only the wait before it is called
                    await Task.Delay(_connectAttempts * 1_000).ConfigureAwait(false);
 
                    await Reconnect().ConfigureAwait(false);
 
                    return await InitializeCommunication(Browser).ConfigureAwait(false);
                }
            }
 
            try
            {
                // Enable target discovery
                await SendCommand<object>(DevToolsMethods.TargetSetDiscoverTargets, new { discover = true }, null).ConfigureAwait(false);
 
            // Get all targets
                for (int cnt = 3; 0 < cnt && false == _foundWhatsNew; cnt--)
                {
                    targets = await SendCommand<object>(DevToolsMethods.TargetGetTargets, new { }, null).ConfigureAwait(false);
                    if (targets == null || targets.targetInfos == null)
                    {
                        // the socket is open and the browser answered, but there is no page to drive
                        string msg = $"The browser at [{_puppeteerUrl}] reported no targets, so there is no page to drive";
 
                        GPAL.PublishSimpleEvent(GPALEventType.ERROR, msg, this, GPALObjectType.PuppeteerCommunicator);
 
                        throw new GPALException($"{GPAL.MyMethodName()}: {msg}");
                    }
 
                    // Close any tab with URL "chrome://whats-new/"
                    // NOTE: now handled in temp profile
                    //foreach (dynamic target in targets.targetInfos)
                    //{
                    //    string targetType = target.type?.ToString();
                    //    string targetUrl = target.url?.ToString();
                    //    if (targetType == "page" && targetUrl == "chrome://whats-new/")
                    //    {
                    //        string targetId = target.targetId?.ToString();
                    //        GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Closing tab with URL: [{targetUrl}] (targetId: [{targetId}])", this, GPALObjectType.PuppeteerCommunicator);
                    //        await SendCommand<object>(DevToolsMethods.TargetCloseTarget, new { targetId }, null);
                    //        _foundWhatsNew = true;
                    //        goto restartAfterClose;
                    //    }
                    //}
                    Thread.Sleep(1_000);
                }
 
                // Enable Target domain to receive Target.created events
                await SendCommand<object>(DevToolsMethods.TargetSetDiscoverTargets, new { discover = true }, null).ConfigureAwait(false);
                //await SendCommand<object>(DevToolsMethods.TargetSetAutoAttach, new { autoAttach = true, waitForDebuggerOnStart = false, flatten = true }, null);
 
                // Find and attach to a page target
                var pageTarget = ((IEnumerable<dynamic>)targets.targetInfos)
                    .FirstOrDefault(t => t.type == "page" && t.url != "");
 
                if (pageTarget != null)
                {
                    var targetId = (string)pageTarget.targetId;
                    session = await SendCommand<object>(DevToolsMethods.TargetAttachToTarget, new
                    {
                        targetId,
                        flatten = true
                    }, null).ConfigureAwait(false);
                    sessionId = (string)session?.sessionId;
 
                    if (sessionId != null)
                    {
                        string browserContextId = pageTarget.browserContextId?.ToString() ?? "";
                        var tabQueue = new ConcurrentQueue<KeyValuePair<string, string>>();
                        tabQueue.Enqueue(new KeyValuePair<string, string>(targetId, sessionId));
                        _windowSessionsQueue.Enqueue(new WindowSession(browserContextId, tabQueue, 0)); // Default context, activeTabIndex=0
                        _activeWindowIndex = 0;
                        ((PuppeteerClient)PuppeteerClient)._currentTargetId = targetId;
                        GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Attached to targetId: [{targetId}], sessionId: [{sessionId}], URL: [{pageTarget.url}]", this, GPALObjectType.PuppeteerCommunicator);
 
                        // .CaptureCalls can be said before there is a browser. the flag is carried in when this
                        // communicator is built, and the Network domain is turned on here, where there is finally
                        // a session to turn it on for, so recording starts before the first navigation
                        if (true == CapturingCalls)
                            await CaptureCalls(true, sessionId).ConfigureAwait(false);
                    }
                    else
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Failed to attach to targetId: [{targetId}]", this, GPALObjectType.PuppeteerCommunicator);
                    }
                }
                else
                {
                    GPAL.PublishSimpleEvent(GPALEventType.ERROR, "No page target found after initialization", this, GPALObjectType.PuppeteerCommunicator);
                }
                //await SendCommand<object>(DevToolsMethods.PageEnable, new { }, sessionId);
                //await SendCommand<object>(DevToolsMethods.NetworkEnable, new { }, sessionId);
            }
            catch (ObjectDisposedException ex) when (ex.ObjectName == "System.Net.WebSockets.ClientWebSocket")
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"WebSocket disposed", this, GPALObjectType.Puppeteer, ex);
                await Reconnect().ConfigureAwait(false);
                return await InitializeCommunication(Browser).ConfigureAwait(false);
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Initialization failed", this, GPALObjectType.Puppeteer, ex);
            }
 
            // the reader this init started, so Reconnect waits on the one that is actually running rather than
            // whichever one the constructor first saw
            ReceiveTask = ourTask;
 
            return ourTask;
        }

        private async Task InitializeWebSocket()
        {
            webSocketUrl ??= GetWebSocketUrl(_puppeteerUrl);
            if (string.IsNullOrEmpty(webSocketUrl))
            {
                string msg = $"The browser at [{_puppeteerUrl}] never opened its debug port, so there is nothing to reconnect to";
 
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, msg, this, GPALObjectType.PuppeteerCommunicator);
 
                throw new GPALException($"{GPAL.MyMethodName()}: {msg}");
            }
 
            _webSocket = new ClientWebSocket();
            await _webSocket.ConnectAsync(new Uri(webSocketUrl), _cts.Token).ConfigureAwait(false);
        }

        private async Task ApplyStealthProtection(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            // Combine anti-bot scripts with enhanced toString override
            string antiAntiBotScript = @"
                    (function() {
                        var originalError = Error;
                        Object.defineProperty(Error.prototype, 'stack', {
                            configurable: false,
                            enumerable: true,
                            writable: true,
                            value: (function() {
                                try {
                                    throw new originalError();
                                } catch (e) {
                                    return e.stack;
                                }
                            })()
                        });
 
                        window.Error = new Proxy(originalError, {
                            construct(target, args) {
                                var instance = new target(...args);
                                return Object.freeze(instance);
                            }
                        });
 
                        // Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
 
                        // Enhanced toString override to hide script contents
                        (function() {
                            // Store the original toString
                            const originalToString = Object.prototype.toString;
 
                            // Create a proxy handler to intercept toString calls
                            const handler = {
                                apply: function(target, thisArg, argumentsList) {
                                    if (thisArg instanceof Function && /antiAntiBotScript|CDP/.test(originalToString.call(thisArg))) {
                                        return 'function () { [native code] }';
                                    }
                                    return target.apply(thisArg, argumentsList);
                                }
                            };
 
                            // Wrap toString with a proxy
                            Object.prototype.toString = new Proxy(originalToString, handler);
 
                            console.log('toString override applied via Proxy');
                        })();
 
                        console.log('CDP protection with toString override applied');
                    })();
                ";
 
            // Enable Fetch script injection for the initial page load
            await EnableFetchScriptInjection(antiAntiBotScript, sessionId).ConfigureAwait(false);
 
            GPAL.PublishSimpleEvent(GPALEventType.INFO, "Stealth CDP protection with toString override applied via Fetch.requestPaused.", this, GPALObjectType.Browser);
        }
        [DllImport("user32.dll")]
        private static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);

        internal const int DefaultCommandTimeoutSeconds = 10;
        internal const int LongCommandTimeoutSeconds = 60;
 
        // the commands whose work is not answering us: fetching a page over the network, repainting it, encoding an
        // image. everything else is a question the browser already knows the answer to
        private static readonly HashSet<DevToolsMethods> slowCommands = new HashSet<DevToolsMethods>
        {
            DevToolsMethods.PageNavigate,
            DevToolsMethods.PageNavigateToHistoryEntry,
            DevToolsMethods.PageReload,
            DevToolsMethods.PageCaptureScreenshot,
        };
 
        public async Task<dynamic> SendCommand<TParameters>(DevToolsMethods method, TParameters parameters, string sessionId, int retries = 3, bool doNotGetSemaphore = false, int timeoutSeconds = 0)
        {
            const int SW_MINIMIZE = 6;
 
            // 0 means the caller did not care, so pick by what the command has to do to answer
            if (0 >= timeoutSeconds)
                timeoutSeconds = slowCommands.Contains(method) ? LongCommandTimeoutSeconds : DefaultCommandTimeoutSeconds;
            const int SW_RESTORE = 9;
            const int SW_MAXIMIZE = 3;
 
            if (true == inExit)
                return null;
 
            // For browser-level commands (Target.*), force null sessionId - we should have this properly managed in our code - but if someone else calls this from their code...
            if (method.ToString().StartsWith("Target") && null != sessionId)
            {
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Session ID [{sessionId}] cannot be used for 'Target' CDP commands. Using null.", this, GPALObjectType.PuppeteerCommunicator);
                sessionId = null;
            }
 
            // Handle window state commands directly
            if (method == DevToolsMethods.MinimizeWindow)
            {
                try
                {
                    if (false == Browser?.Process?.HasExited)
                    {
                        ShowWindow(Browser.Process.MainWindowHandle, SW_MINIMIZE);
                        return true;
                    }
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No valid browser process to minimize", this, GPALObjectType.PuppeteerCommunicator);
                    return false;
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, "Failed to minimize window", this, GPALObjectType.PuppeteerCommunicator, ex);
                    return false;
                }
            }
            else if (method == DevToolsMethods.RestoreWindow)
            {
                try
                {
                    if (false == Browser?.Process?.HasExited)
                    {
                        ShowWindow(Browser.Process.MainWindowHandle, SW_RESTORE);
                        return true;
                    }
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No valid browser process to restore", this, GPALObjectType.PuppeteerCommunicator);
                    return false;
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, "Failed to restore window", this, GPALObjectType.PuppeteerCommunicator, ex);
                    return false;
                }
            }
            else if (method == DevToolsMethods.MaximizeWindow)
            {
                try
                {
                    if (false == Browser?.Process?.HasExited)
                    {
                        ShowWindow(Browser.Process.MainWindowHandle, SW_MAXIMIZE);
                        return true;
                    }
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No valid browser process to maximize", this, GPALObjectType.PuppeteerCommunicator);
                    return false;
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, "Failed to maximize window", this, GPALObjectType.PuppeteerCommunicator, ex);
                    return false;
                }
            }
            else if (method == DevToolsMethods.CheckNetworkIdle)
            {
                return CheckNetworkIdle();
            }
 
            if (true == Browser?.Process?.HasExited)
            {
                string msg = "The browser process has exited, so there is nothing left to send a command to";
 
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, msg, this, GPALObjectType.PuppeteerCommunicator);
 
                if (false == inExit)
                {
                    inExit = true;
                    BrowserHelper.KillAllRunningProcesses(true, Browser);
                }
 
                // cleanup first, then the workflow is told
                throw new GPALException($"{GPAL.MyMethodName()}: {msg}");
            }
            else if (false == _usePipes && (_webSocket == null || _webSocket.State != WebSocketState.Open))
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"WebSocket in [{_webSocket?.State}] state, reconnecting", this, GPALObjectType.PuppeteerCommunicator);
                await Reconnect().ConfigureAwait(false);
            }
 
            dynamic data = null;
 
            try
            {
                if (false == doNotGetSemaphore)
                    await _sendSemaphore.WaitAsync(_cts.Token).ConfigureAwait(false);
 
                try
                {
                    long id = Interlocked.Increment(ref _commandId);
                    int retry = 2;
                    int rootNodeId = 1;
 
                    while (0 < retry)
                    {
                        var tcs = new TaskCompletionSource<dynamic>(TaskCreationOptions.RunContinuationsAsynchronously);
                        _responseTasks[id] = tcs;
 
                        var command = DevToolsCommandBuilder.BuildCommand(method, parameters, id, sessionId, rootNodeId);
                        var bytes = Encoding.UTF8.GetBytes(command);
 
                        if (_usePipes)
                        {
                            var stream = Browser.BrowserSettings.InboundPipe;
 
                            // Write 4-byte length header (big-endian uint32)
                            var lengthBytes = BitConverter.GetBytes((uint)bytes.Length);
                            if (BitConverter.IsLittleEndian)
                                Array.Reverse(lengthBytes); // Convert to big-endian
                            await stream.WriteAsync(lengthBytes, 0, lengthBytes.Length, _cts.Token).ConfigureAwait(false);
 
                            // Write JSON command
                            await stream.WriteAsync(bytes, 0, bytes.Length, _cts.Token).ConfigureAwait(false);
 
                            // Flush to ensure immediate send
                            await stream.FlushAsync(_cts.Token).ConfigureAwait(false);
                        }
                        else
                        {
                            await _webSocket.SendAsync(new ArraySegment<byte>(bytes), WebSocketMessageType.Text, true, _cts.Token).ConfigureAwait(false);
                        }
 
                        // --- Add timeout handling to prevent hanging ---
                        dynamic message = null;
                        try
                        {
                            message = await tcs.Task.TimeoutAfter(TimeSpan.FromSeconds(timeoutSeconds), method.ToString()).ConfigureAwait(false);
                        }
                        catch (TimeoutException)
                        {
                            GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Command [{method}] timed out, releasing semaphore.", this, GPALObjectType.PuppeteerCommunicator);
                            // Remove TCS to prevent blocking future commands
                            _responseTasks.TryRemove(id, out _);
                            throw; // optionally rethrow or handle gracefully
                        }
                        finally
                        {
                            // Ensure TCS is removed even on success or exception
                            _responseTasks.TryRemove(id, out _);
                        }
 
                        try
                        {
                            if (message is string)
                            {
                                if (true == "Session with given id not found.".Equals(message))
                                {
                                    if (1 < retry--)
                                    {
                                        ClearCurrentSessionId();   // the stored one is dead, so drop it and let GetCurrentSessionId attach a fresh one
                                        CurrentFrameSessionId = null;
                                        sessionId = GetEffectiveSessionId();
                                        continue;
                                    }
                                }
                                else if (true == "Sink not found".Equals(message))
                                {
                                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, "DIAL devices not supported. Use ID from chrome://media-router-internals/", this, GPALObjectType.PuppeteerCommunicator);
                                }
 
                                bool notRendered = true == NotRenderedAnswers.Any(answer => true == $"{message}".StartsWith(answer));
                                string msg = true == notRendered ? "Element is not rendered, so it has no position on the page." : $"CDP error : [{message}].";
                                if (false == lastErrorMessage.Contains(msg))    // we are not in control of lastmessages.clear, whomever calls us is
                                {
                                    lastErrorMessage.Add(msg);
                                    GPAL.PublishSimpleEvent(true == notRendered ? GPALEventType.INFO : GPALEventType.ERROR, msg, this, GPALObjectType.PuppeteerCommunicator);
                                    supressedMessage = false;
                                }
                                else if (false == supressedMessage)
                                {
                                    GPAL.PublishSimpleEvent(GPALEventType.INFO, "Supressing repeat messages", msg, GPALObjectType.Other);
                                    supressedMessage = true;
                                }
 
                                throw new ApplicationException(msg);
                            }
                            else if (message?.error != null)
                            {
                                if (true == "Session with given id not found.".Equals(message?.error?.message?.ToString()))
                                {
                                    if (1 < retry--)
                                    {
                                        ClearCurrentSessionId();   // the stored one is dead, so drop it and let GetCurrentSessionId attach a fresh one
                                        CurrentFrameSessionId = null;
                                        sessionId = GetEffectiveSessionId();
                                        continue;
                                    }
                                }
 
                                bool notRendered = true == NotRenderedAnswers.Any(answer => true == $"{message.error.message}".StartsWith(answer));
                                string msg = true == notRendered ? "Element is not rendered, so it has no position on the page." : $"CDP error : [{message.error.message}].";
                                if (false == lastErrorMessage.Contains(msg))    // we are not in control of lastmessages.clear, whomever calls us is
                                {
                                    lastErrorMessage.Add(msg);
                                    GPAL.PublishSimpleEvent(true == notRendered ? GPALEventType.INFO : GPALEventType.ERROR, msg, this, GPALObjectType.PuppeteerCommunicator);
                                    supressedMessage = false;
                                }
                                else if (false == supressedMessage)
                                {
                                    GPAL.PublishSimpleEvent(GPALEventType.INFO, "Supressing repeat messages", msg, GPALObjectType.Other);
                                    supressedMessage = true;
                                }
 
                                throw new ApplicationException(msg);
                            }
                        }
                        catch //(Exception ex)
                        {
                            //var noErrorMessage = true;
                        }
 
                        if (null == resultExtractors)
                        {
                            var protocolJson = GetProtocolJSON();
                            resultExtractors = CdpResultExtractors.Build(protocolJson);
                        }
                        // Handle response data
                        if (resultExtractors != null && resultExtractors.TryGetValue(method, out var extractor))
                        {
                            if (null == message || message is string || message.result == null)
                            {
                                string msg = $"Command [{method}] returned null result.";
                                if (false == lastErrorMessage.Contains(msg))
                                {
                                    lastErrorMessage.Add(msg);
                                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, msg, this, GPALObjectType.PuppeteerCommunicator);
                                    supressedMessage = false;
                                }
                                else if (false == supressedMessage)
                                {
                                    GPAL.PublishSimpleEvent(GPALEventType.INFO, "Supressing repeat messages", msg, GPALObjectType.Other);
                                    supressedMessage = true;
                                }
                                return null;
                            }
                            data = extractor((Newtonsoft.Json.Linq.JObject)message?.result);
                        }
                        else
                        {
                            data = message.result?.ToObject<dynamic>() ?? new { };
                        }
 
                        break;
                        //if (data?.Length > 50_000_000) // Limit to 50MB
                        //{
                        //    GPAL.PublishSimpleEvent(GPALEventType.WARNING, "Message data too large", this, GPALObjectType.PuppeteerCommunicator);
                        //    return null;
                        //}
                    }
                }
                finally
                {
                    if (false == doNotGetSemaphore)
                        _sendSemaphore.Release();
                }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Command [{method}][{parameters}] failed.", null, GPALObjectType.None, ex);
            }
 
            return data;
        }
        public async Task<string> EnableFetchScriptInjection(string scriptToInject, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            string identifier = null;
            try
            {
                if (true == Browser.UseSelenium)
                {
                    // Use Selenium CDP command for non-Puppeteer case
                    identifier = BrowserHelper.SeleniumAddScriptToEvaluateOnNewDocument(Browser.BrowserSettings, scriptToInject);
                }
                else if (true == Browser.UsePuppeteer)
                {
                    // Use Puppeteer CDP command directly
                    var result = await SendCommand<object>(DevToolsMethods.PageAddScriptToEvaluateOnNewDocument, new
                    {
                        source = scriptToInject
                    }, sessionId ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId).ConfigureAwait(false);
                    identifier = result?.identifier?.ToString();
                }
 
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Script injected via CDP for sessionId: [{sessionId ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId}]", this, GPALObjectType.PuppeteerCommunicator);
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Failed to inject script via CDP", this, GPALObjectType.Puppeteer, ex);
                throw;
            }
 
            return identifier;
        }

        public async Task RemoveInjectedScript(string identifier, string sessionId = null)
        {
            if (string.IsNullOrEmpty(identifier))
            {
                return;
            }
 
            sessionId ??= GetEffectiveSessionId();
            try
            {
                if (true == Browser.UseSelenium)
                {
                    BrowserHelper.SeleniumRemoveScriptToEvaluateOnNewDocument(Browser.BrowserSettings, identifier);
                }
                else if (true == Browser.UsePuppeteer)
                {
                    await SendCommand<object>(DevToolsMethods.PageRemoveScriptToEvaluateOnNewDocument, new
                    {
                        identifier
                    }, sessionId ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId).ConfigureAwait(false);
                }
 
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Injected script [{identifier}] removed via CDP for sessionId: [{sessionId ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId}]", this, GPALObjectType.PuppeteerCommunicator);
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Failed to remove injected script via CDP", this, GPALObjectType.Puppeteer, ex);
                throw;
            }
        }
 
        private readonly List<string> _injectedScriptIdentifiers = new List<string>();

        public async Task<string> InjectScript(string scriptToInject, string sessionId = null)
        {
            var identifier = await EnableFetchScriptInjection(scriptToInject, sessionId).ConfigureAwait(false);
            if (!string.IsNullOrEmpty(identifier))
            {
                _injectedScriptIdentifiers.Add(identifier);
            }
            return identifier;
        }

        public async Task ClearInjectedScripts(string sessionId = null)
        {
            foreach (var identifier in _injectedScriptIdentifiers)
            {
                await RemoveInjectedScript(identifier, sessionId).ConfigureAwait(false);
            }
            _injectedScriptIdentifiers.Clear();
        }
        // using fetchenable request - doesn't work due to nonce issues
        // the concept here is to inject javascript in a page response before the website loads it, but the above seems to work, iunno, i think this was for antibot scripts
        // but we are already stealthy except synthetic events, but then use hardware and chrome mode, not headless
        //public async Task EnableFetchScriptInjection(string scriptToInject, string sessionId = null)
        //{
        //    try
        //    {
        //        // Ensure Fetch domain is enabled with retries
        //        int maxRetries = 3;
        //        for (int attempt = 0; attempt < maxRetries; attempt++)
        //        {
        //            try
        //            {
        //                await SendCommand<object>(DevToolsMethods.FetchEnable, new
        //                {
        //                    patterns = new[]
        //                    {
        //            new { urlPattern = "*", resourceType = "Document", requestStage = "Response" }
        //        }
        //                }, sessionId ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId);
        //                GPAL.PublishSimpleEvent(GPALEventType.INFO, $"FetchEnable successful on attempt {attempt + 1}", this, GPALObjectType.PuppeteerCommunicator);
        //                break;
        //            }
        //            catch (Exception ex)
        //            {
        //                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"FetchEnable failed on attempt {attempt + 1}: {ex.Message}", this, GPALObjectType.PuppeteerCommunicator);
        //                if (attempt == maxRetries - 1) throw;
        //                await Task.Delay(500); // Wait before retrying
        //            }
        //        }
 
        //        Action<object, dynamic> handler = async (sender, e) =>
        //        {
        //            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Fetch.requestPaused event data: {Newtonsoft.Json.JsonConvert.SerializeObject(e)}", this, GPALObjectType.PuppeteerCommunicator);
 
        //            var requestIdToken = e["requestId"];
        //            if (requestIdToken == null)
        //            {
        //                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "requestId is null in Fetch.requestPaused event. Full event data logged.", this, GPALObjectType.PuppeteerCommunicator);
        //                // Add more context for debugging
        //                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Event context: sessionId={e.sessionId}, targetId={e.targetInfo?.targetId}, url={e.targetInfo?.url}", this, GPALObjectType.PuppeteerCommunicator);
        //                return; // Exit if requestId is missing
        //            }
 
        //            var requestId = requestIdToken.ToString();
        //            var responseStatusCode = e["responseStatusCode"]?.ToObject<int>() ?? 200;
        //            var resourceType = e["resourceType"]?.ToString();
 
        //            if (string.IsNullOrEmpty(resourceType) || (resourceType == "Document" && responseStatusCode >= 200 && responseStatusCode < 300))
        //            {
        //                try
        //                {
        //                    var response = await SendCommand<object>(DevToolsMethods.FetchGetResponseBody, new { requestId }, sessionId ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId);
        //                    var body = response["body"]?.ToString();
        //                    var isBase64 = response["base64Encoded"]?.ToObject<bool>() ?? false;
 
        //                    if (string.IsNullOrEmpty(body))
        //                    {
        //                        GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Empty body received for requestId: {requestId}", this, GPALObjectType.PuppeteerCommunicator);
        //                        await SendCommand<object>(DevToolsMethods.FetchContinueRequest, new { requestId }, sessionId ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId);
        //                        return;
        //                    }
 
        //                    if (isBase64)
        //                    {
        //                        body = Encoding.UTF8.GetString(Convert.FromBase64String(body));
        //                    }
 
        //                    // Extract the existing nonce from responseHeaders
        //                    string existingNonce = null;
        //                    var responseHeaders = e["responseHeaders"] as IEnumerable<dynamic>;
        //                    string cspHeader = null;
        //                    if (responseHeaders != null)
        //                    {
        //                        cspHeader = responseHeaders
        //                            .Where(h => h["name"].ToString().ToLower() == "content-security-policy")
        //                            .Select(h => h["value"].ToString())
        //                            .FirstOrDefault();
        //                        if (!string.IsNullOrEmpty(cspHeader))
        //                        {
        //                            var nonceMatch = System.Text.RegularExpressions.Regex.Match(cspHeader, @"nonce-([a-zA-Z0-9+/=]{16})");
        //                            if (nonceMatch.Success)
        //                            {
        //                                existingNonce = nonceMatch.Groups[1].Value;
        //                            }
        //                        }
        //                    }
 
        //                    // Use the existing nonce if found, otherwise generate a new one
        //                    var nonce = !string.IsNullOrEmpty(existingNonce) ? $"nonce-{existingNonce}" : $"nonce-{Guid.NewGuid().ToString("N").Substring(0, 16)}";
        //                    var modifiedBody = body.Replace(
        //                        "<head>",
        //                        $"<head><script {nonce}>{scriptToInject}</script>"
        //                    );
 
        //                    var responseHeadersList = new List<object>
        //        {
        //            new { name = "Content-Type", value = "text/html" }
        //        };
 
        //                    if (!string.IsNullOrEmpty(existingNonce) && cspHeader != null)
        //                    {
        //                        responseHeadersList.Add(new { name = "Content-Security-Policy", value = cspHeader });
        //                    }
        //                    else if (!string.IsNullOrEmpty(existingNonce))
        //                    {
        //                        responseHeadersList.Add(new { name = "Content-Security-Policy", value = $"script-src 'nonce-{existingNonce}' 'strict-dynamic' https: http:; object-src 'none';" });
        //                    }
        //                    else
        //                    {
        //                        responseHeadersList.Add(new { name = "Content-Security-Policy", value = $"script-src {nonce} 'strict-dynamic' https: http:; object-src 'none';" });
        //                    }
 
        //                    await SendCommand<object>(DevToolsMethods.FetchFulfillRequest, new
        //                    {
        //                        requestId,
        //                        responseCode = responseStatusCode,
        //                        responseHeaders = responseHeadersList,
        //                        body = Convert.ToBase64String(Encoding.UTF8.GetBytes(modifiedBody))
        //                    }, sessionId ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId);
 
        //                    GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Injected script into HTML response for requestId: {requestId} with nonce: {nonce}", this, GPALObjectType.PuppeteerCommunicator);
        //                }
        //                catch (Exception ex)
        //                {
        //                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Failed to inject script: {ex.Message}", this, GPALObjectType.Puppeteer, ex);
        //                    await SendCommand<object>(DevToolsMethods.FetchContinueRequest, new { requestId }, sessionId ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId);
        //                }
        //            }
        //            else
        //            {
        //                await SendCommand<object>(DevToolsMethods.FetchContinueRequest, new { requestId }, sessionId ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId);
        //            }
        //        };
 
        //        string eventKey = $"Fetch.requestPaused_{sessionId ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId}";
        //        _eventHandlers[eventKey] = handler;
 
        //        GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Subscribed to Fetch.requestPaused for sessionId: {sessionId ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId}", this, GPALObjectType.PuppeteerCommunicator);
        //    }
        //    catch (Exception ex)
        //    {
        //        GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Failed to enable Fetch script injection: {ex.Message}", this, GPALObjectType.Puppeteer, ex);
        //        throw;
        //    }
        //}
        internal async Task ReceivePipeMessages(CancellationToken ct)
        {
            // Signal: "I'm alive and reading"
            _readerReadyTcs?.SetResult(true);
 
            var stream = Browser.BrowserSettings.OutboundPipe; // FileStream (byte-oriented)
            if (stream == null || !stream.IsConnected || !stream.CanRead)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, "OutboundPipe null, disconnected, or not readable", this, GPALObjectType.PuppeteerCommunicator);
                return;
            }
 
            var encoding = Encoding.UTF8;
 
            // Helper to process one complete JSON text message (unchanged)
            void ProcessMessageString(string text)
            {
                try
                {
                    dynamic message = Newtonsoft.Json.JsonConvert.DeserializeObject(text);
                    if (message == null) return;
 
                    if (message.id != null)
                    {
                        if (_responseTasks.TryRemove((int)message.id, out TaskCompletionSource<dynamic> tcs))
                        {
                            if (message.error != null)
                            {
                                string errorMessage = (message.error.message != null ? message.error.message.ToString() :
                                                       message.error.ToString()) ?? "Unknown CDP error";
                                if (!errorMessage.Contains("wasn't found"))
                                    GPAL.PublishSimpleEvent(GPALEventType.ERROR, errorMessage, this, GPALObjectType.PuppeteerCommunicator);
                                tcs.TrySetResult(errorMessage);
                            }
                            else
                            {
                                tcs.TrySetResult(message);
                            }
                        }
                    }
                    else if (message.method != null)
                    {
                        string method = (string)message.method;
 
                        // turning the Page domain on to hear about dialogs brings every lifecycle and frame event with it,
                        // and the dynamic reads below are not cheap enough to run on all of them for nothing
                        if (true == method.StartsWith("Page.") && "Page.javascriptDialogOpening" != method)
                            return;
 
                        dynamic paramsData = message.@params;
                        string title = paramsData?.targetInfo?.title;
                        string targetType = paramsData?.targetInfo?.type?.ToString();
                        string sessionId = message.sessionId?.ToString() ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId;
                        string url = paramsData?.targetInfo?.url?.ToString() ?? "unknown";
 
                        if (method.StartsWith("Network."))
                        {
                            if (method == "Network.requestWillBeSent" ||
                                method == "Network.loadingFinished" ||
                                method == "Network.loadingFailed" ||
                                method == "Network.requestServedFromCache" ||
                                method == "Network.requestWillBeSentExtraInfo")
                            {
                                _events.Enqueue((method, paramsData));
                            }
 
                            // recorded before the suppression check, so a capture still sees the requests made
                            // while something else is waiting for the network to go quiet
                            if (true == CapturingCalls && "Network.requestWillBeSent" == method)
                                RecordCall(paramsData);
                            else if (true == CapturingCalls && "Network.responseReceived" == method)
                                RecordStatus(paramsData);
 
                            if (_suppressNetworkEvents)
                                return;
                        }
 
                        // a dialog stops the page dead until it is answered, so it is answered from here rather than
                        // handed to a workflow that cannot reach the page while one is up. the page's own alert,
                        // confirm and prompt are untouched, so nothing about this is visible to it
                        if ("Page.javascriptDialogOpening" == method && null != Browser.BrowserSettings.DialogsAccepted)
                        {
                            bool accept = true == Browser.BrowserSettings.DialogsAccepted;
                            string typed = Browser.BrowserSettings.DialogText;
 
                            GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Answering a [{paramsData?.type}] with accept [{accept}] text [{typed}]", this, GPALObjectType.PuppeteerCommunicator);
 
                            // not awaited, because this reader is the only thing that will ever see the reply arrive.
                            // and sent past the send semaphore, because the click that raised the dialog is holding it
                            // and cannot let go until the dialog is answered, which is what this is
                            _ = SendCommand<object>(DevToolsMethods.PageHandleJavaScriptDialog,
                                null == typed ? (object)new { accept } : new { accept, promptText = typed },
                                sessionId, 3, true);
                        }
 
                        if (method == "Target.targetCreated" && _sendSemaphore.CurrentCount == 1)
                        {
                            if (true == targetType?.Equals("page") && false == url?.StartsWith("chrome://") && false == url?.Equals("about:blank"))
                            {
                                string targetId = paramsData?.targetInfo?.targetId?.ToString();
                                string browserContextId = paramsData?.targetInfo?.browserContextId?.ToString();
                                if (!string.IsNullOrEmpty(targetId))
                                {
                                    // TODO: this needs to be pushed onto a queue, then the next time send 
                                    // Fire-and-forget is fine here
                                    _ = HandleNewTarget(targetId, browserContextId, null, true);
                                    GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Detected new uncontrolled tab: TargetId [{targetId}] in Window [{browserContextId}]", this, GPALObjectType.PuppeteerCommunicator);
                                }
                            }
                        }
 
                        GPAL.PublishSimpleEvent(GPALEventType.DEEPDEBUG, $"Received (pipe): [{text}]", this, GPALObjectType.PuppeteerCommunicator);
                    }
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Error processing pipe message", this, GPALObjectType.PuppeteerCommunicator, ex);
                }
            }
 
            // CDP over a pipe separates messages with a nul byte and never says how long one is. read bytes
            // until one turns up, and what came before it is a whole message
            var pending = new List<byte>();
            var chunk = new byte[65536];
 
            try
            {
                while (_isRunning && !Browser.BrowserSettings.Process.HasExited && !ct.IsCancellationRequested)
                {
                    var readTask = stream.ReadAsync(chunk, 0, chunk.Length, ct);
 
                    if (await Task.WhenAny(readTask, Task.Delay(5000, ct)).ConfigureAwait(false) != readTask)
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No data on OutboundPipe after 5s - Chrome not responding", this, GPALObjectType.PuppeteerCommunicator);
                        continue;
                    }
 
                    int bytesRead = readTask.Result;
 
                    if (0 == bytesRead)
                        break;   // EOF
 
                    for (int i = 0; i < bytesRead; i++)
                    {
                        if (0 != chunk[i])
                        {
                            pending.Add(chunk[i]);
                            continue;
                        }
 
                        // a nul with nothing before it is a separator after a message already taken
                        if (0 < pending.Count)
                        {
                            ProcessMessageString(encoding.GetString(pending.ToArray()));
                            pending.Clear();
                        }
                    }
                }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"ReceivePipeMessages failed", this, GPALObjectType.PuppeteerCommunicator, ex);
            }
        }
        private async Task ReceiveMessages(CancellationToken ct)
        {
            var buffer = new byte[102400];
 
            while (_isRunning && _webSocket.State == WebSocketState.Open)
            {
                // Check if the cancellation token was canceled before proceeding
                // prolly connecting to a new page after closing a tab or window?
                if (ct.IsCancellationRequested)
                {
                    // Handle cancellation gracefully
                    try
                    {
                        await _webSocket.CloseOutputAsync(WebSocketCloseStatus.NormalClosure, "Cancellation requested", CancellationToken.None).ConfigureAwait(false);
                        _webSocket.Dispose();
                    }
                    catch (Exception ex)
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Error during WebSocket cleanup on cancellation", this, GPALObjectType.PuppeteerCommunicator, ex);
                    }
                    break;
                }
 
                try
                {
                    using var ms = new System.IO.MemoryStream();
                    WebSocketReceiveResult result;
                    do
                    {
                        result = await _webSocket.ReceiveAsync(new ArraySegment<byte>(buffer), ct).ConfigureAwait(false);
                        ms.Write(buffer, 0, result.Count);
                    } while (!result.EndOfMessage);
 
                    try
                    {
                        if (result.MessageType == WebSocketMessageType.Close)
                        {
                            await _webSocket.CloseOutputAsync(WebSocketCloseStatus.NormalClosure, "WebSocket closed", CancellationToken.None).ConfigureAwait(false);
                            break;
                        }
                    }
                    catch (OperationCanceledException)
                    {
                        // Graceful cancellation
                    }
                    catch (WebSocketException ex)
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"WebSocket error", this, GPALObjectType.PuppeteerCommunicator, ex);
                    }
                    finally
                    {
                        if (_webSocket.State == WebSocketState.Closed || _webSocket.State == WebSocketState.Aborted)
                        {
                            try { await _webSocket.CloseAsync(WebSocketCloseStatus.NormalClosure, "Cleanup", CancellationToken.None).ConfigureAwait(false); } catch { }
                            _webSocket.Dispose();
                            _webSocket = null;
                        }
                    }
 
                    if (null != ms)
                    {
                        var json = Encoding.UTF8.GetString(ms.ToArray());
                        var message = Newtonsoft.Json.JsonConvert.DeserializeObject<dynamic>(json);
 
                        if (message?.id != null)
                        {
                            if (_responseTasks.TryRemove((int)message.id, out TaskCompletionSource<dynamic> tcs))
                            {
                                if (message.error != null)
                                {
                                    string errorMessage = (message.error.message != null ? message.error.message.ToString() :
                                                           message.error.ToString()) ?? "Unknown CDP error";
                                    if (false == errorMessage.Contains("wasn't found"))  // trying to remove a token we removed already
                                        GPAL.PublishSimpleEvent(GPALEventType.DEBUG, errorMessage, this, GPALObjectType.PuppeteerCommunicator);
                                    tcs.SetResult(errorMessage);
                                }
                                else
                                    tcs.SetResult(message);
                            }
                        }
                        else if (message.method != null)
                        {
                            string method = (string)message.method;
 
                            // turning the Page domain on to hear about dialogs brings every lifecycle and frame event with it,
                            // and the dynamic reads below are not cheap enough to run on all of them for nothing
                            // continue, not return: this one is the receive loop itself, and returning from it
                            // ends the reader for the life of the browser
                            if (true == method.StartsWith("Page.") && "Page.javascriptDialogOpening" != method)
                                continue;
 
                            dynamic paramsData = message.@params;
                            string title = paramsData.targetInfo?.title;
                            string targetType = paramsData.targetInfo?.type?.ToString();
                            string sessionId = message.sessionId?.ToString() ?? ((PuppeteerClient)PuppeteerClient)._currentTargetId;
                            string url = paramsData.targetInfo?.url?.ToString() ?? "unknown";
 
 
                            // Filter network events when suppressed
                            if (method.StartsWith("Network."))
                            {
                                // Always enqueue relevant network events
                                if (method == "Network.requestWillBeSent" ||
                                    method == "Network.loadingFinished" ||
                                    method == "Network.loadingFailed" ||
                                    method == "Network.requestServedFromCache" ||
                                    method == "Network.requestWillBeSentExtraInfo")
                                {
                                    _events.Enqueue((method, paramsData));
                                }
 
                                // recorded before the suppression check, so a capture still sees the requests made
                                // while something else is waiting for the network to go quiet
                                if (true == CapturingCalls && "Network.requestWillBeSent" == method)
                                    RecordCall(paramsData);
                                else if (true == CapturingCalls && "Network.responseReceived" == method)
                                    RecordStatus(paramsData);
 
                                if (method == "Network.responseReceived")
                                {
                                    // paramsData is message.@params
                                    string type = paramsData.type?.ToString();
 
                                    // We only care about "Document" (the actual HTML page)
                                    if (type == "Document")
                                    {
                                        this.ServerResponseCode = (int)paramsData.response.status;
                                        string responseUrl = paramsData.response.url?.ToString();
 
                                        Browser.ServerResponseCode = this.ServerResponseCode;
                                        //GPAL.PublishSimpleEvent(GPALEventType.DEBUG,
                                        //    $"HTTP Status Captured: [{this.ServerResponseCode}] for [{responseUrl}]",
                                        //    this, GPALObjectType.PuppeteerCommunicator);
 
                                        // You might want to store this in a field like: this.LastStatusCode = statusCode;
                                    }
                                }
                                if (_suppressNetworkEvents)
                                    continue; // Skip logging and further processing
                            }
 
                            if (method.StartsWith("Cast.")) // prolly just Cast.sinksUpdated
                            {
                                try
                                {
                                    JObject payload = paramsData;
                                    JToken sink = payload["sinks"];
                                    try
                                    {
                                        if (null != sink)
                                            CastDevices.Add(new CastDevice(sink[0]["name"]?.ToString(), sink[0]["id"]?.ToString()));
                                    } catch { } // index issue
 
                                    GPAL.PublishSimpleEvent(GPALEventType.DEBUG,
                                        $"[{method}] [{Newtonsoft.Json.JsonConvert.SerializeObject(paramsData)}]",
                                        this, GPALObjectType.PuppeteerCommunicator);
 
                                    // TODO: Store sinks globally so CastTo() can read them later and decipher friendly name
                                    // LastKnownSinks = paramsData.sinks;
                                }
                                catch (Exception ex)
                                {
                                    GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION,
                                        $"Error processing [{method}]",
                                        this, GPALObjectType.PuppeteerCommunicator, ex);
                                }
                            }
 
                            // a dialog stops the page dead until it is answered, so it is answered from here rather than
                            // handed to a workflow that cannot reach the page while one is up. the page's own alert,
                            // confirm and prompt are untouched, so nothing about this is visible to it
                            if ("Page.javascriptDialogOpening" == method && null != Browser.BrowserSettings.DialogsAccepted)
                            {
                                bool accept = true == Browser.BrowserSettings.DialogsAccepted;
                                string typed = Browser.BrowserSettings.DialogText;
 
                                GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Answering a [{paramsData?.type}] with accept [{accept}] text [{typed}]", this, GPALObjectType.PuppeteerCommunicator);
 
                                // not awaited, because this reader is the only thing that will ever see the reply arrive.
                                // and sent past the send semaphore, because the click that raised the dialog is holding it
                                // and cannot let go until the dialog is answered, which is what this is
                                _ = SendCommand<object>(DevToolsMethods.PageHandleJavaScriptDialog,
                                    null == typed ? (object)new { accept } : new { accept, promptText = typed },
                                    sessionId, 3, true);
                            }
 
                            if (method == "Target.targetCreated" && _sendSemaphore.CurrentCount == 1)
                            {
                                if (true == targetType.Equals("page") && false == url?.StartsWith("chrome://") && false == url?.Equals("about:blank"))
                                {
                                    string targetId = paramsData.targetInfo?.targetId?.ToString();
                                    string browserContextId = paramsData.targetInfo?.browserContextId?.ToString();
 
                                    if (!string.IsNullOrEmpty(targetId))
                                    {
                                        // Handle like NewTab: attach, enable domains, add to queue
                                        // TODO: this needs to be pushed onto a queue, then the next time send 
                                        await HandleNewTarget(targetId, browserContextId, null, true).ConfigureAwait(false);
                                        GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Detected new uncontrolled tab: TargetId [{targetId}] in Window [{browserContextId}]", this, GPALObjectType.PuppeteerCommunicator);
                                    }
                                }
                            }
                            //else if (method == "Target.targetInfoChanged" && _sendSemaphore.CurrentCount == 1)
                            //{
                            //    string targetId = paramsData.targetInfo?.targetId?.ToString();
                            //    string browserContextId = paramsData.targetInfo?.browserContextId?.ToString();
                            //    targetType = paramsData.targetInfo?.type?.ToString();
                            //    url = paramsData.targetInfo?.url?.ToString() ?? "unknown";
 
                            //    if (targetType == "page" && targetId != null && true == Browser.Started)
                            //    {
                            //        if (url.StartsWith("chrome://") || url == "about:blank")
                            //        {
                            //            ; GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Skipping tab info change: TargetId [{targetId}], URL [{url}]", this, GPALObjectType.PuppeteerCommunicator);
                            //        }
                            //        else
                            //        {
                            //            // Re-attach to ensure valid sessionId
                            //            var session = await SendCommand<object>(DevToolsMethods.TargetAttachToTarget, new { targetId, flatten = true }, null, 3, true);
                            //            string newSessionId = session?.sessionId?.ToString();
                            //            if (newSessionId != null)
                            //            {
                            //                await HandleNewTarget(targetId, browserContextId, newSessionId);
                            //                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Processed tab info change: TargetId [{targetId}] in Window [{browserContextId}], Session [{newSessionId}]", this, GPALObjectType.PuppeteerCommunicator);
                            //            }
                            //            else
                            //            {
                            //                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Failed to re-attach on Target.targetInfoChanged: TargetId [{targetId}]", this, GPALObjectType.PuppeteerCommunicator);
                            //            }
                            //        }
                            //    }
                            //}      
                            GPAL.PublishSimpleEvent(GPALEventType.DEEPDEBUG, $"Received: [{Newtonsoft.Json.JsonConvert.SerializeObject(message)}]", this, GPALObjectType.PuppeteerCommunicator);
                        }
                    }
                }
                catch (Exception ex)  // or catch (WebSocketException ex) if you want to be more specific
                {
                    string innerMsg = "";
 
                    // Option 1 – Simple & most common (recommended for logging)
                    if (ex.InnerException != null)
                    {
                        innerMsg = $" Inner: [{ex.InnerException.Message}]";
                        // Optional: also add type if helpful
                        // innerMsg += $" ({ex.InnerException.GetType().Name})";
                    }
 
                    string exMsg = $"Error receiving WebSocket message: [{ex.Message}][{innerMsg}]";
 
                    // Optional – even better: walk the full inner chain (very deep nesting is rare in WebSocket scenarios)
                    // string fullInnerChain = GetFullInnerExceptionMessage(ex);
 
                    GPAL.PublishSimpleEvent(
                        GPALEventType.DEEPDEBUG,
                        exMsg,
                        this,
                        GPALObjectType.Puppeteer,
                        ex);   // - still pass original ex (it already contains .InnerException)
 
                    // throw new ApplicationException(exMsg, ex);  // - Important: pass original ex as InnerException! // can't do this kills everything
                }
            }
        }

        private async Task HandleNewTarget(string targetId, string browserContextId, string newSessionId = null, bool doNotGetSendSemaphore = false, bool? isActive = null)
        {
            // a tab GPAL opened is the tab to be on, and a tab noticed arriving is not. that was being worked out
            // from whether a session id came with it, which had it exactly backwards: NewTab passes no session
            // and so marked the tab it just opened inactive, leaving every later command on the previous tab
            bool activeTab = isActive ?? !(null == newSessionId);
 
            // Add to the window's tab queue
            await AddTabToQueue(targetId, newSessionId, activeTab, doNotGetSendSemaphore).ConfigureAwait(false);
 
            // Set as active tab (mimic NewTab behavior)
            //SetActiveTabIndex(CurrentSessions.Count - 1);
 
            // a new tab is a new session with the Network domain off, so a capture that was on for the page that
            // opened it would go quiet exactly where the interesting request is
            if (true == CapturingCalls)
                await CaptureCalls(true, newSessionId).ConfigureAwait(false);
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Handled new target: ID [{targetId}] in Window [{browserContextId}]", this, GPALObjectType.PuppeteerCommunicator);
        }
        public async Task WaitForEvent(string eventName, TimeSpan timeout)
        {
            var start = DateTime.UtcNow;
            while (DateTime.UtcNow - start < timeout)
            {
                if (_events.TryDequeue(out var evt) && evt.Event == eventName)
                    return;
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Waiting for [{eventName}] got [{evt.Event}]", this, GPALObjectType.PuppeteerCommunicator);
                await Task.Delay(100).ConfigureAwait(false);
            }
            GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Event [{eventName}] not received within [{timeout.TotalSeconds}]s", this, GPALObjectType.PuppeteerCommunicator);
        }

        public async Task<bool> WaitForLayoutReady(GPALElement element, string sessionId, int maxWaitMs = 3000, int pollIntervalMs = 150)
        {
            var stopwatch = System.Diagnostics.Stopwatch.StartNew();
            sessionId ??= GetEffectiveSessionId();
 
            while (stopwatch.ElapsedMilliseconds < maxWaitMs)
            {
                // Option A: Try CDP box model (most accurate)
                var box = await SendCommand<dynamic>(
                    DevToolsMethods.DOMGetBoxModel,
                    new { backendNodeId = element.ElementBackendNodeId },
                    sessionId
                ).ConfigureAwait(false);
 
                if (box?.model?.content != null)
                {
                    var quad = box.model.content;
                    if (quad.Count >= 8 && quad[2] > quad[0] && quad[7] > quad[1]) // width & height > 0
                    {
                        return true;
                    }
                }
                else if (null == box)   // no box model? maybe it got detached? try to find the new element?
                {
                    List<GPALElement> elems = await EvaluateSelector(element.Css, sessionId).ConfigureAwait(false);
                    if (0 < elems.Count)
                    {
                        element.ElementBackendNodeId = elems[0].ElementBackendNodeId;
                        element.ElementHandle = elems[0].ElementHandle;
                        element.ElementNodeId = elems[0].ElementNodeId;
                        element.Css = elems[0].Css;
                        element.Xpath = elems[0].Xpath;
                    }
                }
 
                // Option B: Fallback to JS dimensions check (works even if CDP box fails)
                var jsResult = await SendCommand<dynamic>(
                    DevToolsMethods.RuntimeEvaluate,
                    new
                    {
                        expression = $@"
                        (function() {{
                            const el = document.querySelector('{element.Css}') ||
                                       document.evaluate('{element.Xpath}', document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
                            if (!el) return false;
                            const r = el.getBoundingClientRect();
                            return r.width > 0.1 && r.height > 0.1 && r.top >= 0; // visible-ish
                        }})()",
                        contextId = CurrentContextId,
                        returnByValue = true
                    },
                    sessionId
                ).ConfigureAwait(false);
 
                if (jsResult?.result?.value is bool visible && visible)
                {
                    return true;
                }
 
                await Task.Delay(pollIntervalMs).ConfigureAwait(false);
            }
 
            GPAL.PublishSimpleEvent(GPALEventType.WARNING,
                $"Timeout waiting for layout on [{element.TagName}][{element.Css ?? element.Xpath}] after [{maxWaitMs}]ms",
                this, GPALObjectType.PuppeteerCommunicator);
 
            return false;
        }

        /// <param name="sessionId">The CDP session used to issue the creation commands; if null, the effective session ID is resolved automatically.</param>
        /// <returns>A task that resolves to the CDP target ID of the newly created tab.</returns>
        /// <example>
        /// <code>
        /// string targetId = await communicator.CreateTarget("https://example.com", newWindow: true);
        /// </code>
        /// </example>
        public async Task<string> CreateTarget(string url, bool newWindow = false, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            url = MagicHelper.GetFullUrl(url, Browser, out Browser._areRobotsAllowed);
 
            if (false == Browser.AreRobotsAllowed && true == Browser.BrowserSettings.ObeyRobotsTxt)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Visiting [{url}] is disallowed by robots.txt and your request to honor it. Not going to URL. Workflow will fail.", this, GPALObjectType.PuppeteerCommunicator);
                url = "https://google.com";
            }
 
            object parameters = new { url };
            if (newWindow)
            {
                var context = await SendCommand<object>(DevToolsMethods.TargetCreateBrowserContext, new { }, sessionId).ConfigureAwait(false);
                string browserContextId = context.browserContextId.ToString();
                parameters = new { url, browserContextId };
            }
 
            var result = await SendCommand<object>(DevToolsMethods.TargetCreateTarget, parameters, null).ConfigureAwait(false); // null for browser-level
            string targetId = result.targetId.ToString();
            await SendCommand<object>(DevToolsMethods.TargetActivateTarget, new { targetId }, null).ConfigureAwait(false);
            var session = await SendCommand<object>(DevToolsMethods.TargetAttachToTarget, new { targetId, flatten = true }, null).ConfigureAwait(false);
            string newSessionId = session.sessionId.ToString();
            await AddTabToQueue(targetId, newSessionId).ConfigureAwait(false); // Add to queue, set active
 
            // Enable Page domain for new tab
            //await SendCommand<object>(DevToolsMethods.PageEnable, new { }, newSessionId);
 
            return targetId;
        }
        internal async Task CloseOutputWebSocketAsync()
        {
            // Close the WebSocket connection with a normal closure status and an empty description
            try
            {
                if (null != _webSocket)
                    await _webSocket.CloseOutputAsync(WebSocketCloseStatus.NormalClosure, "Client closing", CancellationToken.None).ConfigureAwait(false);
            }
            catch
            {
                // we are terminating anyways...
            }
        }
        internal async Task<string> GetInitialTargetId(string sessionId)
        {
            dynamic targets = await SendCommand<dynamic>(DevToolsMethods.TargetGetTargets, new { }, null).ConfigureAwait(false);
            var pageTarget = ((IEnumerable<dynamic>)targets.targetInfos).FirstOrDefault(t => (string)t.type == "page");  // Cast to IEnumerable<dynamic> and use typed lambda
            return pageTarget != null ? (string)pageTarget.targetId : null;
        }
        internal async Task<int> TabCount()
        {
            dynamic targets = await SendCommand<dynamic>(DevToolsMethods.TargetGetTargets, new { }, null).ConfigureAwait(false);
            return ((IEnumerable<dynamic>)targets.targetInfos).Count(t => (string)t.type == "page");
        }
        /// <param name="sessionId">Unused; reserved for future use.</param>
        /// <returns>A task that resolves to the browser context ID (window ID) of the window containing a matching tab, or null if no match is found.</returns>
        /// <example>
        /// <code>
        /// string windowId = await communicator.GetTargetWindowIdByUrl("https://example.com/dashboard");
        /// </code>
        /// </example>
        public async Task<string> GetTargetWindowIdByUrl(string url, string sessionId = null)
        {
            if (string.IsNullOrWhiteSpace(url))
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "URL is empty or null in GetTargetWindowIdByUrl", this, GPALObjectType.PuppeteerCommunicator);
                return null;
            }
 
            url = MagicHelper.GetFullUrl(url, Browser, out bool _); // Normalize URL (e.g., add "https://" if needed)
            var windowArray = _windowSessionsQueue.ToArray();
            foreach (var window in windowArray)
            {
                var tabArray = window.TabQueue.ToArray();
                foreach (var tab in tabArray)
                {
                    var targetInfo = await SendCommand<object>(DevToolsMethods.TargetGetTargetInfo, new { targetId = tab.Key }, null).ConfigureAwait(false);
                    string targetUrl = targetInfo?.targetInfo?.url?.ToString();
                    if (targetUrl != null && targetUrl.Contains(url))
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Found window with browserContextId [{window.BrowserContextId}] for URL [{url}]", this, GPALObjectType.PuppeteerCommunicator);
                        return window.BrowserContextId; // Return the window's BrowserContextId
                    }
                }
            }
 
            GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"No window found with a tab matching URL [{url}]", this, GPALObjectType.PuppeteerCommunicator);
            return null;
        }
        /// <param name="sessionId">The CDP session used to resolve the effective session if needed; if null, the effective session ID is resolved automatically.</param>
        /// <returns>A task that resolves to the CDP target ID of the matching tab, the current target ID if <paramref name="url"/> was empty, or null if no match is found.</returns>
        /// <example>
        /// <code>
        /// string tabId = await communicator.GetTargetTabIdByUrl("https://example.com/page2");
        /// </code>
        /// </example>
        public async Task<string> GetTargetTabIdByUrl(string url, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            if (string.IsNullOrWhiteSpace(url))
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "URL is empty or null in GetTargetTabIdByUrl", this, GPALObjectType.PuppeteerCommunicator);
                return GetCurrentTargetId();
            }
 
            url = MagicHelper.GetFullUrl(url, Browser, out bool _);
            var windowArray = _windowSessionsQueue.ToArray();
 
            if (_activeWindowIndex >= 0 && _activeWindowIndex < windowArray.Length)
            {
                var tabArray = windowArray[_activeWindowIndex].TabQueue.ToArray();
                foreach (var tab in tabArray)
                {
                    var targetInfo = await SendCommand<object>(DevToolsMethods.TargetGetTargetInfo, new { targetId = tab.Key }, null).ConfigureAwait(false);
                    string targetUrl = targetInfo?.targetInfo?.url?.ToString();
                    if (targetUrl != null)
                    {
                        string decodedTarget = Uri.UnescapeDataString(targetUrl);
                        string decodedUrl = Uri.UnescapeDataString(url);
 
                        if (true == decodedTarget.Contains(decodedUrl))
                        {
                            GPAL.PublishSimpleEvent(GPALEventType.DEBUG,
                                $"Found tab with targetId [{tab.Key}] for URL [{url}] in active window",
                                this, GPALObjectType.PuppeteerCommunicator);
 
                            return tab.Key;
                        }
                    }
                }
            }
 
            for (int i = 0; i < windowArray.Length; i++)
            {
                if (i == _activeWindowIndex) continue;
                var tabArray = windowArray[i].TabQueue.ToArray();
                foreach (var tab in tabArray)
                {
                    var targetInfo = await SendCommand<object>(DevToolsMethods.TargetGetTargetInfo, new { targetId = tab.Key }, null).ConfigureAwait(false);
                    string targetUrl = targetInfo?.targetInfo?.url?.ToString();
                    if (targetUrl != null && targetUrl.Contains(url))
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Found tab with targetId [{tab.Key}] for URL [{url}] in window [{i}]", this, GPALObjectType.PuppeteerCommunicator);
                        return tab.Key;
                    }
                }
            }
 
            GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"No tab found with URL [{url}]", this, GPALObjectType.PuppeteerCommunicator);
            return null;
        }
        internal async Task<string> GetNextWindowId(string id, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var targets = await SendCommand<object>(DevToolsMethods.TargetGetTargets, new { }, null).ConfigureAwait(false);
            var windowList = ((IEnumerable<dynamic>)targets.targetInfos)
                .Where(t => t.type == "browser" || t.type == "page")
                .GroupBy(t => t.browserContextId ?? t.targetId)
                .Select(g => g.First())
                .OrderBy(t => t.targetId)
                .ToList();
            for (int i = 0; i < windowList.Count; i++)
            {
                if (windowList[i].targetId.ToString() == id)
                {
                    return i < windowList.Count - 1 ? windowList[i + 1].targetId.ToString() : null;
                }
            }
            GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"No next window found for ID: [{id}]", this, GPALObjectType.PuppeteerCommunicator);
            return null;
        }
        internal async Task<string> GetPreviousWindowId(string id, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var targets = await SendCommand<object>(DevToolsMethods.TargetGetTargets, new { }, null).ConfigureAwait(false);
            var windowList = ((IEnumerable<dynamic>)targets.targetInfos)
                .Where(t => t.type == "browser" || t.type == "page")
                .GroupBy(t => t.browserContextId ?? t.targetId)
                .Select(g => g.First())
                .OrderBy(t => t.targetId)
                .ToList();
            for (int i = 0; i < windowList.Count; i++)
            {
                if (windowList[i].targetId.ToString() == id)
                {
                    return i > 0 ? windowList[i - 1].targetId.ToString() : null;
                }
            }
            GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"No previous window found for ID: [{id}]", this, GPALObjectType.PuppeteerCommunicator);
            return null;
        }
        public async Task<int> QueryByCss(string selector, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            //await WaitForEvent("Page.loadEventFired", TimeSpan.FromSeconds(10));
 
            var doc = await SendCommand<object>(DevToolsMethods.DOMGetDocument, new { depth = 0 }, sessionId).ConfigureAwait(false);
            var result = await SendCommand<object>(DevToolsMethods.DOMQuerySelector, new { nodeId = (int)doc.root.nodeId, selector }, sessionId).ConfigureAwait(false);
 
            var nodeId = (int)result.nodeId;
 
            if (nodeId == 0)
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"No nodes found for Css: [{selector}]", this, GPALObjectType.PuppeteerCommunicator);
 
            return nodeId;
        }
        public class Node
        {
            public string ObjectId { get; set; }

            public int BackendNodeId { get; set; }
            public int NodeId { get; set; }
        }
 
        private readonly SemaphoreSlim _evaluateSelectorSemaphore = new SemaphoreSlim(1, 1);

        /// <summary>
        /// Resolves an iframe element matching the given selector and switches the current evaluation context
        /// into that iframe by attaching to its frame target (for cross-origin frames) and creating an isolated
        /// JavaScript execution world. Subsequent DOM/JS operations will operate inside the iframe until
        /// the context is reset.
        /// </summary>
        /// <param name="frameSelector">A CSS or XPath selector identifying the iframe element.</param>
        public async Task SwitchToFrame(string frameSelector)
        {
            // Cleared on a context change: a remote object from the previous context resolves nothing and the
            // failure looks like a bad selector
            CurrentRootObjectId = null;
 
 
            var elements = await EvaluateSelector(frameSelector, isRecursive: true).ConfigureAwait(false);
            if (elements.Count == 0)
            {
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, "Frame not found: " + frameSelector, this, GPALObjectType.PuppeteerCommunicator);
                return;
            }
 
            var iframeElement = elements[0];
 
            var describe = await SendCommand<dynamic>(DevToolsMethods.DOMDescribeNode, new
            {
                objectId = iframeElement.ElementHandle,
                pierce = true
            }, GetEffectiveSessionId()).ConfigureAwait(false);
 
            string frameId = describe?.node?.frameId?.ToString();
 
            if (string.IsNullOrEmpty(frameId))
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, "No frameId for frame [" + frameSelector + "]", this, GPALObjectType.PuppeteerCommunicator);
                return;
            }
 
            CurrentFrameId = frameId;
 
            // drop any session left over from a previously resolved iframe - the attach below is allowed to fail
            // silently for same-origin frames, and without this a stale cross-origin session would be reused
            CurrentFrameSessionId = null;
 
            // Try to attach to frame target (works for cross-origin OOPIFs)
            try
            {
                var attach = await SendCommand<dynamic>(DevToolsMethods.TargetAttachToTarget, new
                {
                    targetId = frameId,
                    flatten = true
                }, null).ConfigureAwait(false);
 
                string frameSessionId = attach?.sessionId?.ToString();
                if (!string.IsNullOrEmpty(frameSessionId))
                    CurrentFrameSessionId = frameSessionId;
            }
            catch
            {
                // Normal for same-origin iframes - ignore
            }
 
            // Always create isolated world (works for both same-origin and cross-origin)
            await Task.Delay(300).ConfigureAwait(false);
 
            var isolated = await SendCommand<dynamic>(DevToolsMethods.PageCreateIsolatedWorld, new
            {
                frameId = frameId,
                worldName = "gpal_isolated_" + Guid.NewGuid().ToString("N"),
                grantUniversalAccess = false
            // a cross-origin frame lives in its own target, so the world has to be created on that target's
            // session - the page session does not know the frame at all. same-origin falls back to the page.
            }, GetEffectiveSessionId()).ConfigureAwait(false);
 
            CurrentContextId = isolated?.executionContextId?.ToObject<long?>();
 
            if (CurrentContextId.HasValue)
            {
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG,
                    "Resolved iframe [" + frameSelector + "] | FrameId: " + frameId + " | ContextId: " + CurrentContextId.Value,
                    this, GPALObjectType.PuppeteerCommunicator);
            }
            else
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, "Failed to create isolated world for " + frameSelector, this, GPALObjectType.PuppeteerCommunicator);
            }
        }

        /// as the root they resolve against. CDP has no current element, so the scope is held here and only the
        /// element lookup goes over the wire.
        /// <br/><br/>
        /// Not a substitute for entering a frame. A frame needs its own execution context, which
        /// <see cref="SwitchToFrame"/> attaches to, and a cross-origin iframe is not reachable as a node.
        /// </summary>
        /// <param name="elementSelector">A CSS or XPath selector identifying the element to search inside.</param>
        public async Task SwitchToElement(string elementSelector)
        {
            var found = await EvaluateSelector(elementSelector, isRecursive: true).ConfigureAwait(false);
 
            if (0 == found.Count)
            {
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, "Element to search inside not found: " + elementSelector, this, GPALObjectType.PuppeteerCommunicator);
                return;
            }
 
            // The element's remote object, which querySelector is called on. SwitchToShadowDom differs only in
            // taking one further hop to the shadowRoot
            CurrentRootObjectId = found[0].ElementHandle;
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG,
                "Searching inside [" + elementSelector + "] | ObjectId: " + CurrentRootObjectId,
                this, GPALObjectType.PuppeteerCommunicator);
        }
 
        public async Task SwitchToShadowDom(string shadowHostSelector)
        {
            var hosts = await EvaluateSelector(shadowHostSelector, isRecursive: true).ConfigureAwait(false);
            if (hosts.Count == 0)
            {
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, "Shadow host not found: " + shadowHostSelector, this, GPALObjectType.PuppeteerCommunicator);
                return;
            }
 
            var host = hosts[0];
            var s = GetEffectiveSessionId();
 
            var describe = await SendCommand<dynamic>(DevToolsMethods.DOMDescribeNode, new
            {
                objectId = host.ElementHandle,
                pierce = true,
                depth = 1
            }, s).ConfigureAwait(false);
 
            var shadowRoots = describe?.node?.shadowRoots as IEnumerable<dynamic>;
 
            if (shadowRoots?.Any() != true)
            {
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, "No shadow root on host: " + shadowHostSelector, this, GPALObjectType.PuppeteerCommunicator);
                return;
            }
 
            var shadowRoot = shadowRoots.First();
 
            if (shadowRoot.backendNodeId != null)
            {
                var resolve = await SendCommand<dynamic>(DevToolsMethods.DOMResolveNode, new
                {
                    backendNodeId = (long)shadowRoot.backendNodeId
                }, s).ConfigureAwait(false);
 
                if (resolve?.@object?.objectId != null)
                {
                    CurrentRootObjectId = (string)resolve.@object.objectId;
                }
            }
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG,
                "Resolved shadow DOM [" + shadowHostSelector + "] | ObjectId: " + CurrentRootObjectId,
                this, GPALObjectType.PuppeteerCommunicator);
        }
        
        /// (via <see cref="SwitchToFrame"/>). If nothing is found and the call is not recursive, it performs
        /// a deep search by recursively evaluating the selector inside any iframe targets.
        /// </summary>
        /// <param name="selector">A CSS selector, XPath expression, numeric node id, or CDP remote object id.</param>
        /// <param name="sessionId">CDP session id; the effective session (or current session, if inside an isolated iframe context) is used if null.</param>
        /// <param name="isRecursive">True when this call is a recursive deep search inside an iframe; suppresses the outer iframe search and the evaluation semaphore.</param>
        /// <returns>Task that resolves to the list of matching elements, or an empty list if none were found or an error occurred.</returns>
        public async Task<List<GPALElement>> EvaluateSelector(string selector, string sessionId = null, bool isRecursive = false)
        {
            var elements = new List<GPALElement>();
 
            // an explicit session (a recursive deep search) wins, otherwise use the effective one: the isolated
            // world is created on whichever target owns the frame, so its context id is only meaningful on that
            // same session. cross-origin frames have their own, same-origin frames fall back to the page session.
            string effectiveSessionId = (!string.IsNullOrEmpty(sessionId) && sessionId != GetCurrentSessionId())
                ? sessionId
                : GetEffectiveSessionId();
 
            if (false == isRecursive)
                await _evaluateSelectorSemaphore.WaitAsync().ConfigureAwait(false);
 
            try
            {
                var nodes = new List<Node>();
 
                bool inRootContext = !string.IsNullOrEmpty(CurrentRootObjectId);
 
                // When we have an isolated world (from ResolveIframe), use MAIN session for runtime commands
                // but keep effectiveSessionId for DOM commands when finding child iframes
                bool useIsolatedContext = CurrentContextId.HasValue;
 
                if (inRootContext)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.DEBUG,
                        "Evaluating inside the scope set by InShadowDom or InElement, for selector [" + selector + "]",
                        this, GPALObjectType.PuppeteerCommunicator);
                }
 
                try
                {
                    // NodeId / ObjectId handling
                    bool isNodeId = int.TryParse(selector, out int tmpNodeId);
                    bool isObjectId = System.Text.RegularExpressions.Regex.IsMatch(selector, @"^-?\d+\.\d+\.\d+$");
 
                    // Enable pierce so shadow roots (and iframes) are visible in the DOM tree
                        await SendCommand<object>(DevToolsMethods.DOMGetDocument, new
                        {
                            pierce = true,
                            depth = 20
                        }, effectiveSessionId).ConfigureAwait(false);
 
                    // === SCOPED QUERY (when .InShadowDom() or .InElement() is active) ===
                    if (inRootContext && !isNodeId && !isObjectId)
                    {
                        try
                        {
                            var shadowQueryResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeCallFunctionOn, new
                            {
                                objectId = CurrentRootObjectId,
                                functionDeclaration = @"
                                    function(selector) {
                                        let nodes = [];
                                        try {
                                            const cssNodes = this.querySelectorAll(selector);
                                            if (cssNodes?.length > 0) {
                                                nodes = Array.from(cssNodes);
                                            }
                                        } catch (e) {}
 
                                        if (nodes.length === 0) {
                                            try {
                                                const result = document.evaluate(selector, this, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
                                                for (let i = 0; i < result.snapshotLength; i++) {
                                                    const node = result.snapshotItem(i);
                                                    if (node?.getBoundingClientRect) {
                                                        node.getBoundingClientRect();
                                                        nodes.push(node);
                                                    }
                                                }
                                            } catch (e) {}
                                        }
                                        return { nodes: nodes };
                                    }",
                                arguments = new[] { new { value = selector } },
                                contextId = CurrentContextId,
                                returnByValue = false
                            }, effectiveSessionId).ConfigureAwait(false);
 
                            if (shadowQueryResult?.result?.objectId != null)
                            {
                                // Get wrapper { nodes: [...] }
                                var wrapper = await SendCommand<dynamic>(DevToolsMethods.RuntimeGetProperties,
                                    new { 
                                        objectId = (string)shadowQueryResult.result.objectId,
                                        contextId = CurrentContextId,
                                        ownProperties = true 
                                    }, effectiveSessionId).ConfigureAwait(false);
 
                                string nodesArrayId = null;
 
                                // Find "nodes" property without lambda
                                if (wrapper?.result != null)
                                {
                                    foreach (var p in wrapper.result)
                                    {
                                        if (p.name == "nodes" && p.value?.objectId != null)
                                        {
                                            nodesArrayId = (string)p.value.objectId;
                                            break;
                                        }
                                    }
                                }
 
                                if (!string.IsNullOrEmpty(nodesArrayId))
                                {
                                    // Get array items
                                    var arrayProps = await SendCommand<dynamic>(DevToolsMethods.RuntimeGetProperties,
                                        new { 
                                            objectId = nodesArrayId,
                                            contextId = CurrentContextId,
                                            ownProperties = true 
                                        }, effectiveSessionId).ConfigureAwait(false);
 
                                    nodes.Clear();
 
                                    if (arrayProps?.result != null)
                                    {
                                        foreach (var item in arrayProps.result)
                                        {
                                            var val = item.value;
                                            if (val != null
                                                && val.type == "object"
                                                && val.subtype == "node"
                                                && val.objectId != null)
                                            {
                                                nodes.Add(new Node { ObjectId = (string)val.objectId });
                                            }
                                        }
                                    }
                                }
 
                                if (nodes.Count > 0)
                                    goto ProcessFoundNodes;
                            }
                        }
                        catch (Exception ex)
                        {
                            GPAL.PublishSimpleEvent(GPALEventType.DEBUG,
                                $"Shadow DOM query failed for [{selector}]. Falling back to main path.",
                                this, GPALObjectType.PuppeteerCommunicator, ex);
                        }
                    }
 
                    if (isNodeId || isObjectId)
                    {
                        var requestNodeResult = await SendCommand<object>(DevToolsMethods.DOMRequestNode, new { objectId = selector }, effectiveSessionId).ConfigureAwait(false);
                        if (requestNodeResult?.nodeId != null)
                        {
                            var nodeId = (int)requestNodeResult.nodeId;
                            var resolveNodeResult = await SendCommand<object>(DevToolsMethods.DOMResolveNode, new { nodeId }, effectiveSessionId).ConfigureAwait(false);
                            if (resolveNodeResult?.@object?.objectId != null)
                            {
                                var describeNode = await SendCommand<object>(DevToolsMethods.DOMDescribeNode, new { objectId = (string)resolveNodeResult.@object.objectId, pierce = true }, effectiveSessionId).ConfigureAwait(false);
                                nodes.Add(new Node
                                {
                                    ObjectId = (string)resolveNodeResult.@object.objectId,
                                    BackendNodeId = describeNode?.node?.backendNodeId ?? 0,
                                    NodeId = nodeId
                                });
                            }
                        }
                    }
                    else
                    {
                        // === YOUR ORIGINAL JS EVALUATION PATH (100% unchanged) ===
                        string jsFunc = @"
                        function evaluateSelector(selector) {
                            let nodes = [];
                            let type = 'unknown';
                            let error = null;
 
                            // Try CSS first
                            try {
                                const cssNodes = document.querySelectorAll(selector);
                                if (cssNodes.length > 0) {
                                    nodes = Array.from(cssNodes);
                                    type = 'css';
                                }
                            } catch (e) {}
 
                            // If CSS failed, try XPath
                            if (nodes.length === 0) {
                                try {
                                    const result = document.evaluate(
                                        selector,
                                        document,
                                        null,
                                        XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
                                        null
                                    );
 
                                    // Force CDP to wrap each node by accessing a layout property
                                    for (let i = 0; i < result.snapshotLength; i++) {
                                        const node = result.snapshotItem(i);
                                        if (node && node.getBoundingClientRect) {
                                            // This forces CDP to create a RemoteObject with objectId
                                            node.getBoundingClientRect();
                                            nodes.push(node);
                                        }
                                    }
 
                                    if (nodes.length > 0) {
                                        type = 'xpath';
                                    } else {
                                        error = 'No elements found for selector [' + selector + ']';
                                    }
                                } catch (e) {
                                    error = 'Invalid XPath or error: ' + e.message;
                                }
                            }
 
                            return { nodes: nodes };
                        }";
 
                        string escapedSelector = selector;
                        var evalResult = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
                        {
                            expression = $"({jsFunc})(\"{escapedSelector}\")",
                            contextId = CurrentContextId,
                            returnByValue = false
                        }, effectiveSessionId).ConfigureAwait(false);
 
                        if (evalResult?.result?.objectId != null)
                        {
                            var nodesProps = await SendCommand<object>(DevToolsMethods.RuntimeGetProperties, 
                                new { 
                                    objectId = (string)evalResult.result.objectId,
                                    contextId = CurrentContextId,
                                    ownProperties = true 
                                }, effectiveSessionId).ConfigureAwait(false);
                            dynamic errorProp = null;
 
                            if (nodesProps?.result != null)
                            {
                                foreach (var p in nodesProps.result)
                                {
                                    if (p.name == "error" && p.value != null && p.value.value != null)
                                    {
                                        errorProp = p;
                                        break;
                                    }
                                }
                            }
 
                            if (errorProp != null)
                            {
                                string errMsg = (string)errorProp.value.value ?? "Unknown selector error";
                                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"[{errMsg}]", this, GPALObjectType.PuppeteerCommunicator);
                                if (false == isRecursive)
                                    return new List<GPALElement>();
                            }
 
                            foreach (var prop in nodesProps.result)
                            {
                                if (prop.name == "nodes" && prop.value?.objectId != null)
                                {
                                    var nodeArray = await SendCommand<object>(DevToolsMethods.RuntimeGetProperties, 
                                        new { 
                                            objectId = (string)prop.value.objectId,
                                            contextId = CurrentContextId,
                                            ownProperties = true 
                                        }, effectiveSessionId).ConfigureAwait(false);
                                    foreach (var np in nodeArray.result)
                                    {
                                        if (np.value != null && np.value.type == "object" && np.value.subtype == "node")
                                            nodes.Add(new Node { ObjectId = (string)np.value.objectId });
                                    }
                                }
                            }
                        }
                    }
 
                ProcessFoundNodes:
 
                    // Sequential per-node extraction (your original logic - completely untouched)
                    foreach (var node in nodes)
                    {
                        try
                        {
                            var attributes = new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
 
                            var describeNode = await SendCommand<object>(DevToolsMethods.DOMDescribeNode, new { objectId = node.ObjectId, pierce = true }, effectiveSessionId).ConfigureAwait(false);
                            if (describeNode?.node != null)
                            {
                                node.BackendNodeId = describeNode.node.backendNodeId ?? 0;
                                var requestNodeResult = await SendCommand<object>(DevToolsMethods.DOMRequestNode, new
                                {
                                    objectId = node.ObjectId
                                }, effectiveSessionId).ConfigureAwait(false);
 
                                node.NodeId = requestNodeResult.nodeId;
                                attributes["tagName"] = describeNode.node.nodeName;
                            }
 
                            var jsProps = await SendCommand<object>(DevToolsMethods.RuntimeCallFunctionOn, new
                            {
                                functionDeclaration = @"
                            function() {
                                const rect = this.getBoundingClientRect();
                                const cleanText = (str) => (str || '').replace(/\s+/g, ' ').trim();
 
                                const attrs = {
                                    enabled: !this.disabled,
                                    // a checkbox says checked and an option says selected, and Selected is
                                    // one question over both of them, the way it is on selenium
                                    selected: this.checked === true || this.selected === true,
                                    indeterminate: this.indeterminate === true,
                                    displayed: this.offsetParent !== null,
                                    href: this.href || '',
                                    src: this.src || '',
 
                                    value: cleanText(this.value),
                                    text: cleanText(this.text || this.innerText),
                                    placeholder: cleanText(this.placeholder),
 
                                    index: this.index || '',
                                    length: this.files ? this.files.length : this.length || '',
                                    type: this.type || '',
                                    id: this.id || '',
                                };
                                for (let {name,value} of Array.from(this.attributes||[])) attrs[name]=value;
 
                                // Force boolean properties last - multiple not getting set above, being dropped by cdp?
                                attrs.multiple = this.multiple === true;
 
                                function getCss(el){
                                    if(!(el instanceof Element)) return '';
                                    const parts=[];
                                    while(el && el.nodeType===1){
                                        let part=el.nodeName.toLowerCase();
                                        if(el.id){part+='#'+el.id; parts.unshift(part); break;}
                                        let sib=el, nth=1;
                                        while((sib=sib.previousElementSibling)!=null){if(sib.nodeName.toLowerCase()===part)nth++;}
                                        if(nth>1) part+=':nth-of-type('+nth+')';
                                        parts.unshift(part); el=el.parentElement;
                                    }
                                    return parts.join(' > ');
                                }
                                return {attributes:attrs,css:getCss(this),boundingRect:{x:rect.x,y:rect.y,width:rect.width,height:rect.height,top:rect.top,left:rect.left,bottom:rect.bottom,right:rect.right}};
                            }",
                                objectId = node.ObjectId,
                                contextId = CurrentContextId,
                                returnByValue = true
                            }, effectiveSessionId).ConfigureAwait(false);
 
                            if (jsProps?.result?.value != null)
                            {
                                var dict = ((Newtonsoft.Json.Linq.JObject)jsProps.result.value).ToObject<Dictionary<string, object>>();
 
                                if (dict.ContainsKey("attributes"))
                                {
                                    var jsAttrDict = ((Newtonsoft.Json.Linq.JObject)dict["attributes"]).ToObject<Dictionary<string, object>>();
                                    foreach (var kvp in jsAttrDict) if (!attributes.ContainsKey(kvp.Key)) attributes[kvp.Key] = kvp.Value;
                                }
 
                                if (dict.ContainsKey("boundingRect"))
                                {
                                    var brObj = ((Newtonsoft.Json.Linq.JObject)dict["boundingRect"]).ToObject<Dictionary<string, object>>();
                                    float ToFloat(object o)
                                    {
                                        if (o is double d) return (float)d;
                                        if (o is long l) return (float)l;
                                        if (o is int i) return (float)i;
                                        if (o is string s && float.TryParse(s, out var r)) return r;
                                        return 0f;
                                    }
 
                                    var rect = new ClientRectangle
                                    {
                                        X = ToFloat(brObj.ContainsKey("x") ? brObj["x"] : 0),
                                        Y = ToFloat(brObj.ContainsKey("y") ? brObj["y"] : 0),
                                        Width = ToFloat(brObj.ContainsKey("width") ? brObj["width"] : 0),
                                        Height = ToFloat(brObj.ContainsKey("height") ? brObj["height"] : 0),
                                        Top = ToFloat(brObj.ContainsKey("top") ? brObj["top"] : 0),
                                        Left = ToFloat(brObj.ContainsKey("left") ? brObj["left"] : 0),
                                        Bottom = ToFloat(brObj.ContainsKey("bottom") ? brObj["bottom"] : 0),
                                        Right = ToFloat(brObj.ContainsKey("right") ? brObj["right"] : 0)
                                    };
 
                                    attributes["boundingRect"] = rect;
                                    attributes["location"] = new System.Drawing.Point((int)rect.X, (int)rect.Y);
                                    attributes["size"] = new System.Drawing.Size((int)rect.Width, (int)rect.Height);
                                }
 
                                if (dict.ContainsKey("css")) attributes["css"] = dict["css"]?.ToString();
                            }
 
                            attributes["xpath"] = await GetXPathForElement(node.BackendNodeId).ConfigureAwait(false);
 
                            elements.Add(new GPALElement(attributes, Browser)
                            {
                                ElementHandle = node.ObjectId,
                                ElementBackendNodeId = node.BackendNodeId,
                                ElementNodeId = node.NodeId
                            });
                        }
                        catch
                        {
                            // Skip failed nodes
                        }
                    }
 
                    // Recurse into iframes if still nothing found (questionable if this every found anything - fix the selector)
                    //if (!elements.Any() && false == isRecursive)
                    //{
                    //    GPAL.PublishSimpleEvent(GPALEventType.DEBUG, "Element STILL not found, performing deep search in iframes.", this, GPALObjectType.PuppeteerCommunicator);
 
                    //    var targets = await SendCommand<object>(DevToolsMethods.TargetGetTargets, new { }, null).ConfigureAwait(false);
                    //    var iframeTargets = ((IEnumerable<dynamic>)targets.targetInfos).Where(t => t.type == "iframe");
                    //    foreach (var target in iframeTargets)
                    //    {
                    //        var frameSession = await SendCommand<object>(DevToolsMethods.TargetAttachToTarget, new { targetId = (string)target.targetId, flatten = true }, null).ConfigureAwait(false);
                    //        var frameSessionId = (string)frameSession.sessionId;
 
                    //        var frameElements = await EvaluateSelector(selector, frameSessionId, true).ConfigureAwait(false);
                    //        if (frameElements.Any())
                    //            return frameElements;
                    //    }
                    //}
 
                    return elements;
                }
                catch
                {
                    return new List<GPALElement>();
                }
            }
            finally
            {
                if (false == isRecursive)
                    _evaluateSelectorSemaphore.Release();
            }
        }
 
        // generate selectors from backendnodeid
        /// <summary>
        /// Generates a CSS selector string that uniquely identifies the element with the given backend node id.
        /// </summary>
        /// <param name="backendNodeId">The CDP backend node id of the element.</param>
        /// <param name="optimized">Whether to prefer a shorter, optimized selector (e.g. using the element's id) when possible.</param>
        /// <param name="sessionId">CDP session id; the effective session is used if null.</param>
        /// <returns>Task that resolves to the generated CSS selector, or an empty string if it could not be determined.</returns>
        public async Task<string> GetCssForElement(int backendNodeId, bool optimized = false, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            string jsFunc = @"
                    function getCssSelector(node) {
//                        console.log('getCssSelector called with node:', node);
 
                        if (!node || node.nodeType !== Node.ELEMENT_NODE) {
                            console.error('Invalid node, returning empty string');
                            return '';
                        }
 
                        if (node.id) {
//                            console.log('Found ID:', node.id);
                            return '#' + node.id.replace(/([ #.;+*~'!^$[\‍]()=>|\/@])/g, '\\$1');
                        }
 
                        let selector = node.localName.toLowerCase();
//                        console.log('Tag name:', selector);
 
                        if (node.classList && node.classList.length > 0) {
                            const classes = Array.from(node.classList)
                                .filter(c => c && /^[a-zA-Z][\w-]*$/.test(c))
                                .map(c => c.replace(/([ #.;+*~'!^$[\‍]()=>|\/@])/g, '\\$1'));
                            if (classes.length > 0) {
                                selector += '.' + classes.join('.');
                            }
 //                           console.log('Selector with classes:', selector);
                        }
 
                        try {
                            const matches = document.querySelectorAll(selector);
 //                           console.log('Matches for selector:', matches.length, selector);
                            if (matches.length === 1 && matches[0] === node) {
                                return selector;
                            }
                        } catch (e) {
 //                           console.error('Error in querySelectorAll:', e.message);
                            return '';
                        }
 
 //                       console.log('Returning fallback selector:', selector);
                        return selector;
                }";
            return await GetXPathOrCssForElement(backendNodeId, jsFunc, optimized, sessionId).ConfigureAwait(false);
        }
        /// <summary>
        /// Generates an XPath expression that identifies the element with the given backend node id.
        /// </summary>
        /// <param name="backendNodeId">The CDP backend node id of the element.</param>
        /// <param name="optimized">Whether to prefer a shorter, optimized path (e.g. using the element's id) when possible.</param>
        /// <param name="sessionId">CDP session id; the effective session is used if null.</param>
        /// <returns>Task that resolves to the generated XPath expression, or an empty string if it could not be determined.</returns>
        public async Task<string> GetXPathForElement(int backendNodeId, bool optimized = true, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            // Your full JS template as a string
            string jsFunc = @"
                function getXPathForElement(node, optimized) {
                    let Elements = { DOMPath: {} };
 
                    Elements.DOMPath.xPath = function(node, optimized) {
                        if (node.nodeType === Node.DOCUMENT_NODE) return '/';
                        const steps = [];
                        let contextNode = node;
                        while (contextNode) {
                            const step = Elements.DOMPath._xPathValue(contextNode, optimized);
                            if (!step) break;
                            steps.push(step);
                            if (step.optimized) break;
                            contextNode = contextNode.parentNode;
                        }
                        steps.reverse();
                        return (steps.length && steps[0].optimized ? '' : '/') + steps.map(step => step.value).join('/');
                    };
 
                    Elements.DOMPath._xPathValue = function(node, optimized) {
                        let ownValue;
                        const ownIndex = Elements.DOMPath._xPathIndex(node);
                        if (ownIndex === -1) return null;
                        switch (node.nodeType) {
                            case Node.ELEMENT_NODE:
                                if (optimized && node.getAttribute('id'))
                                    return new Elements.DOMPath.Step('//*[@id=\'' + node.getAttribute('id') + '\']', true);
                                ownValue = node.localName;
                                break;
                            case Node.ATTRIBUTE_NODE:
                                ownValue = '@' + node.nodeName;
                                break;
                            case Node.TEXT_NODE:
                            case Node.CDATA_SECTION_NODE:
                                ownValue = 'text()';
                                break;
                            case Node.PROCESSING_INSTRUCTION_NODE:
                                ownValue = 'processing-instruction()';
                                break;
                            case Node.COMMENT_NODE:
                                ownValue = 'comment()';
                                break;
                            case Node.DOCUMENT_NODE:
                                ownValue = '';
                                break;
                            default:
                                ownValue = '';
                                break;
                        }
                        if (ownIndex > 0)
                            ownValue += '[' + ownIndex + ']';
                        return new Elements.DOMPath.Step(ownValue, node.nodeType === Node.DOCUMENT_NODE);
                    };
 
                    Elements.DOMPath._xPathIndex = function(node) {
                        function areNodesSimilar(left, right) {
                            if (left === right) return true;
                            if (left.nodeType === Node.ELEMENT_NODE && right.nodeType === Node.ELEMENT_NODE)
                                return left.localName === right.localName;
                            if (left.nodeType === right.nodeType) return true;
                            const leftType = left.nodeType === Node.CDATA_SECTION_NODE ? Node.TEXT_NODE : left.nodeType;
                            const rightType = right.nodeType === Node.CDATA_SECTION_NODE ? Node.TEXT_NODE : right.nodeType;
                            return leftType === rightType;
                        }
                        const siblings = node.parentNode ? node.parentNode.children : null;
                        if (!siblings) return 0;
                        let hasSameNamedElements;
                        for (let i = 0; i < siblings.length; ++i) {
                            if (areNodesSimilar(node, siblings[i]) && siblings[i] !== node) {
                                hasSameNamedElements = true;
                                break;
                            }
                        }
                        if (!hasSameNamedElements) return 0;
                        let ownIndex = 1;
                        for (let i = 0; i < siblings.length; ++i) {
                            if (areNodesSimilar(node, siblings[i])) {
                                if (siblings[i] === node) return ownIndex;
                                ++ownIndex;
                            }
                        }
                        return -1;
                    };
 
                    Elements.DOMPath.Step = function(value, optimized) {
                        this.value = value;
                        this.optimized = optimized || false;
                    };
 
                    return Elements.DOMPath.xPath(node, optimized);
                }";
            return await GetXPathOrCssForElement(backendNodeId, jsFunc, optimized, sessionId);
        }
        /// function on it to compute a selector or path string.
        /// </summary>
        /// <param name="backendNodeId">The CDP backend node id of the element to resolve.</param>
        /// <param name="jsFunc">A JavaScript function declaration that takes (node, optimized) and returns the selector/path string.</param>
        /// <param name="optimized">Whether the JavaScript function should prefer a shorter, optimized result.</param>
        /// <param name="sessionId">CDP session id to use for the resolve and evaluate commands.</param>
        /// <returns>Task that resolves to the computed selector/path string, or an empty string on failure.</returns>
        public async Task<string> GetXPathOrCssForElement(int backendNodeId, string jsFunc, bool optimized, string sessionId)
        {
            try
            {
                // Resolve to objectId using backendNodeId
                var resolve = await SendCommand<dynamic>(DevToolsMethods.DOMResolveNode, new { backendNodeId, pierce = true }, sessionId).ConfigureAwait(false);
                string objectId = resolve.@object.objectId;
 
                // Call function
                var result = await SendCommand<dynamic>(DevToolsMethods.RuntimeCallFunctionOn, new
                {
                    objectId,
                    functionDeclaration = $"function(optimized) {{ return ({jsFunc})(this, optimized); }}",
                    arguments = new object[] { new { value = optimized } },
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
 
                // Release objectId to prevent leak
                //await SendCommand<object>(DevToolsMethods.RuntimeReleaseObject, new { objectId }, sessionId);
 
                return result?.result?.value?.ToString() ?? "";
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR,
                    $"Failed to get XPath for backendNodeId [{backendNodeId}]",
                    this, GPALObjectType.PuppeteerCommunicator, ex);
                return "";
            }
        }
 
        // Helper method to get attributes
        static Dictionary<string, string> GetAttributesAsDictionary(string jsonString)
        {
            try
            {
                using System.Text.Json.JsonDocument doc = System.Text.Json.JsonDocument.Parse(jsonString);
 
                // Navigate to the 'node' object
                if (!doc.RootElement.TryGetProperty("node", out System.Text.Json.JsonElement nodeElement))
                {
                    return null;
                }
 
                // Navigate to the 'attributes' array
                if (!nodeElement.TryGetProperty("attributes", out System.Text.Json.JsonElement attributesElement) ||
                    attributesElement.ValueKind != System.Text.Json.JsonValueKind.Array)
                {
                    return null;
                }
 
                var dict = new Dictionary<string, string>();
                for (int i = 0; i < attributesElement.GetArrayLength() - 1; i += 2)
                {
                    string key = attributesElement[i].GetString();
                    string value = attributesElement[i + 1].GetString();
                    dict[key] = value;
                }
 
                return dict;
            }
            catch (System.Text.Json.JsonException)
            {
                return null; // Invalid JSON
            }
        }
        public async Task LeftClickByCss(string selector, string sessionId = null)
        {
            List<GPALElement> elems = await EvaluateSelector(selector, sessionId).ConfigureAwait(false);
            List<dynamic> responses = new List<dynamic>();
 
            foreach (GPALElement elem in elems)
                await ClickElement(elem, sessionId, responses, ClickType.LeftClick).ConfigureAwait(false);
        }

        public async Task<dynamic> ExecuteJavaScript(string expression, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            return await SendCommand<object>(DevToolsMethods.RuntimeEvaluate,
                new {
                    expression,
                    contextId = CurrentContextId,
                    returnByValue = true,
                    awaitPromise = true
                }
                , sessionId).ConfigureAwait(false);
        }

        internal string LastNavigationError { get; set; }

        /// Starts or stops recording what the browser asks for, reported over the DevTools protocol.
        /// Every session GPAL knows about is told, not only the active tab, because a click that opens a tab
        /// is exactly the request worth seeing.
        /// <example>await browser.PuppeteerCommunicator.CaptureCalls(true);</example>
        /// </summary>
        /// <param name="capture">True to record, false to stop</param>
        /// <param name="sessionId">The session to tell, or null for every session known</param>
        public async Task CaptureCalls(bool capture, string sessionId = null)
        {
            CapturingCalls = capture;
 
            // nothing is reported until the Network domain is on, and it is not on at startup. it is on per
            // session rather than per browser, so every tab GPAL knows about is told, not just the active one:
            // a click that opens a tab is exactly the request worth seeing. sending it twice to one session is
            // harmless, so nothing has to work out which of these it already told
            if (true == capture)
                foreach (string session in KnownSessions(sessionId))
                    await SendCommand<object>(DevToolsMethods.NetworkEnable, new { }, session).ConfigureAwait(false);
        }
 
        // the session handed in, the effective one, and every tab of every window, without repeats
        private List<string> KnownSessions(string sessionId)
        {
            List<string> retVal = new List<string>();
 
            foreach (string session in new[] { sessionId, GetEffectiveSessionId() })
                if (false == string.IsNullOrEmpty(session) && false == retVal.Contains(session))
                    retVal.Add(session);
 
            foreach (WindowSession window in _windowSessionsQueue.ToArray())
                foreach (KeyValuePair<string, string> tab in window.TabQueue.ToArray())
                    if (false == string.IsNullOrEmpty(tab.Value) && false == retVal.Contains(tab.Value))
                        retVal.Add(tab.Value);
 
            return retVal;
        }
 
        // the status the site answered this request with, matched back to it by the browser's own request id
        private void RecordStatus(dynamic paramsData)
        {
            try
            {
                string requestId = paramsData?.requestId?.ToString();
 
                if (false == string.IsNullOrEmpty(requestId) && true == _capturedById.TryGetValue(requestId, out GPALCall call))
                    call.Status = (int)(paramsData?.response?.status ?? 0);
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Could not record a response status", this, GPALObjectType.PuppeteerCommunicator, ex);
            }
        }
 
        // one line of the network tab, kept as the fields a workflow would act on rather than the whole event
        private void RecordCall(dynamic paramsData)
        {
            try
            {
                GPALCall call = new GPALCall
                {
                    Url = paramsData?.request?.url?.ToString(),
                    Method = paramsData?.request?.method?.ToString(),
                    ResourceType = paramsData?.type?.ToString(),
                    PostData = paramsData?.request?.postData?.ToString(),
                    Initiator = paramsData?.initiator?.type?.ToString()
                };
 
                // what the page's own code put on the request, which is the half a hand-built call is missing
                if (paramsData?.request?.headers is Newtonsoft.Json.Linq.JObject headers)
                    foreach (KeyValuePair<string, Newtonsoft.Json.Linq.JToken> header in headers)
                        call.Headers[header.Key] = header.Value?.ToString();
 
                // a filter narrows what is kept rather than what is asked for, so nothing is missed by a
                // declaration made after the fact, only unrecorded
                string filter = Browser?.BrowserSettings?.CallFilter;
 
                if (false == string.IsNullOrEmpty(filter) && true != call.Url?.Contains(filter))
                    return;
 
                call.RequestId = paramsData?.requestId?.ToString();
 
                if (false == string.IsNullOrEmpty(call.RequestId))
                    _capturedById[call.RequestId] = call;
 
                CapturedCalls.Add(call);
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Could not record a request", this, GPALObjectType.PuppeteerCommunicator, ex);
            }
        }
 
        internal async Task SetExtraHttpHeaders(Dictionary<string, object> headers, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            // the Network domain has to be on before it will accept this, and it is not enabled at startup. Without
            // it the command is accepted and quietly does nothing, which reads as the credentials being wrong
            await SendCommand<object>(DevToolsMethods.NetworkEnable, new { }, sessionId).ConfigureAwait(false);
            await SendCommand<object>(DevToolsMethods.NetworkSetExtraHTTPHeaders, new { headers }, sessionId).ConfigureAwait(false);
        }
 
        public async Task<bool> NavigateToUrl(string url, string sessionId)
        {
            _attachedFilesPerSession.Clear();
            var result = await SendCommand<object>(DevToolsMethods.PageNavigate, new { url }, sessionId).ConfigureAwait(false);
 
            // a navigation that fails still answers, and answers with a perfectly good result carrying errorText,
            // so the presence of a result says only that the command was accepted, never that a page loaded
            LastNavigationError = (result as Newtonsoft.Json.Linq.JObject)?["errorText"]?.ToString();
 
            if (null == result)
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Failed to Go to [{url}]", this, GPALObjectType.PuppeteerCommunicator);
            else if (false == string.IsNullOrEmpty(LastNavigationError))
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Failed to Go to [{url}][{LastNavigationError}]", this, GPALObjectType.PuppeteerCommunicator);
            else
                //await WaitForEvent("Page.loadEventFired", TimeSpan.FromSeconds(30));
                GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Go to [{url}]", this, GPALObjectType.PuppeteerCommunicator);
 
            return null != result && true == string.IsNullOrEmpty(LastNavigationError);
        }
 
        // Implementation for "back"
        /// <param name="sessionId">CDP session id; the effective session is used if null.</param>
        /// <returns>Task that resolves to the navigation result, or null if there is no previous history entry.</returns>
        /// <example>
        /// <code>
        /// await communicator.Back();
        /// </code>
        /// </example>
        public async Task<dynamic> Back(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            dynamic history = await SendCommand<object>(DevToolsMethods.PageGetNavigationHistory, new { }, sessionId).ConfigureAwait(false);
            if (history?.currentIndex != null)
            {
                var entries = (IEnumerable<dynamic>)history.entries;
                var nextEntry = entries.ElementAtOrDefault((int)history.currentIndex - 1);
                if (nextEntry?.id != null)
                {
                    var result = await SendCommand(DevToolsMethods.PageNavigateToHistoryEntry, new { entryId = (int)nextEntry.id }, sessionId).ConfigureAwait(false);
                    return result;
                }
            }
            GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No previous page in history", this, GPALObjectType.PuppeteerClient);
            return null;
        }
 
        // Implementation for "capture-visible-tab"

        public async Task<dynamic> CaptureVisibleTab(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            return await SendCommand<object>(DevToolsMethods.PageCaptureScreenshot, new { format = "png" }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for CastDesktop
        /// <param name="sinkName">The display name of the Cast sink/device to mirror to.</param>
        /// <param name="sessionId">CDP session id; the effective session is used if null.</param>
        /// <example>
        /// <code>
        /// await communicator.CastDesktop("Living Room TV", sessionId);
        /// </code>
        /// </example>
        public async Task CastDesktop(string sinkName, string sessionId)
        {
            CastDevice sink = null;
            int retries = 10;
            sessionId ??= GetEffectiveSessionId();
 
            await SendCommand<object>(DevToolsMethods.CastDisable, null, sessionId).ConfigureAwait(false);
 
            while (null == sink && 0 < retries--)
            {
                GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Searching for [{sinkName}].", this, GPALObjectType.PuppeteerCommunicator);
                await SendCommand<object>(DevToolsMethods.CastEnable, new { }, sessionId).ConfigureAwait(false);
 
                await Task.Delay(3_000).ConfigureAwait(false);
 
                sink = CastDevices.Find(device => device.name == sinkName);
            }
 
            await Task.Delay(3_000).ConfigureAwait(false);
 
            if (null != sink)
            {
                GPAL.PublishSimpleEvent(GPALEventType.INFO, $"[{sinkName}] found.", this, GPALObjectType.PuppeteerCommunicator);
                SinkName = sinkName;
                object param = new { sinkName = sink.name };
 
                // cast or javascript, not both
                await SendCommand<object>(DevToolsMethods.CastStartDesktopMirroring, param, sessionId).ConfigureAwait(false);
            }
            else
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"[{sinkName}] NOT found.", this, GPALObjectType.PuppeteerCommunicator);
        }
 
        // Implementation for CastTab
        /// <param name="sinkName">The display name of the Cast sink/device to mirror to.</param>
        /// <param name="sessionId">CDP session id; the effective session is used if null.</param>
        /// <example>
        /// <code>
        /// await communicator.CastTab("Living Room TV", sessionId);
        /// </code>
        /// </example>
        public async Task CastTab(string sinkName, string sessionId)
        {
            CastDevice sink = null;
            int retries = 10;
            sessionId ??= GetEffectiveSessionId();
 
            await SendCommand<object>(DevToolsMethods.CastDisable, null, sessionId).ConfigureAwait(false);
 
            while (null == sink && 0 < retries--)
            {
                GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Searching for [{sinkName}].", this, GPALObjectType.PuppeteerCommunicator);
                await SendCommand<object>(DevToolsMethods.CastEnable, new { }, sessionId).ConfigureAwait(false);
 
                await Task.Delay(3_000).ConfigureAwait(false);
 
                sink = CastDevices.Find(device => device.name == sinkName);
            }
 
            await Task.Delay(3_000).ConfigureAwait(false);
 
            if (null != sink)
            {
                GPAL.PublishSimpleEvent(GPALEventType.INFO, $"[{sinkName}] found.", this, GPALObjectType.PuppeteerCommunicator);
                SinkName = sinkName;
                object param = new { sinkName = sink.name };
 
                // cast or javascript, not both
                await SendCommand<object>(DevToolsMethods.CastStartTabMirroring, param, sessionId).ConfigureAwait(false);
            }
            else
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"[{sinkName}] NOT found.", this, GPALObjectType.PuppeteerCommunicator);
        }
 
        // Implementation for "stop-casting"
        /// <param name="sessionId">CDP session id to send the stop-casting command on.</param>
        /// <returns>Task that resolves to true once the stop attempt has completed (regardless of whether casting actually stopped).</returns>
        /// <example>
        /// <code>
        /// await communicator.StopCasting(sessionId);
        /// </code>
        /// </example>
        public async Task<bool> StopCasting(string sessionId)
        {
            // NOTE: there may be no programmatic way to cleanly stop casting except to close the tab or window. This doesn't seem to work.
            try
            {
                await SendCommand<object>(DevToolsMethods.CastStopCasting, new { sinkName = SinkName }, sessionId).ConfigureAwait(false);
            }
            catch { }
 
            Thread.Sleep(500);
 
            return true;
        }
 
        // Implementation for "check-network-idle"
        /// </summary>
        /// <param name="sessionId">CDP session id; the effective session is used if null.</param>
        /// <param name="maxConnections">Reserved for future use; currently not enforced.</param>
        /// <param name="timeoutMs">The maximum total time, in milliseconds, to wait for the network to become idle.</param>
        /// <param name="pruneMs">The duration of inactivity, in milliseconds, required to consider the network idle.</param>
        /// <param name="sessionToken">An opaque token used to deduplicate repeated status messages across calls.</param>
        /// <returns>Task that resolves to true if the network became idle within the timeout, otherwise false.</returns>
        public async Task<bool> CheckNetworkIdle(string sessionId = null, int maxConnections = 0, int timeoutMs = 30000, int pruneMs = 3000, string sessionToken = null)
        {
            bool retVal = false;
            GPALEventType consoleTypeSave = GPAL.GPALSettings.ConsoleEvents;
            GPALEventType debugTypeSave = GPAL.GPALSettings.DebugEvents;
            string currentErrorMessage = null;
 
 
            if (lastSessionToken != sessionToken)
            {
                lastErrorMessage.Clear();
                supressedMessage = false;
                lastSessionToken = sessionToken;
            }
 
            currentErrorMessage = $"Waiting up to [{timeoutMs}] ms for network to idle to [{maxConnections}] connections for [{pruneMs}] ms";
 
            GPAL.PublishSimpleEvent(GPALEventType.INFO, currentErrorMessage, this, GPALObjectType.PuppeteerCommunicator);
 
            try
            {
                _suppressNetworkEvents = true; // Suppress non-essential network events
                await SendCommand(DevToolsMethods.NetworkEnable, new { cacheDisabled = true }, sessionId).ConfigureAwait(false);
                var start = DateTime.UtcNow;
                DateTime? lastRequestTime = null;
                var pendingEvents = new List<(string Event, dynamic Data, DateTime Timestamp)>();
                int unmatchedCount = 0; // Track unmatched events to throttle logging
                bool isFirstIteration = true; // Flag for initial queue debugging
 
                sessionId ??= GetEffectiveSessionId();
 
                await Task.Delay(500).ConfigureAwait(false);
 
                // Track network events
                while (DateTime.UtcNow - start < TimeSpan.FromMilliseconds(timeoutMs))
                {
                    // Collect events with timestamps
                    while (_events.TryDequeue(out (string Event, dynamic Data) evt))
                    {
                        pendingEvents.Add((evt.Event, evt.Data, DateTime.UtcNow));
                    }
 
                    // Sort events by timestamp to process in order
                    pendingEvents.Sort((a, b) => a.Timestamp.CompareTo(b.Timestamp));
 
                    // Process events
                    foreach (var evt in pendingEvents)
                    {
                        string requestId = evt.Data?.requestId?.ToString() ?? "unknown";
                        string url = evt.Data?.url?.ToString() ?? "unknown";
                        string resourceType = evt.Data?.resourceType?.ToString() ?? "unknown";
                        string initiator = evt.Data?.initiator?.type?.ToString() ?? "unknown";
                        string frameId = evt.Data?.frameId?.ToString() ?? "unknown";
                        string loaderId = evt.Data?.loaderId?.ToString() ?? "unknown";
                        string dataJson = evt.Data != null ? Newtonsoft.Json.JsonConvert.SerializeObject(evt.Data) : "null";
 
                        if (evt.Event == "Network.requestWillBeSent")
                        {
                            lastRequestTime = DateTime.UtcNow;
                            //GPAL.PublishSimpleEvent(GPALEventType.DEEPDEBUG, $"[{(isFirstIteration ? "Initial " : "")}] Request started: requestId=[{requestId}], url=[{url}], resourceType=[{resourceType}], initiator=[{initiator}], frameId=[{frameId}], loaderId=[{loaderId}], data=[{dataJson}]", this, GPALObjectType.PuppeteerCommunicator);
                        }
                        else if (evt.Event == "Network.requestWillBeSentExtraInfo")
                        {
                            string associatedRequestId = evt.Data?.associatedRequestId?.ToString();
                            //GPAL.PublishSimpleEvent(GPALEventType.DEEPDEBUG, $"[{(isFirstIteration ? "Initial " : "")}] Redirected request: requestId=[{requestId}], associatedRequestId=[{associatedRequestId}], url=[{url}], resourceType=[{resourceType}], initiator=[{initiator}], frameId=[{frameId}], loaderId=[{loaderId}], data=[{dataJson}]", this, GPALObjectType.PuppeteerCommunicator);
                        }
                        else if (evt.Event == "Network.loadingFinished" || evt.Event == "Network.loadingFailed")
                        {
                            unmatchedCount++;
                            if (unmatchedCount % 10 == 0) // Throttle logging
                            {
                                //GPAL.PublishSimpleEvent(GPALEventType.DEEPDEBUG, $"No matching request for [{evt.Event}]: requestId=[{requestId}], url=[{url}], resourceType=[{resourceType}], initiator=[{initiator},] frameId=[{frameId}], loaderId=[{loaderId}], data=[{dataJson}], unmatchedCount=[{unmatchedCount}]", this, GPALObjectType.PuppeteerCommunicator);
                            }
                        }
                        else if (evt.Event == "Network.requestServedFromCache")
                        {
                            //GPAL.PublishSimpleEvent(GPALEventType.DEEPDEBUG, $"[{(isFirstIteration ? "Initial " : "")}] Cached request: requestId=[{requestId}], url=[{url}], resourceType=[{resourceType}], initiator=[{initiator}], frameId=[{frameId}], loaderId=[{loaderId}], data=[{dataJson}], activeConnections=0", this, GPALObjectType.PuppeteerCommunicator);
                        }
                        else if (isFirstIteration)
                        {
                            //GPAL.PublishSimpleEvent(GPALEventType.DEEPDEBUG, $"Discarded initial event: [{evt.Event}], requestId=[{requestId}], url=[{url}], resourceType=[{resourceType}], initiator=[{initiator}], frameId=[{frameId}], loaderId=[{loaderId}], data=[{dataJson}]", this, GPALObjectType.PuppeteerCommunicator);
                        }
                    }
                    pendingEvents.Clear(); // Clear processed events
 
                    // Check for idle condition
                    if (lastRequestTime == null || (DateTime.UtcNow - lastRequestTime >= TimeSpan.FromMilliseconds(pruneMs)))
                    {
                        retVal = true; // No new requests for pruneMs
                        break;
                    }
 
                    // Log initial state after first iteration
                    if (isFirstIteration)
                    {
                        isFirstIteration = false;
                    }
 
                    await Task.Delay(50, _cts.Token).ConfigureAwait(false); // Reduced polling delay for responsiveness
                }
 
                // Final debug log
                //GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"CheckNetworkIdle complete: unmatchedCount=[{unmatchedCount}], result=[{retVal}]", this, GPALObjectType.PuppeteerCommunicator);
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Failed to check network idle", null, GPALObjectType.PuppeteerCommunicator, ex);
            }
            finally
            {
                // only turn the domain off if this method is what turned it on. Credentials presented as a header
                // live in the Network domain's state, so disabling here would quietly drop them and the next
                // request would come back a 401 with nothing in the log to explain it
                if (null == Browser?.BrowserSettings.CredentialsPresented)
                    await SendCommand(DevToolsMethods.NetworkDisable, new { }, sessionId).ConfigureAwait(false);
 
                _suppressNetworkEvents = false; // Re-enable event processing
 
                currentErrorMessage = $"Network IS{(retVal ? "" : " NOT")} Idle. Status [{retVal}]";
 
                if (false == lastErrorMessage.Contains(currentErrorMessage))
                {
                    lastErrorMessage.Add(currentErrorMessage);
                    GPAL.PublishSimpleEvent(GPALEventType.INFO, currentErrorMessage, this, GPALObjectType.PuppeteerCommunicator);
                    supressedMessage = false;
                }
                else if (false == supressedMessage)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.INFO, "Supressing repeat messages", currentErrorMessage, GPALObjectType.Other);
                    supressedMessage = true;
                }
            }
            return retVal;
        }
      
        // Implementation for "clear-referrer"

        public async Task ClearReferrer(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            await SendCommand<object>(DevToolsMethods.NetworkSetExtraHTTPHeaders, new { headers = new { Referer = "" } }, sessionId).ConfigureAwait(false);
        }

        private void CheckForLastBrowserWindowOpen(string reason)
        {
            if (_windowSessionsQueue.IsEmpty)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"[{reason}] : Last window closed, **BE CAREFUL AND DO NOT** try to run browser commands until another browser is opened.", this, GPALObjectType.PuppeteerCommunicator);
            }
        }
        /// <param name="sessionId">CDP session id; the effective session is used if null.</param>
        /// <returns>Task that resolves to true if the tab (and possibly its now-empty window) was closed successfully.</returns>
        /// <example>
        /// <code>
        /// await communicator.CloseTab(url: "https://example.com");
        /// </code>
        /// </example>
        public async Task<bool> CloseTab(string url = null, string tabId = null, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            string targetId = tabId ?? (url != null ? await GetTargetTabIdByUrl(url).ConfigureAwait(false) : GetCurrentTargetId());
            return await CloseTab(targetId, sessionId).ConfigureAwait(false);
        }
        /// <summary>
        /// Closes the browser tab with the given target id, removes it from the internal tab queue, and
        /// closes its parent window if that was the last remaining tab.
        /// </summary>
        /// <param name="targetId">The CDP target id of the tab to close.</param>
        /// <param name="sessionId">CDP session id; the effective session is used if null.</param>
        /// <returns>Task that resolves to true if the tab was closed (and the parent window closed, if it became empty), otherwise false.</returns>
        public async Task<bool> CloseTab(string targetId, string sessionId = null)
        {
            bool retVal = false;
            if (string.IsNullOrEmpty(targetId))
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No targetId provided for CloseTab", this, GPALObjectType.PuppeteerCommunicator);
            }
            else
            {
 
                await SendCommand<object>(DevToolsMethods.TargetCloseTarget, new { targetId }, null).ConfigureAwait(false);
                bool removed = RemoveTabFromQueue(targetId);
                if (!removed)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Failed to remove tab [{targetId}] from queue", this, GPALObjectType.PuppeteerCommunicator);
                }
 
                var windowArray = _windowSessionsQueue.ToArray();
                if (windowArray.Length == 0 || _activeWindowIndex >= windowArray.Length)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"No active window after closing tab [{targetId}]", this, GPALObjectType.PuppeteerCommunicator);
                    retVal = true;
                }
                else
                {
                    var tabQueue = windowArray[_activeWindowIndex].TabQueue;
                    if (tabQueue != null && tabQueue.IsEmpty)
                    {
                        string browserContextId = windowArray[_activeWindowIndex].BrowserContextId;
                        await CloseWindow(browserContextId, sessionId).ConfigureAwait(false);
                        GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Closed window for targetId [{targetId}] (context [{browserContextId}]) as it has no tabs", this, GPALObjectType.PuppeteerCommunicator);
                        retVal = true;
                    }
                }
            }
            CheckForLastBrowserWindowOpen("CloseTab()");
            return retVal;
        }
        /// <param name="sessionId">CDP session id; currently unused but reserved for future use.</param>
        /// <returns>Task that resolves to true if the window and all its tabs were closed successfully, otherwise false.</returns>
        /// <example>
        /// <code>
        /// await communicator.CloseWindow(browserContextId);
        /// </code>
        /// </example>
        public async Task<bool> CloseWindow(string browserContextId, string sessionId = null)
        {
            bool retVal = false;
            try
            {
                var windowArray = _windowSessionsQueue.ToArray();
                var window = windowArray.FirstOrDefault(w => w.BrowserContextId == browserContextId);
                if (window == null)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Window with browserContextId [{browserContextId}] not found", this, GPALObjectType.PuppeteerCommunicator);
                }
                else
                {
                    // iterate thru all open tabs, close them which will close the window, also cleanup our internal housekeeping
                    var tabArray = window.TabQueue.ToArray();
                    foreach (var tab in tabArray)
                    {
                        await SendCommand<object>(DevToolsMethods.TargetCloseTarget, new { targetId = tab.Key }, null).ConfigureAwait(false);
                        RemoveTabFromQueue(tab.Key);
                    }
 
                    if (RemoveWindowFromQueue(browserContextId))
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Closed window with browserContextId [{browserContextId}]", this, GPALObjectType.PuppeteerCommunicator);
                        retVal = true;
                    }
                    else
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Failed to remove window with browserContextId [{browserContextId}]", this, GPALObjectType.PuppeteerCommunicator);
                    }
                }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Failed to close window with browserContextId [{browserContextId}]", this, GPALObjectType.PuppeteerCommunicator, ex);
            }
 
            CheckForLastBrowserWindowOpen("CloseWindow()");
            return retVal;
        }
 
        // Implementation for "delete-storage"
        /// <param name="storageType">Storage type</param>
        /// <param name="sessionId">CDP session id</param>
        /// <param name="domain">Domain/origin; null acts as wildcard</param>
        /// <param name="storeName">Optional object store (IndexedDB)</param>
        /// <param name="path">Optional path (cookies)</param>
        /// <param name="key">Optional key; null acts as wildcard</param>
        /// <returns>Number of items successfully deleted</returns>
        public async Task<bool> DeleteStorage(
            string storageType,
            string sessionId,
            string domain = null,
            string storeName = null,
            string path = null,
            string key = null)
        {
            sessionId ??= GetEffectiveSessionId();
            int deletedCount = 0;
            bool retVal = false;
 
            bool IsMissing(string s) => string.IsNullOrEmpty(s);
 
            try
            {
                string origin = false == string.IsNullOrEmpty(domain) ? UrlHelper.GetOrigin(domain) : UrlHelper.GetOrigin(BrowserHelper.GetCurrentUrl(Browser.BrowserSettings));
 
                if (IsMissing(domain))
                    GPAL.PublishSimpleEvent(GPALEventType.INFO, $"DOMAIN IS MISSING. Deleting all [{storageType}] for origin [{origin}].", this, GPALObjectType.PuppeteerCommunicator);
 
                switch (storageType)
                {
                    case "cookie":
                        {
                            var cookiesJson = await GetStorage("cookie", sessionId, domain, storeName, path, key).ConfigureAwait(false);
                            var cookies = JsonConvert.DeserializeObject<List<dynamic>>(cookiesJson) ?? new List<dynamic>();
                            foreach (dynamic c in cookies)
                            {
                                var delParams = new Dictionary<string, object>
                                {
                                    { "name", (string)c.Key },
                                    { "domain", (string)c.Domain },
                                    //{ "url", $"https://{(string)c.Domain.ToString().TrimStart('.')}{(string)c.Path}" },
                                    { "path", (string)c.Path },
                                };
 
                                // build the partitionKey object exactly as it appears in the cookie. a cookie
                                // that has no partition answers with a json null, which is an object and not a
                                // c# null, so asking that for topLevelSite threw after the delete had gone out
                                JToken cookiePartition = ((JObject)c)["PartitionKey"];
 
                                if (null != cookiePartition && JTokenType.Object == cookiePartition.Type)
                                {
                                    var pk = new Dictionary<string, object>
                                    {
                                        { "topLevelSite", (string)cookiePartition["topLevelSite"] },
                                        { "hasCrossSiteAncestor", (bool?)cookiePartition["hasCrossSiteAncestor"] }
                                    };
 
                                    delParams.Add("partitionKey", pk);
                                }
                                // deleteCookies answers with the reply object rather than a flag, and assigning
                                // that to a bool threw once the cookie had already gone, so the loop stopped on
                                // the first one and nothing counted it
                                dynamic deleteReply = await SendCommand(DevToolsMethods.NetworkDeleteCookies, delParams, sessionId).ConfigureAwait(false);
 
                                retVal = null != deleteReply;
 
                                if (true == retVal)
                                    deletedCount++;
                            }
                            break;
                        }
                    case "localStorage":
                    case "sessionStorage":
                        {
                            if (IsMissing(domain))
                            {
                                string js = $@"(function() {{
                                            try {{
                                                {storageType}.clear();
                                                return true;
                                            }} catch (e) {{
                                                return false;
                                            }}
                                        }})();";
 
                                retVal = SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                                {
                                    expression = js,
                                    awaitPromise = false,
                                    contextId = CurrentContextId,
                                    returnByValue = true
                                }, sessionId).ConfigureAwait(false).GetAwaiter().GetResult()?.ToString().Contains("true");
 
                                if (true == retVal)
                                    deletedCount++;
 
                                break;
                            }
 
                            if (IsMissing(key))
                            {
                                var keysJson = await GetStorage(storageType, sessionId, domain).ConfigureAwait(false);
 
                                // the read answers the whole store as a key/value object, and taking that as a
                                // list of names threw before a single item was removed
                                List<string> keys = new List<string>();
 
                                if (false == string.IsNullOrWhiteSpace(keysJson))
                                {
                                    JToken storeRead = JToken.Parse(keysJson);
 
                                    if (JTokenType.Object == storeRead.Type)
                                        keys = ((JObject)storeRead).Properties().Select(each => each.Name).ToList();
                                    else if (JTokenType.Array == storeRead.Type)
                                        keys = storeRead.Select(each => each.ToString()).ToList();
                                }
                                foreach (var k in keys)
                                {
                                    retVal = SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                                    {
                                        expression = $"{storageType}.removeItem('{EscapeJsString(k)}');",
                                        awaitPromise = false,
                                        contextId = CurrentContextId,
                                        returnByValue = true
                                    }, sessionId).ConfigureAwait(false).GetAwaiter().GetResult()?.ToString().Contains("true");
                                    if (true == retVal)
                                        deletedCount++;
                                }
                            }
                            else
                            {
                                retVal = SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                                {
                                    expression = $"{storageType}.removeItem('{EscapeJsString(key)}');",
                                    awaitPromise = false,
                                    contextId = CurrentContextId,
                                    returnByValue = true
                                }, sessionId).ConfigureAwait(false).GetAwaiter().GetResult()?.ToString().Contains("true");
                                if (true == retVal)
                                    deletedCount++;
                            }
                            break;
                        }
                    case "indexedDb":
                        {
                            if (IsMissing(domain))
                            {
                                retVal = SendCommand<dynamic>(DevToolsMethods.StorageClearDataForOrigin, new
                                {
                                    origin = origin,
                                    storageTypes = "indexeddb"
                                }, sessionId).GetAwaiter().GetResult() != null;
 
                                if (retVal)
                                    deletedCount++;
 
                                break;
                            }
 
                            if (IsMissing(storeName))
                            {
                                // enumerate all DBs and delete
                                var dbsJson = await GetStorage("indexeddb", sessionId, domain).ConfigureAwait(false);
                                var dbs = JsonConvert.DeserializeObject<List<string>>(dbsJson) ?? new List<string>();
                                foreach (var db in dbs)
                                {
                                    string js = $@"(function(){{ indexedDB.deleteDatabase('{EscapeJsString(db)}'); }})();";
                                    retVal = SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, 
                                        new { 
                                            expression = js, 
                                            awaitPromise = true,
                                            contextId = CurrentContextId,
                                            returnByValue = true 
                                        }, sessionId).GetAwaiter().GetResult()?.ToString().Contains("true");
                                    if (true == retVal)
                                        deletedCount++;
                                }
                            }
                            else if (IsMissing(key))
                            {
                                string js = $@"(function(){{ indexedDB.deleteDatabase('{EscapeJsString(storeName)}'); }})();";
                                retVal = SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, 
                                    new { 
                                        expression = js, 
                                        awaitPromise = true,
                                        contextId = CurrentContextId,
                                        returnByValue = true 
                                    }, sessionId).GetAwaiter().GetResult()?.ToString().Contains("true");
                                if (true == retVal)
                                    deletedCount++;
                            }
                            else
                            {
                                string js = $@"(function() {{
                                                return new Promise((resolve, reject) => {{
                                                    const dbName     = '{EscapeJsString(path)}';      // path = dbName (per your note)
                                                    const store      = '{EscapeJsString(storeName)}'; // storeName = store (per your note)
                                                    const recordKey  = '{EscapeJsString(key)}';
 
                                                    const openReq = indexedDB.open(dbName);
 
                                                    openReq.onerror = () => reject(openReq.error);
 
                                                    openReq.onsuccess = () => {{
                                                        const db = openReq.result;
 
                                                        const tx = db.transaction(store, 'readwrite');
                                                        const objectStore = tx.objectStore(store);
 
                                                        objectStore.delete(recordKey);
 
                                                        tx.oncomplete = () => {{
                                                            db.close();
                                                            resolve(true);   // so your .Contains(""true"") check still works
                                                        }};
 
                                                        tx.onerror = () => {{
                                                            db.close();
                                                            reject(tx.error);
                                                        }};
                                                    }};
                                                }});
                                            }})();
                                        ";
 
                                retVal = SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate,
                                    new
                                    {
                                        expression = js,
                                        awaitPromise = true,
                                        contextId = CurrentContextId,
                                        returnByValue = true
                                    }, sessionId).GetAwaiter().GetResult()?.ToString().Contains("true");
 
                                if (retVal)
                                    deletedCount++;
                            }
                            break;
                        }
 
                    case "cache":
                        {
                            if (IsMissing(domain))
                            {
                                string js = @"(async function() {
                                                try {
                                                    const keys = await caches.keys();
                                                    await Promise.all(keys.map(k => caches.delete(k)));
                                                    return true;
                                                } catch (e) {
                                                    return false;
                                                }
                                            })();";
 
                                retVal = SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                                {
                                    expression = js,
                                    awaitPromise = true,
                                    contextId = CurrentContextId,
                                    returnByValue = true
                                }, sessionId).GetAwaiter().GetResult()?.ToString().Contains("true");
 
                                if (true == retVal)
                                    deletedCount++;
 
                                break;
                            }
 
                            if (IsMissing(key))
                            {
                                // the store name names the cache, the same as the read does. without one the read
                                // answers the cache names and each whole cache goes; with one it answers the keys
                                // held in that cache and they go one at a time
                                var cachesJson = await GetStorage("cache", sessionId, domain, storeName).ConfigureAwait(false);
                                var cacheEntries = JsonConvert.DeserializeObject<List<string>>(cachesJson) ?? new List<string>();
 
                                foreach (var each in cacheEntries)
                                {
                                    string cacheDelete = IsMissing(storeName)
                                        ? $"caches.delete('{EscapeJsString(each)}');"
                                        : $"caches.open('{EscapeJsString(storeName)}').then(cache => cache.delete('{EscapeJsString(each)}',{{ignoreVary: true}}));";
 
                                    retVal = SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, 
                                        new { 
                                            expression = cacheDelete, 
                                            awaitPromise = true,
                                            contextId = CurrentContextId,
                                            returnByValue = true 
                                        }, sessionId).GetAwaiter().GetResult()?.ToString().Contains("true");
                                    if (true == retVal)
                                        deletedCount++;
                                }
                            }
                            else
                            {
                                retVal = SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, 
                                    new { 
                                        expression = $"caches.open('{EscapeJsString(storeName)}').then(cache => cache.delete('{EscapeJsString(key)}', {{ignoreVary: true}}));", 
                                        awaitPromise = true,
                                        contextId = CurrentContextId,
                                        returnByValue = true 
                                    }, sessionId).GetAwaiter().GetResult()?.ToString().Contains("true");
                                if (true == retVal)
                                    deletedCount++;
                            }
                            break;
                        }
 
                    default:
                        GPAL.PublishSimpleEvent(
                            GPALEventType.ERROR,
                            $"Unsupported storage type: [{storageType}]",
                            this,
                            GPALObjectType.PuppeteerCommunicator);
                        break;
                }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(
                    GPALEventType.EXCEPTION,
                    $"Failed for [{storageType}] d[{domain}] sn[{storeName}] p[{path}] k[{key}]",
                    this,
                    GPALObjectType.PuppeteerCommunicator,
                    ex);
            }
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Deleted [{deletedCount}] [{storageType}](s)", this, GPALObjectType.PuppeteerCommunicator);
 
            return 0 < deletedCount;
        }
        // Small helper to prevent JS injection / quoting issues
        /// <returns>The escaped string, or an empty string if <paramref name="value"/> is null or empty.</returns>
        private static string EscapeJsString(string value)
        {
            if (string.IsNullOrEmpty(value)) return "";
            return value.Replace("\\", "\\\\")
                        .Replace("'", "\\'")
                        .Replace("\r", "\\r")
                        .Replace("\n", "\\n");
        }
 
        // Implementation for "evaluate"
        public async Task<dynamic> Evaluate(string xpath, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            return await SendCommand<object>(DevToolsMethods.RuntimeEvaluate,
                new {
                    contextId = CurrentContextId,
                    expression = $"document.evaluate('{xpath}', document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue"
                }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "evaluate-all"
        public async Task<dynamic> EvaluateAll(string xpath, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            return await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new {
                    contextId = CurrentContextId,
                    expression = $"Array.from(document.evaluate('{xpath}', document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null))" 
                }, sessionId).ConfigureAwait(false);
        }

        private string GetKeyCode(char c)
        {
            char upper = char.ToUpperInvariant(c);
 
            if (upper >= 'A' && upper <= 'Z')
            {
                return "Key" + upper;
            }
 
            if (char.IsDigit(c))
            {
                return "Digit" + c;
            }
 
            switch (c)
            {
                case '`':
                case '~':
                    return "Backquote";
 
                case '-':
                case '_':
                    return "Minus";
 
                case '=':
                case '+':
                    return "Equal";
 
                case '[':
                case '{':
                    return "BracketLeft";
 
                case ']':
                case '}':
                    return "BracketRight";
 
                case '\\':
                case '|':
                    return "Backslash";
 
                case ';':
                case ':':
                    return "Semicolon";
 
                case '\'':
                case '"':
                    return "Quote";
 
                case ',':
                case '<':
                    return "Comma";
 
                case '.':
                case '>':
                    return "Period";
 
                case '/':
                case '?':
                    return "Slash";
 
                case ' ':
                    return "Space";
 
                case '\t':
                    return "Tab";
 
                case '\r':
                case '\n':
                    return "Enter";
 
                // Add more special keys here as needed, e.g.:
                // case '\b': return "Backspace";
                // case '\x1B': return "Escape";
 
                default:
                    return c.ToString();  // fallback
            }
        }
 
        // Implementation for "fillin" helper
        public async Task<dynamic> FillIn(string objectId, string text, int delayMs = 0, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            // Input.insertText (faster bulk insert)
            bool success = await TryInsertText(objectId, text, sessionId).ConfigureAwait(false);
            if (success) return true;
 
            // JS direct set + synthetic events
            success = await TryJsDirectFill(objectId, text, sessionId).ConfigureAwait(false);
            if (success) return true;
 
            // Step 1: Ensure focused
            await FocusElement(objectId, sessionId).ConfigureAwait(false);
 
            // Per-char key events (most reliable for validation)
            success = await TryTypeWithKeyEvents(objectId, text, delayMs, sessionId).ConfigureAwait(false);
            if (success) return true;
 
 
            // All failed — log or throw
            GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Failed to fill element [{objectId}] with [{text}] using all methods.");
            return false;
 
        }

        private async Task<bool> TryTypeWithKeyEvents(string objectId, string text, int delayMs, string sessionId)
        {
            try
            {
                await DispatchTextCharByChar(text, 0 < delayMs ? delayMs : 50, sessionId).ConfigureAwait(false);
 
                // After typing, verify
                string actualValue = await GetElementValue(objectId, sessionId).ConfigureAwait(false);
                if (actualValue == text)
                {
                    // Final blur to trigger any validation/button enable
                    await BlurElement(objectId, sessionId).ConfigureAwait(false);
                    return true;
                }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Failed to type text, trying next method.", this, GPALObjectType.PuppeteerCommunicator, ex);
            }
            return false;
        }

        private async Task<bool> TryInsertText(string objectId, string text, string sessionId)
        {
            try
            {
                // Bulk insert
                await SendCommand(DevToolsMethods.InputInsertText, new { text }, sessionId).ConfigureAwait(false);
 
                // Verify
                string actualValue = await GetElementValue(objectId, sessionId).ConfigureAwait(false);
                if (actualValue == text)
                {
                    await BlurElement(objectId, sessionId).ConfigureAwait(false);
                    return true;
                }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Failed to type text, trying next method.", this, GPALObjectType.PuppeteerCommunicator, ex);
            }
            return false;
        }

        private async Task<bool> TryJsDirectFill(string objectId, string text, string sessionId)
        {
            try
            {
                // Your original/enhanced JS function (set .value + dispatch events)
                var js = @"
                        function(value) {
                            this.value = value;
 
                            // Trigger everything frameworks listen to
                            const desc = Object.getOwnPropertyDescriptor(this, 'value') || 
                                          Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value') ||
                                          Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value');
 
                            // Bypass any framework value setters that block direct assignment
                            if (desc && desc.set) {
                                desc.set.call(this, value);
                            }
 
                            this.dispatchEvent(new Event('input', { bubbles: true }));
                            this.dispatchEvent(new Event('change', { bubbles: true }));
                        }";
 
                await SendCommand(DevToolsMethods.RuntimeCallFunctionOn, new
                {
                    objectId,
                    functionDeclaration = js,
                    arguments = new[] { new { value = text } },
                    contextId = CurrentContextId,
                    awaitPromise = true
                }, sessionId).ConfigureAwait(false);
 
                // Verify
                string actualValue = await GetElementValue(objectId, sessionId).ConfigureAwait(false);
                if (actualValue == text)
                {
                    await BlurElement(objectId, sessionId).ConfigureAwait(false);
                    return true;
                }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Failed to type text, trying next method.", this, GPALObjectType.PuppeteerCommunicator, ex);
            }
            return false;
        }
 
        // Helper: Get current value via JS evaluate
        private async Task<string> GetElementValue(string objectId, string sessionId)
        {
            var result = await SendCommand<dynamic>(DevToolsMethods.RuntimeCallFunctionOn, new
            {
                objectId,
                functionDeclaration = "function() { return this.value; }",
                contextId = CurrentContextId,
                returnByValue = true
            }, sessionId).ConfigureAwait(false);
 
            // Parse the returned value (assuming it's a string)
            return result?.result?.value?.ToString() ?? string.Empty;
        }
 
        // Helper: Focus
        internal async Task FocusElement(string objectId, string sessionId)
        {
            await SendCommand(DevToolsMethods.RuntimeCallFunctionOn, new
            {
                objectId,
                contextId = CurrentContextId,
                functionDeclaration = "function() { this.focus(); }"
            }, sessionId).ConfigureAwait(false);
        }
 
        // Helper: Blur
        private async Task BlurElement(string objectId, string sessionId)
        {
            await SendCommand(DevToolsMethods.RuntimeCallFunctionOn, new
            {
                objectId,
                contextId = CurrentContextId,
                functionDeclaration = "function() { this.blur(); }"
            }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "fill-in-append"

        public async Task FillInAppend(string objectId, string text, int delayMs = 0, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            var currentResp = await SendCommand<object>(DevToolsMethods.RuntimeCallFunctionOn, new
            {
                objectId,
                functionDeclaration = "function() { return this.value || ''; }",
                contextId = CurrentContextId,
                returnByValue = true
            }, sessionId).ConfigureAwait(false);
 
            string current = currentResp?.result?.value?.ToString() ?? "";
            await FillIn(objectId, current + text, delayMs, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "fill-in-insert"
        /// <code>
        /// await communicator.FillInInsert(inputObjectId, "prefix-");
        /// </code>
        /// </example>
        public async Task FillInInsert(string objectId, string text, int delayMs = 0, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            var currentResp = await SendCommand<object>(DevToolsMethods.RuntimeCallFunctionOn, new
            {
                objectId,
                functionDeclaration = "function() { return this.value || ''; }",
                contextId = CurrentContextId,
                returnByValue = true
            }, sessionId).ConfigureAwait(false);
 
            string current = currentResp?.result?.value?.ToString() ?? "";
            await FillIn(objectId, text + current, delayMs, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "fill-in-overwrite"

        /// </code>
        /// </example>
        public async Task FillInOverwrite(string objectId, string text, int delayMs = 0, string sessionId = null)
        {
            await FillIn(objectId, text, delayMs, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "fire-change-event"
        public async Task<dynamic> FireChangeEvent(string objectId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            return await SendCommand<object>(DevToolsMethods.RuntimeCallFunctionOn, new
            {
                objectId,
                contextId = CurrentContextId,
                functionDeclaration = "function() {{ this.dispatchEvent(new Event('change')); }}"
            }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "focus"
        public async Task Focus(int backendNodeId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var nodeId = await GetNodeIdFromBackendNodeId(backendNodeId, sessionId).ConfigureAwait(false);
            await SendCommand<object>(DevToolsMethods.DOMFocus, new { nodeId }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "forward"
        public async Task<dynamic> Forward(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            dynamic history = await SendCommand<object>(DevToolsMethods.PageGetNavigationHistory, new { }, sessionId).ConfigureAwait(false);
            if (history?.currentIndex != null)
            {
                var entries = (IEnumerable<dynamic>)history.entries;
                var nextEntry = entries.ElementAtOrDefault((int)history.currentIndex + 1);
                if (nextEntry?.id != null)
                {
                    var result = await SendCommand(DevToolsMethods.PageNavigateToHistoryEntry, new { entryId = (int)nextEntry.id }, sessionId).ConfigureAwait(false);
                    return result;
                }
            }
            GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No next page in history", this, GPALObjectType.PuppeteerClient);
            return null;
        }
 
        // Implementation for "fullscreen"
        public async Task<bool> FullScreen(string sessionId = null)
        {
            if (true == Browser.BrowserSettings.UseHeadless)
                return await Maximize().ConfigureAwait(false);
            else
            {
                sessionId ??= GetEffectiveSessionId();
 
                var windowId = await GetCurrentWindow(sessionId).ConfigureAwait(false);
 
                await SendCommand(DevToolsMethods.BrowserSetWindowBounds, new
                {
                    windowId,
                    bounds = new { windowState = "fullscreen" }  // - this is the CDP way for browser fullscreen
                }, sessionId).ConfigureAwait(false);
            }
 
            return true;
        }
 
        // Implementation for "get-attribute"
        public async Task<dynamic> GetAttribute(int backendNodeId, string attribute, string sessionId = null)
        {
            var nodeId = await GetNodeIdFromBackendNodeId(backendNodeId, sessionId).ConfigureAwait(false);
            sessionId ??= GetEffectiveSessionId();
            return await SendCommand<object>(DevToolsMethods.DOMGetAttributes, new { nodeId, name = attribute }, sessionId).ConfigureAwait(false);
        }
 
 
        // Implementation for "get-bounding-client-rect"
        public async Task<Rectangle> GetBoundingClientRect(int backendNodeId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            // If we are inside an iframe (via InFrame()), prefer the iframe's context/session
            bool isInFrame = CurrentContextId.HasValue;
            string effectiveSessionId = isInFrame && !string.IsNullOrEmpty(CurrentFrameSessionId)
                ? CurrentFrameSessionId
                : sessionId;
 
            // getBoundingClientRect answers against the document holding the element, which is what the screen
            // calculation expects since it adds the iframe position itself.
            // Taken whenever there is an execution context, not only when the frame has its own session: a
            // same-origin iframe never gets one, and the box model below answers in main-frame coordinates that
            // already include the iframe offset
            if (CurrentContextId.HasValue)
            {
                try
                {
                    // 1. Convert backendNodeId to a JavaScript RemoteObject in the frame context
                    var resolveResult = await SendCommand<dynamic>(DevToolsMethods.DOMResolveNode, new
                    {
                        backendNodeId = backendNodeId,
                        executionContextId = CurrentContextId.Value
                    }, effectiveSessionId).ConfigureAwait(false);
 
                    string objectId = resolveResult?.@object?.objectId;
 
                    if (!string.IsNullOrEmpty(objectId))
                    {
                        // 2. Call getBoundingClientRect directly on that object
                        var rectResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeCallFunctionOn, new
                        {
                            objectId = objectId,
                            functionDeclaration = "function() { const r = this.getBoundingClientRect(); return {x: r.left, y: r.top, width: r.width, height: r.height}; }",
                            contextId = CurrentContextId,
                            returnByValue = true
                        }, effectiveSessionId).ConfigureAwait(false);
 
                        if (rectResult?.result?.value != null)
                        {
                            var r = rectResult.result.value;
                            if (0 < (int)r.width && 0 < (int)r.height)
                                // relative to the viewport of the document the element sits in
                                return new Rectangle((int)r.x, (int)r.y, (int)r.width, (int)r.height);
                        }
                    }
                }
                catch { }
            }
 
            // === main page or fallback ===
            Point pageOffset = Point.Empty;
 
            try
            {
                pageOffset = new Point(await WindowPageOffsetX(effectiveSessionId).ConfigureAwait(false),
                                       await WindowPageOffsetY(effectiveSessionId).ConfigureAwait(false));
            }
            catch (Exception)
            {
                // a scroll that cannot be read is taken as none, which leaves the rect where the box model
                // put it rather than losing it
            }
 
            try
            {
                var nodeId = await GetNodeIdFromBackendNodeId(backendNodeId, effectiveSessionId).ConfigureAwait(false);
                dynamic box = await SendCommand<dynamic>(DevToolsMethods.DOMGetBoxModel, new { nodeId }, effectiveSessionId).ConfigureAwait(false);
 
                BoxModelResponse boxModel = ((JObject)box)?.ToObject<BoxModelResponse>();
 
                if (boxModel?.Model != null)
                {
                    // DOM.getBoxModel answers in document coordinates. this method is named for
                    // getBoundingClientRect and the branch above it answers in viewport coordinates, so the
                    // scroll of the same session comes off and both paths mean the same thing.
                    // read outside the rect, because a scroll this cannot get is a rect adjusted by zero
                    // rather than a rect nobody gets
                    return new Rectangle(
                        (int)boxModel.Model.Content[0] - pageOffset.X,
                        (int)boxModel.Model.Content[1] - pageOffset.Y,
                        (int)boxModel.Model.Width,
                        (int)boxModel.Model.Height
                    );
                }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG,
                    $"DOM.getBoxModel failed",
                    this, GPALObjectType.PuppeteerCommunicator, ex);
            }
 
            return new Rectangle(-1, -1, -1, -1);
        }
 
        // Implementation for "get-content-and-css"
        public async Task<dynamic> GetContentAndCss(string elementId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            return await SendCommand<object>(DevToolsMethods.RuntimeEvaluate,
                new {
                    expression = $"let el = document.getElementById('{elementId}'); JSON.stringify({{content: el.innerHTML, css: getComputedStyle(el)}})",
                    contextId = CurrentContextId,
                    returnByValue = false
                }, sessionId).ConfigureAwait(false);
        }
        public async Task<Dictionary<string, object>> GetCssAttributes(int backendNodeId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            try
            {
                var nodeId = await GetNodeIdFromBackendNodeId(backendNodeId, sessionId).ConfigureAwait(false);
 
                await SendCommand<object>(DevToolsMethods.DOMEnable, new { }, sessionId).ConfigureAwait(false);
                await SendCommand<object>(DevToolsMethods.CSSEnable, new { }, sessionId).ConfigureAwait(false);
 
                var result = await SendCommand<dynamic>(DevToolsMethods.CSSGetComputedStyleForNode, new { nodeId }, sessionId).ConfigureAwait(false);
 
                if (result?.computedStyle == null)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"CSS.getComputedStyleForNode returned null for nodeId [{nodeId}]", this, GPALObjectType.PuppeteerCommunicator);
                    return null;
                }
 
                var relevantProps = new HashSet<string>(new[]
                {
                    "display","visibility","opacity","pointer-events","overflow","clip-path",
                    "position","top","left","right","bottom","z-index",
                    "width","height","min-width","min-height","max-width","max-height",
                    "margin","margin-top","margin-right","margin-bottom","margin-left",
                    "padding","padding-top","padding-right","padding-bottom","padding-left",
                    "border","border-width","border-style","border-color","box-sizing",
                    "flex","flex-direction","flex-wrap","flex-grow","flex-shrink","flex-basis",
                    "justify-content","align-items","align-self","order",
                    "grid","grid-template","grid-area","grid-column","grid-row",
                    "transform","transform-origin","transition","animation",
                    "cursor","user-select","content","filter"
                });
 
                var emptyValues = new HashSet<string> { "", "none", "normal", "inherit", "initial", "unset", "auto", "0px", "0", "transparent" };
 
                var computedStyles = new Dictionary<string, object>();
                foreach (var style in result.computedStyle)
                {
                    string name = style.name?.ToString();
                    string value = style.value?.ToString()?.Trim();
 
                    if (name != null && relevantProps.Contains(name) && !string.IsNullOrEmpty(value) && !emptyValues.Contains(value))
                    {
                        computedStyles[name] = value;
                    }
                }
 
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Retrieved [{computedStyles.Count}] filtered CSS attributes for nodeId [{nodeId}]", this, GPALObjectType.PuppeteerCommunicator);
                return computedStyles;
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Failed to get CSS attributes", this, GPALObjectType.PuppeteerCommunicator, ex);
                return null;
            }
            finally
            {
                await SendCommand<object>(DevToolsMethods.CSSDisable, new { }, sessionId).ConfigureAwait(false);
                await SendCommand<object>(DevToolsMethods.DOMDisable, new { }, sessionId).ConfigureAwait(false);
            }
        }
        //public async Task<Dictionary<string, object>> GetCssAttributes(int backendNodeId, string sessionId = null)
        //{
        //    sessionId ??= GetEffectiveSessionId();
 
        //    try
        //    {
        //        var nodeId = await GetNodeIdFromBackendNodeId(backendNodeId, sessionId);
 
        //        await SendCommand<object>(DevToolsMethods.DOMEnable, new { }, sessionId);
        //        await SendCommand<object>(DevToolsMethods.CSSEnable, new { }, sessionId);   // NOTE: this command generates a lot of 'unhandled' receivemessage messages of elements added - this must be done tho
 
        //        // Send CSS.getComputedStyleForNode
        //        var result = await SendCommand<dynamic>(DevToolsMethods.CSSGetComputedStyleForNode, new
        //        {
        //            nodeId
        //        }, sessionId);
 
 
        //        if (result?.computedStyle == null)
        //        {
        //            GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"CSS.getComputedStyleForNode returned null for nodeId [{nodeId}]", this, GPALObjectType.PuppeteerCommunicator);
        //            return null;
        //        }
 
        //        // Process computedStyle array
        //        var computedStyles = new Dictionary<string, object>();
        //        foreach (var style in result.computedStyle)
        //            computedStyles[style.name?.ToString()] = style.value?.ToString();
 
        //        GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Retrieved {computedStyles.Count} CSS attributes for nodeId [{nodeId}]", this, GPALObjectType.PuppeteerCommunicator);
        //        return computedStyles;
        //    }
        //    catch (Exception ex)
        //    {
        //        GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Failed to get CSS attributes for backendNodeId [{backendNodeId}]: {ex.Message}", this, GPALObjectType.PuppeteerCommunicator, ex);
        //        return null;
        //    }
        //    finally
        //    {
        //        await SendCommand<object>(DevToolsMethods.CSSDisable, new { }, sessionId);
        //        await SendCommand<object>(DevToolsMethods.DOMDisable, new { }, sessionId);
        //    }
        //}
        // this appears to be identical to the attributes we get from evaluateselector javascript
        /// <param name="sessionId">CDP session id; the effective session is used if null.</param>
        /// <returns>Task that resolves to a dictionary of attribute names and values, or null on failure.</returns>
        public async Task<Dictionary<string, object>> GetDomAttributes(int backendNodeId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            try
            {
                // Send DOM.getAttributes
                var nodeId = await GetNodeIdFromBackendNodeId(backendNodeId, sessionId).ConfigureAwait(false);
                var result = await SendCommand<object>(DevToolsMethods.DOMGetAttributes, new
                {
                    nodeId
                }, sessionId).ConfigureAwait(false);
 
                if (result?.attributes == null)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"DOM.getAttributes returned null for nodeId [{nodeId}]", this, GPALObjectType.PuppeteerCommunicator);
                    return null;
                }
 
                // Process attributes array (alternating name/value pairs)
                var attributes = new Dictionary<string, object>();
                for (int i = 0; i < result.attributes.Count - 1; i += 2)
                {
                    attributes[result.attributes[i]?.ToString()] = result.attributes[i + 1]?.ToString();
                }
 
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Retrieved [{attributes.Count}] DOM attributes for nodeId [{nodeId}]", this, GPALObjectType.PuppeteerCommunicator);
                return attributes;
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Failed to get DOM attributes for nodeId [{backendNodeId}]", this, GPALObjectType.PuppeteerCommunicator, ex);
                return null;
            }
        }
        public async Task<Dictionary<string, object>> GetDomProperties(int backendNodeId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            try
            {
                // Resolve the node to a JS object so we can run the same curated script the template
                // (ElementHelper.GetDomProperties) and OttoMagic use - not an attribute/property dump.
                var resolve = await SendCommand<dynamic>(DevToolsMethods.DOMResolveNode, new { backendNodeId, pierce = true }, sessionId).ConfigureAwait(false);
                string objectId = resolve.@object.objectId;
 
                // Same key set and truthiness guards as ElementHelper.GetDomProperties
                var jsProps = await SendCommand<dynamic>(DevToolsMethods.RuntimeCallFunctionOn, new
                {
                    objectId,
                    functionDeclaration = @"
                            function() {
                                const props = {};
                                if ('textContent' in this) props.textContent = this.textContent;
                                if ('innerHTML' in this) props.innerHTML = this.innerHTML;
                                if ('innerText' in this) props.innerText = this.innerText;
                                if ('outerHTML' in this) props.outerHTML = this.outerHTML;
                                if ('className' in this) props.className = this.className;
                                if ('disabled' in this) props.disabled = this.disabled;
                                return props;
                            }",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
 
                // Release objectId to prevent leak
                await SendCommand<dynamic>(DevToolsMethods.RuntimeReleaseObject,
                    new {
                        contextId = CurrentContextId,
                        objectId
                    }, sessionId).ConfigureAwait(false);
 
                var properties = new Dictionary<string, object>();
                if (jsProps?.result?.value != null)
                    properties = ((Newtonsoft.Json.Linq.JObject)jsProps.result.value).ToObject<Dictionary<string, object>>();
 
                // Normalize null -> "" (consistent with ElementHelper.GetDomProperties)
                properties = properties.ToDictionary(kvp => kvp.Key, kvp => kvp.Value ?? "");
 
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Retrieved [{properties.Count}] DOM properties for backendNodeId [{backendNodeId}]", this, GPALObjectType.PuppeteerCommunicator);
                return properties;
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Failed to get DOM properties for backendNodeId [{backendNodeId}]", this, GPALObjectType.PuppeteerCommunicator, ex);
                return null;
            }
        }
        // pure javascript, message is too large from browser and cdp / websocket hangs
        /*
        public async Task<dynamic> GetCssAttributes(string selector, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            if (string.IsNullOrEmpty(selector))
            {
                return new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
            }
 
            var jsExpression = $@"
                                (function() {{
                                    try {{
                                        console.log('get css attrs');
                                        // Helper to find the first matching element in a context
                                        function findFirstElement(sel, context = document) {{
                                            // Try CSS selector
                                            try {{
                                        console.log('css');
                                                const element = context.querySelector(sel);
                                                if (element) {{
                                        console.log('found css');
                                                    return element;
                                                }}
                                            }} catch (e) {{
                                        console.log('error ' + e);
                                            }}
 
                                            // Try XPath
                                            try {{
                                        console.log('xpath');
                                                const result = document.evaluate(sel, context, null, 9, null);
                                                if (result.singleNodeValue) {{
                                        console.log('found xpath');
                                                    return result.singleNodeValue;
                                                }}
                                            }} catch (e) {{
                                        console.log('error ' + e);
                                            }}
 
                                            return null;
                                        }}
 
                                        console.log('find first');
                                        // Search in main document
                                        let element = findFirstElement('{selector.Replace("'", "\\'").Replace("\\", "\\\\")}');
 
                                        // Search in shadow DOM if no element found
                                        if (!element) {{
                                        console.log('try shadowdom');
                                            const shadowHosts = document.querySelectorAll('*');
                                            var shadowCount = 0;
                                            for (const host of shadowHosts) {{
                                                if (host.shadowRoot) {{
                                        console.log('searching shadow root' + shadowCount++);
                                                    element = findFirstElement('{selector.Replace("'", "\\'").Replace("\\", "\\\\")}', host.shadowRoot);
                                                    if (element) break;
                                                }}
                                            }}
                                        }}
 
                                        // Search in iframes if no element found
                                        if (!element) {{
                                        console.log('try iframes');
                                            const iframes = document.querySelectorAll('iframe');
                                            var iframeCount = 0;
                                            for (const iframe of iframes) {{
                                                try {{
                                                    if (iframe.contentDocument) {{
                                        console.log('searching iframe' + iframeCount++);
                                                        element = findFirstElement('{selector.Replace("'", "\\'").Replace("\\", "\\\\")}', iframe.contentDocument);
                                                        if (element) break;
                                                    }}
                                                }} catch (e) {{
                                                    // Ignore iframe access errors (e.g., cross-origin)
                                                }}
                                            }}
                                        }}
 
                                        // If no element found, return empty object
                                        if (!element) {{
                                        console.log('no element found');
                                            return {{}};
                                        }}
 
                                        console.log('get computed style');
                                        // Get computed styles for the element
                                        const styles = window.getComputedStyle(element);
                                        const props = {{}};
                                        for (let i = 0; i < styles.length; i++) {{
                                            const prop = styles[i];
                                            const value = styles.getPropertyValue(prop);
                                            if (value && value !== 'none') {{
                                                props[prop] = value;
                                            }}
                                        }}
                                        console.log('return props ' + props);
                                        return props;
                                    }} catch (e) {{
                                        console.error('Error in GetCssAttributes:', e);
                                        return {{}};
                                    }}
                                }})()";
 
            var jsProps = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
            {
                expression = jsExpression,
                contextId = CurrentContextId,
                returnByValue = true
            }, sessionId);
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Got jsprops [{jsProps}]");
 
            return jsProps?.result?.value != null
                ? ((Newtonsoft.Json.Linq.JObject)jsProps.result.value).ToObject<Dictionary<string, object>>()
                : new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
        }
        public async Task<dynamic> GetDomAttributes(string selector, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            var jsExpression = $@"
                                (function() {{
                                    try {{
                                        console.log('get dom attrs');
                                        // Helper to find the first matching element in a context
                                        function findFirstElement(sel, context = document) {{
                                            // Try CSS selector
                                            try {{
                                                const element = context.querySelector(sel);
                                                if (element) return element;
                                            }} catch (e) {{
                                                // Invalid CSS selector; try XPath
                                            }}
 
                                            // Try XPath
                                            try {{
                                                const result = document.evaluate(sel, context, null, 9, null);
                                                if (result.singleNodeValue) return result.singleNodeValue;
                                            }} catch (e) {{
                                                // Invalid XPath; continue to shadow DOM/iframes
                                            }}
 
                                            return null;
                                        }}
 
                                        // Search in main document
                                        let element = findFirstElement('{selector.Replace("'", "\\'").Replace("\\", "\\\\")}');
 
                                        // Search in shadow DOM if no element found
                                        if (!element) {{
                                            const shadowHosts = document.querySelectorAll('*');
                                            for (const host of shadowHosts) {{
                                                if (host.shadowRoot) {{
                                                    element = findFirstElement('{selector.Replace("'", "\\'").Replace("\\", "\\\\")}', host.shadowRoot);
                                                    if (element) break;
                                                }}
                                            }}
                                        }}
 
                                        // Search in iframes if no element found
                                        if (!element) {{
                                            const iframes = document.querySelectorAll('iframe');
                                            for (const iframe of iframes) {{
                                                try {{
                                                    if (iframe.contentDocument) {{
                                                        element = findFirstElement('{selector.Replace("'", "\\'").Replace("\\", "\\\\")}', iframe.contentDocument);
                                                        if (element) break;
                                                    }}
                                                }} catch (e) {{
                                                    // Ignore iframe access errors (e.g., cross-origin)
                                                }}
                                            }}
                                        }}
 
                                        // If no element found, return empty object
                                        if (!element) return {{}};
 
                                        // Get DOM attributes for the element
                                        const attributes = element.attributes;
                                        const attrs = {{}};
                                        for (let i = 0; i < attributes.length; i++) {{
                                            const name = attributes[i].name;
                                            const value = attributes[i].value;
                                            if (name && value) {{
                                                attrs[name] = value;
                                            }}
                                        }}
                                        return attrs;
                                    }} catch (e) {{
                                        console.error('Error in GetDomAttributes:', e);
                                        return {{}};
                                    }}
                                }})()";
 
            var jsProps = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
            {
                expression = jsExpression,
                contextId = CurrentContextId,
                returnByValue = true
            }, sessionId);
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Got jsprops [{jsProps}]");
 
            return jsProps?.result?.value != null
                ? ((Newtonsoft.Json.Linq.JObject)jsProps.result.value).ToObject<Dictionary<string, object>>()
                : new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
        }
        public async Task<dynamic> GetDomProperties(string selector, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var jsExpression = $@"
                                (function() {{
                                    try {{
                                        //console.log('get dom props');
                                        // Helper to find the first matching element in a context
                                        function findFirstElement(sel, context = document) {{
                                            // Try CSS selector
                                            try {{
                                        //console.log('css');
                                                const element = context.querySelector(sel);
                                                if (element) {{
                                        //console.log('found css');
                                                    return element;
                                                }}
                                            }} catch (e) {{
                                        //console.log('error ' + e);
                                            }}
 
                                            // Try XPath
                                            try {{
                                        //console.log('xpath');
                                                const result = document.evaluate(sel, context, null, 9, null);
                                                if (result.singleNodeValue) {{
                                                    return result.singleNodeValue;
                                                }}
                                            }} catch (e) {{
                                        //console.log('error ' + e);
                                            }}
 
                                            return null;
                                        }}
 
                                        // Search in main document
                                        let element = findFirstElement('{selector.Replace("'", "\\'").Replace("\\", "\\\\")}');
 
                                        // Search in shadow DOM if no element found
                                        if (!element) {{
                                            const shadowHosts = document.querySelectorAll('*');
                                            let hostCount = 0;
                                            for (const host of shadowHosts) {{
                                        //console.log('searching shadow host ' + hostCount);
                                                hostCount++;
                                                if (host.shadowRoot) {{
                                                    element = findFirstElement('{selector.Replace("'", "\\'").Replace("\\", "\\\\")}', host.shadowRoot);
                                                    if (element) {{
                                                        break;
                                                    }}
                                                }}
                                            }}
                                        }}
 
                                        // Search in iframes if no element found
                                        if (!element) {{
                                            const iframes = document.querySelectorAll('iframe');
                                            let iframeCount = 0;
                                            for (const iframe of iframes) {{
                                                iframeCount++;
                                                try {{
                                                    if (iframe.contentDocument) {{
                                        //console.log('searching iframe ' + iframeCount);
                                                        element = findFirstElement('{selector.Replace("'", "\\'").Replace("\\", "\\\\")}', iframe.contentDocument);
                                                        if (element) {{
                                                            break;
                                                        }}
                                                    }}
                                                }} catch (e) {{
                                        //console.log('error ' + e);
                                                }}
                                            }}
                                        }}
 
                                        // If no element found, return empty object
                                        if (!element) {{
                                            return {{}};
                                        }}
 
                                        // Get DOM properties for the element
                                        //console.log('get dom props 2');
                                        const props = {{}};
                                        if (element.tagName) props.tagName = element.tagName;
                                        if (element.textContent) props.textContent = element.textContent;
                                        if (element.value != null && element.value !== '') props.value = element.value;
                                        if (element.innerHTML) props.innerHTML = element.innerHTML;
                                        if (element.outerHTML) props.outerHTML = element.outerHTML;
                                        if (element.className) props.className = element.className;
                                        if (element.id) props.id = element.id;
                                        //console.log('return props');
                                        return props;
                                    }} catch (e) {{
                                        return {{}};
                                    }}
                                }})()";
 
            var jsProps = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
            {
                expression = jsExpression,
                contextId = CurrentContextId,
                returnByValue = true
            }, sessionId);
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Got jsprops [{jsProps}]");
 
            return jsProps?.result?.value != null
                ? ((Newtonsoft.Json.Linq.JObject)jsProps.result.value).ToObject<Dictionary<string, object>>()
                : new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
        }
        */
 
        // Implementation for "get-current-url"

        /// string url = await communicator.GetCurrentUrl();
        /// </code>
        /// </example>
        public async Task<string> GetCurrentUrl(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            // Evaluate 'window.location.toString()' to get the current URL
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new { 
                    expression = "window.location.href",
                    contextId = CurrentContextId,
                    returnByValue = true 
                }, sessionId).ConfigureAwait(false);
 
            // Extract and log the URL
            return result?.result?.value;
        }
 
        // Implementation for "get-current-window"

        public async Task<int> GetCurrentWindow(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            var result = await SendCommand<dynamic>(
                DevToolsMethods.BrowserGetWindowForTarget,
                new { }, // no params needed
                sessionId
            ).ConfigureAwait(false);
 
            return (int)result.windowId;
        }


        public async Task<System.Drawing.Rectangle> GetWindowRectangle(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            int windowId = await GetCurrentWindow(sessionId).ConfigureAwait(false);
 
            dynamic result = await SendCommand<dynamic>(
                DevToolsMethods.BrowserGetWindowBounds,
                new { windowId },
                sessionId
            ).ConfigureAwait(false);
 
            dynamic bounds = result?.bounds;
 
            // A minimized window reports its restored bounds
            return new System.Drawing.Rectangle(
                (int)(bounds?.left ?? 0),
                (int)(bounds?.top ?? 0),
                (int)(bounds?.width ?? 0),
                (int)(bounds?.height ?? 0));
        }
 
        // Implementation for "get-element-attribute-hash"
        public async Task<dynamic> GetElementAttributeHash(string elementId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            return await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new
                {
                    expression = "JSON.stringify(document.getElementById('" + elementId + "').attributes)",
                    contextId = CurrentContextId,
                    returnByValue = false
                }, sessionId).ConfigureAwait(false);
        }

        public async Task<string> GetPageSource(string sessionId = null)
        {
            if (sessionId == null)
            {
                sessionId = GetEffectiveSessionId();
            }
 
            // ── 1. Get root document ─────────────────────────────────────────────
            var docResult = await SendCommand(
                DevToolsMethods.DOMGetDocument,
                new Dictionary<string, object> { { "depth", 0 } },
                sessionId).ConfigureAwait(false);
 
            if (docResult == null)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "DOM.getDocument returned null",
                    this, GPALObjectType.PuppeteerCommunicator);
                return string.Empty;
            }
 
            // Normalize to JObject
            JObject rootDoc = docResult as JObject;
            if (rootDoc == null)
            {
                try
                {
                    string jsonStr = Newtonsoft.Json.JsonConvert.SerializeObject(docResult);
                    rootDoc = JObject.Parse(jsonStr);
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING,
                        "Failed to convert DOM.getDocument response to JObject: [" + ex.Message + "]",
                        this, GPALObjectType.PuppeteerCommunicator);
                    return string.Empty;
                }
            }
 
            // Find root (direct or wrapped in "result")
            JToken rootToken = rootDoc["root"] ?? rootDoc["result"]?["root"];
 
            if (rootToken == null || rootToken.Type != JTokenType.Object)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING,
                    "No valid 'root' object found in DOM.getDocument response",
                    this, GPALObjectType.PuppeteerCommunicator);
                return string.Empty;
            }
 
            JObject root = (JObject)rootToken;
 
            if (!long.TryParse(root["nodeId"]?.ToString(), out long rootNodeId))
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "Invalid or missing nodeId in root",
                    this, GPALObjectType.PuppeteerCommunicator);
                return string.Empty;
            }
 
            // ── 2. Get outerHTML ─────────────────────────────────────────────────
            var htmlResult = await SendCommand(
                DevToolsMethods.DOMGetOuterHTML,
                new Dictionary<string, object> { { "nodeId", rootNodeId } },
                sessionId).ConfigureAwait(false);
 
            if (htmlResult == null)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "DOM.getOuterHTML returned null",
                    this, GPALObjectType.PuppeteerCommunicator);
                return string.Empty;
            }
 
            // Normalize htmlResult to JObject
            JObject htmlDoc = htmlResult as JObject;
            if (htmlDoc == null)
            {
                try
                {
                    string jsonStr = Newtonsoft.Json.JsonConvert.SerializeObject(htmlResult);
                    htmlDoc = JObject.Parse(jsonStr);
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING,
                        "Failed to convert DOM.getOuterHTML response to JObject: [" + ex.Message + "]",
                        this, GPALObjectType.PuppeteerCommunicator);
                    return string.Empty;
                }
            }
 
            // Extract the actual source string
            string fullSource = htmlDoc["outerHTML"]?.ToString();
 
            if (string.IsNullOrWhiteSpace(fullSource))
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "outerHTML was empty or missing",
                    this, GPALObjectType.PuppeteerCommunicator);
                return string.Empty;
            }
 
            // Return the raw page source. Normalization (JS-unescaping and stripping
            // Chrome's XML-viewer wrapper when a file is being displayed) is applied
            // uniformly for every engine at the choke point in Browser.GetPageSource,
            // so this path stays as "ignorant" as the OttoMagic and Selenium paths.
            return fullSource;
        }
 
        // Implementation for "get-parent-node"
        public async Task<dynamic> GetParentNode(string elementId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            return await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new {
                    contextId = CurrentContextId,
                    expression = "document.getElementById('" + elementId + "').parentNode"
                }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "get-ready-status"

        public async Task<string> GetReadyStatus(string sessionId, string sessionToken)
        {
            sessionId ??= GetEffectiveSessionId();
            string retVal = null;
 
            if (lastSessionToken != sessionToken)
            {
                lastErrorMessage.Clear();
                supressedMessage = false;
                lastSessionToken = sessionToken;
            }
 
            JObject result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
            {
                expression = "document.readyState",
                contextId = CurrentContextId,
                returnByValue = false
            }, sessionId).ConfigureAwait(false);
 
            if (null != result?["result"]?["value"])
                retVal = result?["result"]?["value"]?.ToString();
            else
                retVal = @"""loading""";  //
 
            string currentErrorMessage = $"Document.Ready status [{retVal}]";
 
            if (false == lastErrorMessage.Contains(currentErrorMessage))
            {
                lastErrorMessage.Add(currentErrorMessage);
                GPAL.PublishSimpleEvent(GPALEventType.INFO, currentErrorMessage, null, GPALObjectType.None);
                supressedMessage = false;
            }
            else if (false == supressedMessage)
            {
                GPAL.PublishSimpleEvent(GPALEventType.INFO, "Supressing repeat messages", currentErrorMessage, GPALObjectType.Other);
                supressedMessage = true;
            }
 
            return retVal;
        }
 
        // Implementation for "get-shadow-root"
        public async Task<dynamic> GetShadowRoot(string css, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var nodeId = await QueryByCss(css, sessionId).ConfigureAwait(false);
            return await SendCommand<object>(DevToolsMethods.DOMDescribeNode, new { nodeId, pierce = true }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "get-storage"
        public async Task<string> GetStorage(
            string storageType,
            string sessionId,
            string domain = null,
            string storeName = null,
            string path = null,
            string key = null)
        {
            sessionId ??= GetEffectiveSessionId();
            string resultJson = "null";
 
            try
            {
                switch (storageType)
                {
                    case "cookie":
                        {
                            // get all cookies via CDP
                            dynamic cookiesResp = await SendCommand<dynamic>(DevToolsMethods.StorageGetCookies,
                                null,
                                sessionId).ConfigureAwait(false);
 
                            if (cookiesResp?.cookies != null)
                            {
                                var filtered = new List<dynamic>();
                                path ??= "/";
 
                                foreach (dynamic c in cookiesResp.cookies)
                                {
                                    if ((false == UrlHelper.CookieDomainMatches(((dynamic)c).domain?.ToString(), domain)) ||
                                        (!string.IsNullOrEmpty(path) && ((dynamic)c).path != path) ||
                                        (!string.IsNullOrEmpty(key) && ((dynamic)c).name != key))
                                        continue;
 
                                    // NOTE: this gets all cookies, not just a list of names given a wildcard (missing parm)
                                    // add partitionKey conditionally
                                    if (((dynamic)c).partitionKey != null)
                                    {
                                        filtered.Add(new
                                        {
                                            Key = ((dynamic)c).name,
                                            Domain = ((dynamic)c).domain,
                                            Path = ((dynamic)c).path,
                                            Value = ((dynamic)c).value,
                                            Expires = ((dynamic)c).expires,
 
                                            Secure = ((dynamic)c).secure,
                                            HttpOnly = ((dynamic)c).httpOnly,
                                            SameSite = ((dynamic)c).sameSite,
                                            Session = ((dynamic)c).session,
                                            Priority = ((dynamic)c).priority,
                                            SameParty = ((dynamic)c).sameParty,
                                            SourceScheme = ((dynamic)c).sourceScheme,
                                            SourcePort = ((dynamic)c).sourcePort,
 
                                            PartitionKey = ((dynamic)c).partitionKey
                                        });
                                    }
                                    else
                                    {
                                        filtered.Add(new
                                        {
                                            Key = ((dynamic)c).name,
                                            Domain = ((dynamic)c).domain,
                                            Path = ((dynamic)c).path,
                                            Value = ((dynamic)c).value,
                                            Expires = ((dynamic)c).expires,
 
                                            Secure = ((dynamic)c).secure,
                                            HttpOnly = ((dynamic)c).httpOnly,
                                            SameSite = ((dynamic)c).sameSite,
                                            Session = ((dynamic)c).session,
                                            Priority = ((dynamic)c).priority,
                                            SameParty = ((dynamic)c).sameParty,
                                            SourceScheme = ((dynamic)c).sourceScheme,
                                            SourcePort = ((dynamic)c).sourcePort
                                        });
                                    }
                                }
 
                                resultJson = JsonConvert.SerializeObject(filtered);
                            }
                            break;
                        }
                    case "localStorage":
                    case "sessionStorage":
                        {
                            string js = string.IsNullOrEmpty(key)
                                ? $@"(function(){{
                               let obj={{}};
                               for(let i=0;i<{storageType}.length;i++){{ let k={storageType}.key(i); obj[k]={storageType}.getItem(k); }}
                               return JSON.stringify(obj);
                             }})()"
                                : $"{storageType}.getItem('{EscapeJsString(key)}');";
 
                            var evalResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                            {
                                expression = js,
                                awaitPromise = true,
                                contextId = CurrentContextId,
                                returnByValue = true
                            }, sessionId).ConfigureAwait(false);
 
                            resultJson = evalResult?.result?.value?.ToString() ?? "null";
                            break;
                        }
                    case "indexedDb":
                        {
                            string js;
 
                            if (string.IsNullOrEmpty(path))
                            {
                                // No database name > list all IndexedDB databases
                                js = @"
                                    (async () => {
                                        let dbs = await indexedDB.databases();
                                        return JSON.stringify(dbs.map(db => ({ name: db.name, version: db.version })));
                                    })();";
                            }
                            else if (string.IsNullOrEmpty(storeName))
                            {
                                // Path (database name) given + no object store name > list all object stores in that DB
                                js = $@"
                                    (async () => {{
                                        let req = indexedDB.open('{EscapeJsString(path)}');
                                        return new Promise((resolve) => {{
                                            req.onsuccess = e => {{
                                                let db = e.target.result;
                                                let stores = Array.from(db.objectStoreNames);
                                                db.close();
                                                resolve(JSON.stringify(stores));
                                            }};
                                            req.onerror = () => resolve(null);
                                        }});
                                    }})();";
                            }
                            else if (string.IsNullOrEmpty(key))
                            {
                                // Path + storeName given + no key > list all keys in that specific object store
                                js = $@"
                                    (async () => {{
                                        let req = indexedDB.open('{EscapeJsString(path)}');
                                        return new Promise((resolve) => {{
                                            req.onsuccess = e => {{
                                                let db = e.target.result;
                                                let tx = db.transaction('{EscapeJsString(storeName)}', 'readonly');
                                                let store = tx.objectStore('{EscapeJsString(storeName)}');
                                                let keys = [];
                                                let cursorReq = store.openKeyCursor();
                                                cursorReq.onsuccess = function(event) {{
                                                    let cursor = event.target.result;
                                                    if (cursor) {{
                                                        keys.push(cursor.key);
                                                        cursor.continue();
                                                    }} else {{
                                                        db.close();
                                                        resolve(JSON.stringify(keys));
                                                    }}
                                                }};
                                                cursorReq.onerror = () => {{ db.close(); resolve(null); }};
                                            }};
                                            req.onerror = () => resolve(null);
                                        }});
                                    }})();";
                            }
                            else
                            {
                                // All three (path + storeName + key) > get the value for that key
                                js = $@"
                                    (async () => {{
                                        let req = indexedDB.open('{EscapeJsString(path)}');
                                        return new Promise((resolve) => {{
                                            req.onsuccess = e => {{
                                                let db = e.target.result;
                                                let tx = db.transaction('{EscapeJsString(storeName)}', 'readonly');
                                                let store = tx.objectStore('{EscapeJsString(storeName)}');
                                                let getReq = store.get('{EscapeJsString(key)}');
                                                getReq.onsuccess = () => {{
                                                    db.close();
                                                    resolve(JSON.stringify(getReq.result));
                                                }};
                                                getReq.onerror = () => {{ db.close(); resolve(null); }};
                                            }};
                                            req.onerror = () => resolve(null);
                                        }});
                                    }})();";
                            }
 
                            var evalDb = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                            {
                                expression = js,
                                awaitPromise = true,
                                contextId = CurrentContextId,
                                returnByValue = true
                            }, sessionId).ConfigureAwait(false);
 
                            resultJson = evalDb?.result?.value?.ToString() ?? "null";
                            break;
                        }
 
                    case "cache":
                        {
                            string js;
 
                            if (string.IsNullOrEmpty(storeName))
                            {
                                // no key = enumerate alll cache names
                                // key = return all with the key name
                                js = string.IsNullOrEmpty(key)
                                    ? @"(async ()=>{let c=await caches.keys(); return JSON.stringify(c);})()"
                                    : $@"(async () => {{
                                        const response = await caches.match('{EscapeJsString(key)}');
                                        if (response) {{
                                            const data = await response.json();
                                            return JSON.stringify(data);
                                        }}
                                        return null;
                                    }})();";
                            }
                            else if (string.IsNullOrEmpty(key))
                            {
                                // Path (cache name) is defined + no key > list all keys (as URLs) inside that specific cache
                                js = $@"(async () => {{
                                    const cache = await caches.open('{EscapeJsString(storeName)}');
                                    const keys = await cache.keys();
                                    const keyUrls = keys.map(k => k.url);           // keys are Request objects; we return clean URLs
                                    return JSON.stringify(keyUrls);
                                }})();";
                            }
                            else
                            {
                                // Both path and key are defined > open the specific cache and match the key inside it
                                js = $@"(async () => {{
                                    const cache = await caches.open('{EscapeJsString(storeName)}');
                                    const response = await cache.match('{EscapeJsString(key)}');
                                        if (response) {{{{
                                            const contentType = response.headers.get('content-type') || '';
                                            let data;
                                            if (contentType.includes('application/json') || contentType.includes('text/json')) {{{{
                                                data = await response.json();
                                            }}}} else {{{{
                                                data = await response.text();
                                            }}}}
                                            return JSON.stringify(data);
                                        }}}}
                                        return null;
                                    }})();";
 
                            }
                            var evalCache = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                            {
                                expression = js,
                                awaitPromise = true,
                                contextId = CurrentContextId,
                                returnByValue = true
                            }, sessionId).ConfigureAwait(false);
 
                                resultJson = evalCache?.result?.value?.ToString() ?? "null";
                            break;
                        }
 
                    case "notSet":
                        GPAL.PublishSimpleEvent(
                            GPALEventType.WARNING,
                            $"Nothing to do because StorageType is [{storageType}] d[{domain}] sn[{storeName}] p[{path}] k[{key}]",
                            this,
                            GPALObjectType.PuppeteerCommunicator);
                        break;
 
                    default:
                        GPAL.PublishSimpleEvent(
                            GPALEventType.ERROR,
                            $"Unsupported storage type: [{storageType}]",
                            this,
                            GPALObjectType.PuppeteerCommunicator);
                        break;
                }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(
                    GPALEventType.EXCEPTION,
                    $"GetStorage failed for [{storageType}] d[{domain}] sn[{storeName}] p[{path}] k[{key}]",
                    this,
                    GPALObjectType.PuppeteerCommunicator,
                    ex);
            }
 
            return resultJson;
        }


        public async Task<string> GetUserAgent(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            JObject result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new
                {
                    expression = "navigator.userAgent",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
            return result?["result"]?["value"]?.ToString();
        }
 
        // Implementation for "goto"
        /// <param name="url">The URL to navigate to.</param>
        /// <param name="sessionId">CDP session id; the effective session is used if null.</param>
        /// <returns>Task that resolves to true if navigation succeeded, otherwise false.</returns>
        /// <example>
        /// <code>
        /// await communicator.GoTo("https://example.com");
        /// </code>
        /// </example>
        public async Task<bool> GoTo(string url, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            return await NavigateToUrl(url, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "goto-tab"
        /// <returns>Task that resolves to the targetId of the activated tab, or null if no matching tab was found.</returns>
        public async Task<string> GoToTab(object tabIdOrUrlOrIndex, string sessionId = null)
        {
            string targetId = null;
            var windowArray = _windowSessionsQueue.ToArray();
 
            if (tabIdOrUrlOrIndex is int index)
            {
                if (windowArray.Length == 0 || _activeWindowIndex >= windowArray.Length)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No active window for GoToTab", this, GPALObjectType.PuppeteerCommunicator);
                    return null;
                }
 
                var tabQueue = windowArray[_activeWindowIndex].TabQueue.ToArray();
                if (index < 0 || index >= tabQueue.Length)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Invalid tab index [{index}]", this, GPALObjectType.PuppeteerCommunicator);
                    return null;
                }
 
                // Get targetId from index
                targetId = tabQueue[index].Key;
                if (string.IsNullOrEmpty(targetId))
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"No targetId at index [{index}]", this, GPALObjectType.PuppeteerCommunicator);
                    return null;
                }
 
                // Target.activateTarget is the tab switch itself, not just window ordering - cdp has no way to
                // make a tab current without focusing it, and focusing it raises the window. that raise is the
                // cost of switching tabs, not something GPAL chose
                await SendCommand<object>(DevToolsMethods.TargetActivateTarget, new { targetId }, null).ConfigureAwait(false);
                SetActiveTabIndex(index);
                ((PuppeteerClient)PuppeteerClient)._currentTargetId = targetId;
 
                return targetId;
            }
            else if (tabIdOrUrlOrIndex is string str)
            {
                targetId = await GetTargetTabIdByUrl(str, sessionId).ConfigureAwait(false);
                if (string.IsNullOrEmpty(targetId))
                {
                    // Check if it's a direct targetId
                    foreach (var window in windowArray)
                    {
                        var tabArray = window.TabQueue.ToArray();
                        if (tabArray.Any(kvp => kvp.Key == str))
                        {
                            targetId = str;
                            break;
                        }
                    }
                }
 
                if (string.IsNullOrEmpty(targetId))
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"No target found for tabId or URL [{str}]", this, GPALObjectType.PuppeteerCommunicator);
                    return null;
                }
 
                int windowIndex = GetCurrentWindowIndex(targetId);
                if (windowIndex < 0)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Tab with targetId [{targetId}] not found in any window", this, GPALObjectType.PuppeteerCommunicator);
                    return null;
                }
 
                SetActiveWindowIndex(windowIndex);
                var tabQueue = windowArray[windowIndex].TabQueue.ToArray();
                int tabIndex = Array.FindIndex(tabQueue, kvp => kvp.Key == targetId);
                if (tabIndex < 0)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Tab with targetId [{targetId}] not found in window [{windowArray[windowIndex].BrowserContextId}]", this, GPALObjectType.PuppeteerCommunicator);
                    return null;
                }
 
                await SendCommand<object>(DevToolsMethods.TargetActivateTarget, new { targetId }, null).ConfigureAwait(false);
                SetActiveTabIndex(tabIndex);
                ((PuppeteerClient)PuppeteerClient)._currentTargetId = targetId;
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Switched to tab with targetId [{targetId}], windowIndex [{windowIndex}], tabIndex [{tabIndex}]", this, GPALObjectType.PuppeteerCommunicator);
                return targetId;
            }
 
            GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Invalid input for GoToTab [{tabIdOrUrlOrIndex}]", this, GPALObjectType.PuppeteerCommunicator);
            return null;
        }
 
        // Implementation for "hide-element"
        public async Task<dynamic> HideElement(int backendNodeId, string sessionId = null)
        {
            return await SetAttribute(backendNodeId, "style", "display: none", sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "hover"

        public async Task Hover(int backendNodeId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var x = await GetElementRandomCenterX(backendNodeId, sessionId).ConfigureAwait(false);
            var y = await GetElementRandomCenterY(backendNodeId, sessionId).ConfigureAwait(false);
            await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new { type = "mouseMoved", button = "none", x, y }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "is-clickable"
        /// <code>
        /// bool clickable = await communicator.IsClickable("submitButton");
        /// </code>
        /// </example>
        public async Task<bool> IsClickable(string elementId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            List<GPALElement> elems = await EvaluateSelector(elementId, sessionId).ConfigureAwait(false);
            List<dynamic> responses = new List<dynamic>();
 
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new {
                    contextId = CurrentContextId,
                    expression = "document.getElementById('" + elementId + "').checkVisibility()" 
                }, sessionId).ConfigureAwait(false);
            return (bool)result.value;
        }
 
        // Implementation for "is-displayed"
        public async Task<bool> IsDisplayed(string elementId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new {
                    contextId = CurrentContextId,
                    expression = "document.getElementById('" + elementId + "').offsetParent !== null" 
                }, sessionId).ConfigureAwait(false);
            return (bool)result.value;
        }
 
        // Implementation for "is-enabled"

        public async Task<bool> IsEnabled(string elementId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new {
                    contextId = CurrentContextId,
                    expression = "!document.getElementById('" + elementId + "').disabled" 
                }, sessionId).ConfigureAwait(false);
            return (bool)result.value;
        }
 
        // Implementation for "is-end-of-page"
        public async Task<bool> IsEndOfPage(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            try
            {
                // JavaScript code to check if at end of page
                var result = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = @"
                                (function() {
                                    try {
                                        const overflow = getComputedStyle(document.documentElement).overflow;
                                        if (overflow !== 'hidden') {
                                            return (window.innerHeight + window.scrollY) >= document.body.scrollHeight;
                                        }
                                        const scrollable = Array.from(document.querySelectorAll('*')).find(
                                            el => el.scrollHeight > el.clientHeight && getComputedStyle(el).overflowY !== 'hidden'
                                        ) || document.body;
                                        return (scrollable.clientHeight + scrollable.scrollTop) > scrollable.scrollHeight;
                                    } catch {
                                        return false;
                                    }
                                })()",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
 
                // Parse result
                return (bool)result?["result"]?["value"];
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Error detecting end of page, returning [true]", this, GPALObjectType.PuppeteerCommunicator, ex);
                return true;
            }
        }
 
        // Implementation for "is-visible-in-viewport"
        public async Task<bool> ElementFromPoint(GPALElement element, int x, int y, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            // the node we already have, not a selector re-resolved inside the page. a css lookup here can find
            // a different element or none at all, and it runs in whatever context happens to be current, which is
            // two ways to answer this question about the wrong element
            var resolved = await SendCommand<dynamic>(DevToolsMethods.DOMResolveNode, new
            {
                backendNodeId = element.ElementBackendNodeId
            }, sessionId).ConfigureAwait(false);
 
            string objectId = resolved?.@object?.objectId;
 
            if (true == string.IsNullOrEmpty(objectId))
                return false;
 
            // "this" is the element, so the comparison cannot drift. a descendant counts, since clicking the text
            // inside a button is clicking the button.
            // it answers with what is there rather than just yes or no - "" means this element, anything else
            // names what is covering it, which is the only thing worth knowing when the answer is no
            var result = await SendCommand<dynamic>(DevToolsMethods.RuntimeCallFunctionOn, new
            {
                objectId = objectId,
                functionDeclaration = @"function (x, y) {
                    const hit = document.elementFromPoint(x, y);
                    if (hit === this || this.contains(hit)) { return ''; }
                    if (!hit) { return 'nothing'; }
                    return hit.tagName
                         + (hit.id ? '#' + hit.id : '')
                         + (hit.className ? '.' + String(hit.className).trim().split(/\s+/).join('.') : '');
                }",
                arguments = new object[] { new { value = x }, new { value = y } },
                returnByValue = true
            }, sessionId).ConfigureAwait(false);
 
            string covering = result?.result?.value as string;
 
            if (false == string.IsNullOrEmpty(covering))
                GPAL.PublishSimpleEvent(GPALEventType.INFO, $"[{covering}] is what is at viewport [{x}, {y}], not [{element.TagName}]", null, GPALObjectType.Browser);
 
            return true == string.IsNullOrEmpty(covering) && null != result?.result?.value;
        }
 
        public async Task<bool> IsVisibleInViewport(dynamic elemsOrBackendNodeId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
            {
                expression = @"({ 
                            height: window.innerHeight || document.documentElement.clientHeight, 
                            width:  window.innerWidth  || document.documentElement.clientWidth 
                        })",
                contextId = CurrentContextId,
                returnByValue = true
            }, sessionId).ConfigureAwait(false);
 
            int viewportHeight = 0;
            int viewportWidth = 0;
            bool isInViewport = true;
            if (result?.result?.value != null)
            {
                var dict = ((Newtonsoft.Json.Linq.JObject)result.result.value).ToObject<Dictionary<string, int>>();
                viewportHeight = dict["height"];
                viewportWidth = dict["width"];
            }
 
            if (elemsOrBackendNodeId is List<GPALElement>)
                foreach (GPALElement element in elemsOrBackendNodeId)
                {
                    Rectangle rect = await GetBoundingClientRect(element.ElementBackendNodeId, sessionId).ConfigureAwait(false);
                    if (-1 == rect.X)   // NOTE: CAVEAT: if we cannot compute the box model, the element is prolly not interactable/false positive, so fail-forward
                        isInViewport = true;
                    else
                        isInViewport &= rect.Top >= 0 &&
                                   rect.Left >= 0 &&
                                   rect.Bottom <= viewportHeight &&
                                   rect.Right <= viewportWidth;
                }
            else
            {
                Rectangle rect = await GetBoundingClientRect(elemsOrBackendNodeId, sessionId).ConfigureAwait(false);
                if (-1 == rect.X)   // NOTE: CAVEAT: if we cannot compute the box model, the element is prolly not interactable/false positive, so fail-forward
                    isInViewport = true;
                else
                    isInViewport &= rect.Top >= 0 &&
                           rect.Left >= 0 &&
                           rect.Bottom <= viewportHeight &&
                           rect.Right <= viewportWidth;
            }
            return isInViewport;
        }
 
        // Implementation for "left-click"
        public async Task ClickElement(GPALElement element, string sessionId, List<dynamic> responses,
                                      ClickType clickType = ClickType.LeftClick,
                                      int modifiers = 0)
        {
            bool cdpSuccess = false;
            bool elementNotRendered = false;
            bool forceJavscript = false;
            bool jsSuccess = false;
            bool isInFrame = CurrentContextId.HasValue;
            string effectiveSessionId = isInFrame && !string.IsNullOrEmpty(CurrentFrameSessionId)
                ? CurrentFrameSessionId
                : sessionId;
 
            try
            {
                // NOTE: for headless which is not finding a box model on an A tag
                // Get fresh box model
                // Cheap reflow trigger via JS (very reliable)
                if (true == Browser.BrowserSettings.UseHeadless)
                {
                    await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
                    {
                        expression = "document.body.offsetHeight;",  // reads force layout
                        contextId = CurrentContextId,
                        returnByValue = true
                    }, sessionId).ConfigureAwait(false);
 
                    await Task.Delay(80).ConfigureAwait(false);  // extra breathing room
                }
 
                var boxModel = await SendCommand<object>(DevToolsMethods.DOMGetBoxModel, new
                {
                    objectId = element.ElementHandle
                }, effectiveSessionId).ConfigureAwait(false);
 
                if (null != boxModel)
                {
                    var contentQuad = boxModel?.model?.content;
                    if (contentQuad == null || contentQuad.Count < 8)
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"[{element.TagName}][{clickType}] failed: Unable to get coordinates (boxmodel)");
                    }
                    else
                    {
                        float x = (float)contentQuad[0];
                        float y = (float)contentQuad[1];
                        float width = (float)(contentQuad[2] - contentQuad[0]);
                        float height = (float)(contentQuad[7] - contentQuad[1]);
 
                        var random = new Random();
                        var margin = 0.05f;
                        var clickAreaWidth = width * (1f - 2 * margin);
                        var clickAreaHeight = height * (1f - 2 * margin);
 
                        x = x + width * margin + (float)random.NextDouble() * clickAreaWidth;
                        y = y + height * margin + (float)random.NextDouble() * clickAreaHeight;
 
                        if (0 < x && 0 < y)
                        {
                            // Force center for <a> tags (your existing behavior)
                            if ("A".Equals(element.TagName, StringComparison.OrdinalIgnoreCase))
                            {
                                x = (float)contentQuad[0] + width / 2f;
                                y = (float)contentQuad[1] + height / 2f;
                            }
 
                            // Map ClickType -> CDP values
                            string button = clickType switch
                            {
                                ClickType.LeftClick => "left",
                                ClickType.MiddleClick => "middle",
                                ClickType.RightClick => "right",
                                ClickType.LeftDoubleClick => "left",
                                _ => "left"
                            };
 
                            int clickCount = clickType == ClickType.LeftDoubleClick ? 2 : 1;
 
                            // PRESS
                            responses.Add(await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new
                            {
                                type = "mousePressed",
                                button,
                                buttons = PressedButtons(button),
                                clickCount,
                                x,
                                y,
                                modifiers
                            }, effectiveSessionId).ConfigureAwait(false));
 
                            await Task.Delay(random.Next(60, 140)).ConfigureAwait(false); // human-like
 
                            // RELEASE
                            responses.Add(await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new
                            {
                                type = "mouseReleased",
                                button,
                                clickCount,
                                x = x + random.Next(-2, 3),
                                y = y + random.Next(-2, 3),
                                modifiers
                            }, effectiveSessionId).ConfigureAwait(false));
                            cdpSuccess = true;
                        }
                        else
                        {
                            // the box model is viewport relative, so a negative coordinate means the element sits
                            // outside the viewport and a dispatched mouse event there would land on nothing
                            GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"CDP [{clickType}] has no on-screen point for [{element.TagName}][{element.Css}] at [{x},{y}]. Falling back to JavaScript.", this, GPALObjectType.PuppeteerClient);
                            forceJavscript = true;
                        }
                    }
                }
                else
                {
                    // no box model and a rect with no size is the same answer arrived at the other way
                    elementNotRendered = 0 >= element.BoundingRect.Width || 0 >= element.BoundingRect.Height;
 
                    float x = (float)element.BoundingRect.X;
                    float y = (float)element.BoundingRect.Y;
                    float width = (float)element.BoundingRect.Width;
                    float height = (float)element.BoundingRect.Height;
 
                    var random = new Random();
                    var margin = 0.05f;
                    var clickAreaWidth = width * (1f - 2 * margin);
                    var clickAreaHeight = height * (1f - 2 * margin);
 
                    x = x + width * margin + (float)random.NextDouble() * clickAreaWidth;
                    y = y + height * margin + (float)random.NextDouble() * clickAreaHeight;
 
                    if (0 < x && 0 < y)
                    {
                        // Force center for <a> tags (your existing behavior)
                        if ("A".Equals(element.TagName, StringComparison.OrdinalIgnoreCase))
                        {
                            x = (float)element.BoundingRect.X + width / 2f;
                            y = (float)element.BoundingRect.Y + height / 2f;
                        }
 
                        // Map ClickType -> CDP values
                        string button = clickType switch
                        {
                            ClickType.LeftClick => "left",
                            ClickType.MiddleClick => "middle",
                            ClickType.RightClick => "right",
                            ClickType.LeftDoubleClick => "left",
                            _ => "left"
                        };
 
                        int clickCount = clickType == ClickType.LeftDoubleClick ? 2 : 1;
 
                        // PRESS
                        responses.Add(await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new
                        {
                            type = "mousePressed",
                            button,
                            buttons = PressedButtons(button),
                            clickCount,
                            x,
                            y,
                            modifiers
                        }, effectiveSessionId).ConfigureAwait(false));
 
                        await Task.Delay(random.Next(60, 140)).ConfigureAwait(false); // human-like
 
                        // RELEASE
                        responses.Add(await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new
                        {
                            type = "mouseReleased",
                            button,
                            clickCount,
                            x = x + random.Next(-2, 3),
                            y = y + random.Next(-2, 3),
                            modifiers
                        }, effectiveSessionId).ConfigureAwait(false));
                        cdpSuccess = true;
                    }
                    else if (true == elementNotRendered)
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.INFO, $"CDP [{clickType}] has no point to click for [{element.TagName}][{element.Css}]. Element is not rendered, so it has no position on the page. Falling back to JavaScript.", this, GPALObjectType.PuppeteerClient);
                        forceJavscript = true;
                    }
                    else
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"CDP [{clickType}] failed. Falling back to JavaScript.", this, GPALObjectType.PuppeteerClient);
                        forceJavscript = true;
                    }
                }
            }
            catch (Exception ex)
            {
                if (!GPAL.NoFallbackRecoveryActions)
                    GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"CDP [{clickType}] failed.{(false == GPAL.NoFallbackRecoveryActions ? " Falling back to JavaScript." : " Javascript fallback disallowed.")}", this, GPALObjectType.PuppeteerClient, ex);
            }
 
            // Optional JS fallback (keep your existing one, or remove if CDP never fails anymore)
            if (false == GPAL.NoFallbackRecoveryActions && (false == cdpSuccess || true == forceJavscript))
            {
                bool byCss = false == string.IsNullOrEmpty(element.Css);
                string selector = true == byCss ? element.Css : element.Xpath;
 
                if (string.IsNullOrEmpty(selector))
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Fallback JavaScript failed: No valid XPath or CSS selector for [{element.TagName}]", this, GPALObjectType.PuppeteerClient);
 
                var clickScript = $@"
                            (() => {{
                                try {{
                                    const sel = `{selector.Replace("'", "\\'")}`;
 
                                    // looked up as the kind of selector that was actually passed. handing a css selector to
                                    // document.evaluate throws, and the throw skipped the lookup that would have worked
                                    const el = {(true == byCss ? "document.querySelector(sel)" : "document.evaluate(sel, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue")};
                                    if (!el) return false;
 
                                    // getBoundingClientRect is already viewport relative, which is what clientX and
                                    // clientY are defined as. adding the scroll offset turns them into document
                                    // coordinates and any handler that hit tests the event reads the wrong point
                                    const rect = el.getBoundingClientRect();
                                    const cx = rect.left + rect.width  / 2;
                                    const cy = rect.top  + rect.height / 2;
 
                                    const opts = {{ bubbles: true, cancelable: true, clientX: cx, clientY: cy, view: window }};
 
                                    // === LEFT CLICK (or double) ===
                                    if ({(clickType == ClickType.LeftClick || clickType == ClickType.LeftDoubleClick).ToString().ToLower()}) {{
                                        const count = {(clickType == ClickType.LeftDoubleClick ? 2 : 1)};
                                        for (let i = 0; i < count; i++) {{
                                            el.dispatchEvent(new MouseEvent('mousedown', {{...opts, button: 0, buttons: 1}}));
                                            el.dispatchEvent(new MouseEvent('mouseup',   {{...opts, button: 0, buttons: 0}}));
                                            el.dispatchEvent(new MouseEvent('click',     {{...opts, button: 0, detail: i+1}}));
                                            if (i === 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 80); // ~80ms between clicks
                                        }}
                                        return true;
                                    }}
 
                                    // === MIDDLE CLICK (eBay pop-under) ===
                                    if ({(clickType == ClickType.MiddleClick).ToString().ToLower()}) {{
                                        el.dispatchEvent(new MouseEvent('mousedown', {{...opts, button: 1, buttons: 4}}));
                                        el.dispatchEvent(new MouseEvent('mouseup',   {{...opts, button: 1, buttons: 0}}));
                                        el.dispatchEvent(new MouseEvent('click',     {{...opts, button: 1}}));
                                        return true;
                                    }}
 
                                    // === RIGHT CLICK (context menu) ===
                                    if ({(clickType == ClickType.RightClick).ToString().ToLower()}) {{
                                        el.dispatchEvent(new MouseEvent('mousedown', {{...opts, button: 2, buttons: 2}}));
                                        el.dispatchEvent(new MouseEvent('mouseup',   {{...opts, button: 2, buttons: 0}}));
                                        el.dispatchEvent(new MouseEvent('contextmenu', {{...opts, button: 2}}));
                                        return true;
                                    }}
 
                                    return false;
                                }} catch(e) {{
                                    return false;
                                }}
                            }})();
                            ";
 
                if (false == string.IsNullOrEmpty(selector))
                {
                    dynamic jsResult = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
                    {
                        expression = clickScript,
                        objectGroup = "node",
                        contextId = CurrentContextId,
                        returnByValue = true
                    }, sessionId).ConfigureAwait(false);
 
                    responses.Add(jsResult);
 
                    // the script returns false when it cannot find the element or the click type has no branch
                    if (jsResult?.result?.value is bool clicked && clicked)
                        jsSuccess = true;
                }
            }
 
            // name the path that actually dispatched. a click that reached neither is the one that leaves the page
            // unchanged and scrapes the same results twice, so it cannot read the same as a click that landed
            string clickPath = true == cdpSuccess ? "CDP" : true == jsSuccess ? "JavaScript" : "nothing";
 
            GPAL.PublishSimpleEvent(true == cdpSuccess || true == jsSuccess ? GPALEventType.INFO : GPALEventType.WARNING,
                $"Puppeteer [{clickType}] [{element.TagName}][{Browser.CurrentUOW.CurrentSelector.Name}] w/modifiers [{((PuppeteerClient)PuppeteerClient).GetModifiersString(modifiers)}] dispatched by [{clickPath}]",
                this, GPALObjectType.PuppeteerCommunicator);
        }
        /// <param name="deltaX">Horizontal drag distance in pixels from the element's center.</param>
        /// <param name="deltaY">Vertical drag distance in pixels from the element's center.</param>
        public async Task DragAndDrop(GPALElement element, string sessionId, List<dynamic> responses, int deltaX, int deltaY, int offsetX = 0, int offsetY = 0)
        {
            var startX = (float)element.BoundingRect.X + (float)element.BoundingRect.Width / 2 + offsetX;
            var startY = (float)element.BoundingRect.Y + (float)element.BoundingRect.Height / 2 + offsetY;
            var endX = startX + deltaX;
            var endY = startY + deltaY;
 
            responses.Add(await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new
            {
                type = "mousePressed",
                button = "left",
                clickCount = 1,
                x = startX,
                y = startY,
                modifiers = 0
            }, sessionId).ConfigureAwait(false));
 
            const int STEPS = 10;
            for (int i = 1; i <= STEPS; i++)
            {
                var x = startX + (endX - startX) * i / STEPS;
                var y = startY + (endY - startY) * i / STEPS;
 
                responses.Add(await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new
                {
                    type = "mouseMoved",
                    button = "left",
                    buttons = 1,
                    x,
                    y,
                    modifiers = 0
                }, sessionId).ConfigureAwait(false));
 
                await Task.Delay(15).ConfigureAwait(false);
            }
 
            responses.Add(await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new
            {
                type = "mouseReleased",
                button = "left",
                clickCount = 1,
                x = endX,
                y = endY,
                modifiers = 0
            }, sessionId).ConfigureAwait(false));
        }
        public async Task LeftClick(string elementId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            List<GPALElement> elems = await EvaluateSelector(elementId, sessionId).ConfigureAwait(false);
            List<dynamic> responses = new List<dynamic>();
 
            foreach (GPALElement elem in elems)
            {
                await ScrollIntoView(elem, sessionId).ConfigureAwait(false);
                await ClickElement(elem, sessionId, responses, ClickType.LeftClick).ConfigureAwait(false);
            }
        }

        public async Task SetDownloadBehavior(string downloadPath, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            await SendCommand<object>(DevToolsMethods.BrowserSetDownloadBehavior, new { behavior = "allow", downloadPath = downloadPath }, sessionId).ConfigureAwait(false);
        }

        /// <param name="sessionId">CDP session ID; falls back to the current effective session if null</param>
        /// <returns>Task representing the asynchronous call</returns>
        public async Task RestoreDownloadBehavior(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            await SendCommand<object>(DevToolsMethods.BrowserSetDownloadBehavior, new { behavior = "default" }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "left-click-download"
        // NOTE: HEADLESS ONLY

        /// <param name="responses">List collecting the raw CDP responses from each click.</param>
        /// <returns>Task representing the asynchronous click-and-download operation.</returns>
        public async Task LeftClickAndDownload(List<GPALElement> elems, string downloadPath, int modifiers, string sessionId, List<dynamic> responses)
        {
            sessionId ??= GetEffectiveSessionId();
 
            string saveDirectory = Path.GetDirectoryName(downloadPath);
 
            // NOTE: we can set the download directory, but not the filename, so we still require the downloadwatcher
            await SetDownloadBehavior(saveDirectory, sessionId).ConfigureAwait(false);
 
            foreach (GPALElement elem in elems)
            {
                await ScrollIntoView(elem, sessionId).ConfigureAwait(false);
                await ClickElement(elem, sessionId, responses, ClickType.LeftClick, modifiers).ConfigureAwait(false);
            }
        }
        // Implementation for "left-click-and-upload"
        // NOTE: HEADLESS ONLY
        // NOTE: CAV#EAT: in order to call leftclickandupload repeatedly, we must track the files ourselves and clear the list...
        private static readonly Dictionary<string, List<string>> _attachedFilesPerSession = new Dictionary<string, List<string>>();

        /// Attaches one or more files to file input element(s) using CDP.
        /// Supports single file path (string) or multiple paths (List&lt;string&gt; / IEnumerable&lt;string&gt;).
        /// Accumulates files across calls by tracking attached paths per session/input and re-attaching the full list each time.
        /// Uses DOM.setFileInputFiles to set files directly (headless-friendly, no dialog).
        /// Dispatches change event after attachment to trigger page/widget processing.
        /// </summary>
        /// <param name="elems">List of GPALElement instances representing the file input(s). Usually one, but supports multiple.</param>
        /// <param name="uploadFiles">
        /// File path(s) to attach.
        /// - string: single file path (e.g. @"C:\temp\report.pdf")
        /// - IEnumerable&lt;string&gt; or List&lt;string&gt;: multiple file paths (e.g. new[] { @"C:\file1.pdf", @"C:\file2.jpg" })
        /// </param>
        /// <param name="modifiers">Keyboard modifiers (not used in current implementation)</param>
        /// <param name="sessionId">CDP session ID (optional; falls back to current)</param>
        /// <param name="responses">Optional list to collect status/info (e.g. for logging or fluent chaining)</param>
        /// <returns>Task (async operation)</returns>
        /// <example>
        /// Single file:
        /// <code>
        /// await LeftClickAndUpload(elems, @"C:\temp\doc.pdf", 0, sessionId, responses);
        /// </code>
        ///
        /// Multiple files (additive across calls):
        /// <code>
        /// var files = new List&lt;string&gt; { @"C:\doc1.pdf" };
        /// await LeftClickAndUpload(elems, files, 0, sessionId, responses);
        ///
        /// files.Add(@"C:\photo.jpg");
        /// await LeftClickAndUpload(elems, files, 0, sessionId, responses);  // now attaches both
        /// </code>
        ///
        /// Mixed:
        /// <code>
        /// await LeftClickAndUpload(elems, @"C:\invoice.docx", 0, sessionId, responses);  // single
        /// await LeftClickAndUpload(elems, new[] { @"C:\old1.pdf", @"C:\old2.pdf" }, 0, sessionId, responses);  // full list
        /// </code>
        /// </example>
        public async Task LeftClickAndUpload(
            List<GPALElement> elems,
            object uploadFiles,
            int modifiers,
            string sessionId,
            List<dynamic> responses)
        {
            sessionId ??= GetEffectiveSessionId();
 
            // Normalize uploadFiles to List<string>
            var newPaths = new List<string>();
 
            if (uploadFiles is string singlePath)
            {
                if ("" != singlePath?.Trim())
                {
                    newPaths.Add(Path.GetFullPath(singlePath));
                }
            }
            else if (uploadFiles is GPALFile pathEnumerable)
            {
                foreach (var p in pathEnumerable.Filenames)
                {
                    if ("" != p?.Trim())
                    {
                        newPaths.Add(Path.GetFullPath(p));
                    }
                }
            }
            else
            {
                // Invalid type – silent skip (fluent style)
                return;
            }
 
            if (0 == newPaths.Count)
            {
                return; // nothing to attach
            }
 
            foreach (GPALElement fileInput in elems)
            {
                string nodeKey = $"{sessionId}:{fileInput.ElementBackendNodeId}";
 
                // Get browser-reported file count via attribute
                string fileCountStr = fileInput.GetAttribute("length");
                int browserFileCount = 0;
 
                if ("" != fileCountStr)
                {
                    Int32.TryParse(fileCountStr, out browserFileCount);
                }
 
                // Get or create tracked list
                if (false == _attachedFilesPerSession.TryGetValue(nodeKey, out var currentFiles))
                {
                    currentFiles = new List<string>();
                    _attachedFilesPerSession[nodeKey] = currentFiles;
                }
 
                // Staleness check: browser count != tracked count > reset
                if (browserFileCount != currentFiles.Count)
                {
                    currentFiles.Clear();
                    _attachedFilesPerSession[nodeKey] = currentFiles;
                }
 
                // Add new paths
                currentFiles.AddRange(newPaths);
 
                var setFilesParams = new
                {
                    nodeId = fileInput.ElementNodeId,
                    files = currentFiles.ToArray()
                };
 
                await SendCommand<object>(DevToolsMethods.DOMSetFileInputFiles, setFilesParams, sessionId).ConfigureAwait(false);
                await FireChangeEvent(fileInput.ElementHandle, sessionId).ConfigureAwait(false);
 
                responses?.Add(new
                {
                    status = "upload_attached",
                    pathsAdded = newPaths,
                    totalFilesTracked = currentFiles.Count,
                    browserReportedCount = browserFileCount
                });
            }
        }
 
        // Implementation for "left-double-click"
        public async Task LeftDoubleClick(string elementId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            List<GPALElement> elems = await EvaluateSelector(elementId, sessionId).ConfigureAwait(false);
            List<dynamic> responses = new List<dynamic>();
 
            foreach (GPALElement elem in elems)
            {
                await ScrollIntoView(elem, sessionId).ConfigureAwait(false);
                await ClickElement(elem, sessionId, responses, ClickType.LeftDoubleClick).ConfigureAwait(false);
            }
        }
 
 
        // Implementation for "maximize"
        public async Task<bool> Maximize(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            var windowId = await GetCurrentWindow(sessionId).ConfigureAwait(false);
 
            // window state, not bounds - chromium reads a bounds set as a normal window at that size
            await SendCommand(DevToolsMethods.BrowserSetWindowBounds, new
            {
                windowId,
                bounds = new { windowState = "maximized" }
            }, sessionId).ConfigureAwait(false);
 
            return true;
        }
 
        // Implementation for "minimize"
        public async Task<bool> Minimize(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            var windowId = await GetCurrentWindow(sessionId).ConfigureAwait(false);
            await SendCommand(DevToolsMethods.BrowserSetWindowBounds, new
            {
                windowId = windowId,
                bounds = new { windowState = "minimized" }
            }, sessionId).ConfigureAwait(false);
 
            return true;
        }
        public async Task<bool> MoveTo(List<GPALElement> elems, string sessionId, List<dynamic> responses)
        {
            bool retVal = true;
 
            foreach (GPALElement element in elems)
            {
                try
                {
                    await ScrollIntoView(element, sessionId).ConfigureAwait(false);
 
                    // Randomize move within 90% of the element's border
                    var random = new Random();
                    var margin = 0.05f; // 5% margin on each side (90% clickable area)
                    var clickAreaWidth = (float)element.BoundingRect.Width * (1f - 2 * margin);
                    var clickAreaHeight = (float)element.BoundingRect.Height * (1f - 2 * margin);
                    var x = (float)element.BoundingRect.X + (float)element.BoundingRect.Width * margin + (float)random.NextDouble() * clickAreaWidth;
                    var y = (float)element.BoundingRect.Y + (float)element.BoundingRect.Height * margin + (float)random.NextDouble() * clickAreaHeight;
 
                    if (true == "A".Equals(element.TagName)) // click in dead center, don't miss it, altho width could be a bit more tolerant
                    {
                        x = (float)element.BoundingRect.X + (float)element.BoundingRect.Width / 2;
                        y = (float)element.BoundingRect.Y + (float)element.BoundingRect.Height / 2;
                    }
 
                    responses.Add(await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new
                    {
                        type = "mouseMoved",
                        x,
                        y,
                        modifiers = 0
                    }, sessionId).ConfigureAwait(false));
                }
                catch (Exception ex)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Error moving to element [{element.ElementHandle}][{element.Css}]", this, GPALObjectType.Puppeteer, ex);
                    retVal = false;
                }
            }
            return retVal;
        }
        // Implementation for "move-to"
        public async Task MoveTo(int backendNodeId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var x = await GetElementRandomCenterX(backendNodeId, sessionId).ConfigureAwait(false);
            var y = await GetElementRandomCenterY(backendNodeId, sessionId).ConfigureAwait(false);
            await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new { type = "mouseMoved", x, y }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "click-point"
        private static int PressedButtons(string button)
        {
            int retVal = "middle" == button ? 4 : "right" == button ? 2 : 1;
 
            return retVal;
        }
 
        public async Task ClickElement(int x, int y, string sessionId, List<dynamic> responses,
                                       ClickType clickType = ClickType.LeftClick,
                                       int modifiers = 0)
        {
            sessionId ??= GetEffectiveSessionId();
 
            string button = clickType switch
            {
                ClickType.LeftClick => "left",
                ClickType.MiddleClick => "middle",
                ClickType.RightClick => "right",
                ClickType.LeftDoubleClick => "left",
                _ => "left"
            };
 
            int clickCount = ClickType.LeftDoubleClick == clickType ? 2 : 1;
            var random = new Random();
 
            // land the pointer first so :hover resolves before the press, same as a real mouse would
            await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new
            {
                type = "mouseMoved",
                button = "none",
                x,
                y
            }, sessionId).ConfigureAwait(false);
 
            responses.Add(await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new
            {
                type = "mousePressed",
                button,
                buttons = PressedButtons(button),
                clickCount,
                x,
                y,
                modifiers
            }, sessionId).ConfigureAwait(false));
 
            await Task.Delay(random.Next(60, 140)).ConfigureAwait(false); // human-like
 
            responses.Add(await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new
            {
                type = "mouseReleased",
                button,
                clickCount,
                x,
                y,
                modifiers
            }, sessionId).ConfigureAwait(false));
        }
 
        // Implementation for "move-to-point"
        public async Task MoveTo(int x, int y, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            await SendCommand<object>(DevToolsMethods.InputDispatchMouseEvent, new { type = "mouseMoved", button = "none", x, y }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "new-tab"

        public async Task<string> NewTab(GPALUrl url = null, string sessionId = null)
        {
            if (null == url)
                url = new GPALUrl();
 
            sessionId ??= GetEffectiveSessionId();
            url.ForUrl(MagicHelper.GetFullUrl(url.Url, Browser, out Browser._areRobotsAllowed));
 
            if (false == Browser.AreRobotsAllowed && true == Browser.BrowserSettings.ObeyRobotsTxt)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Visiting [{url.Url}] is disallowed by robots.txt and your request to honor it. Not going to URL. Workflow will fail.", this, GPALObjectType.PuppeteerCommunicator);
                url.ForUrl("https://google.com");
            }
 
            var browserContextId = GetActiveWindowId();
            if (string.IsNullOrEmpty(browserContextId))
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR,
                    "NewTab: No active window found to attach tab",
                    this, GPALObjectType.PuppeteerCommunicator);
                return null;
            }
 
            // Create new target in the current active window (browserContextId).
            // not background: NewTab means the workflow moves to the tab, the same as it does on selenium and
            // ottomagic. a background tab left the browser showing the old page while GPAL drove the new one
            var result = await SendCommand<object>(DevToolsMethods.TargetCreateTarget,
                new { url = url.Url, browserContextId }, null).ConfigureAwait(false);
 
            string targetId = result.targetId.ToString();
 
            // brought to the front, then attached, so the session every later command goes through belongs to
            // the tab the workflow is now looking at
            await SendCommand<object>(DevToolsMethods.TargetActivateTarget, new { targetId }, null).ConfigureAwait(false);
 
            var attached = await SendCommand<object>(DevToolsMethods.TargetAttachToTarget,
                new { targetId, flatten = true }, null).ConfigureAwait(false);
 
            string tabSessionId = attached?.sessionId?.ToString();
 
            if (true == string.IsNullOrEmpty(tabSessionId))
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Opened tab [{targetId}] but could not attach to it, so commands still go to the tab before it", this, GPALObjectType.PuppeteerCommunicator);
 
            // Handle attachment and queuing
            await HandleNewTarget(targetId, browserContextId, tabSessionId, false, true).ConfigureAwait(false);
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG,
                $"Opened new tab TargetId [{targetId}] in Window [{browserContextId}]",
                this, GPALObjectType.PuppeteerCommunicator);
 
            return targetId;
        }
 
        // helper for next/previoustab
        // Implementation for getCurrentTabIndex
        internal int GetCurrentTabIndex(string currentTargetId)
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (windowArray.Length == 0 || _activeWindowIndex >= windowArray.Length)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No active window for NextTab", this, GPALObjectType.PuppeteerCommunicator);
                return 0;
            }
 
            var tabQueue = windowArray[_activeWindowIndex].TabQueue;
            var queueArray = tabQueue.ToArray();
            if (queueArray.Length == 0)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No tabs for NextTab", this, GPALObjectType.PuppeteerCommunicator);
                return 0;
            }
 
            var currentIndex = Array.FindIndex(queueArray, kvp => kvp.Key == currentTargetId);
            if (currentIndex == -1)
                currentIndex = windowArray[_activeWindowIndex].ActiveTabIndex;
 
            return currentIndex;
        }
        // Implementation for "next-tab"

        public async Task<string> NextTab(string currentTargetId)
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (windowArray.Length == 0 || _activeWindowIndex >= windowArray.Length)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No active window for NextTab", this, GPALObjectType.PuppeteerCommunicator);
                return null;
            }
 
            var session = windowArray[_activeWindowIndex];
            var tabQueue = session.TabQueue;
            var browserContextId = session.BrowserContextId;  // Use stored BrowserContextId
 
            // Poll all targets via CDP to discover unknown pages
            var targetsResponse = await SendCommand<dynamic>(
                DevToolsMethods.TargetGetTargets,
                new { },
                null  // Browser-level command, no sessionId
            ).ConfigureAwait(false);
 
            if (targetsResponse?.targetInfos == null)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "Failed to get targets list in NextTab sync", this, GPALObjectType.PuppeteerCommunicator);
                // Proceed anyway with existing queue
            }
            else
            {
                var knownTargetIds = new HashSet<string>(tabQueue.Select(kv => kv.Key));
 
                foreach (var targetInfo in targetsResponse.targetInfos)
                {
                    string targetId = targetInfo.targetId?.ToString();
                    string type = targetInfo.type?.ToString();
                    string contextId = targetInfo.browserContextId?.ToString();
 
                    if (string.IsNullOrEmpty(targetId) || type != "page" || contextId != browserContextId)
                        continue;
 
                    if (!knownTargetIds.Contains(targetId))
                    {
                        // Add with doNotGetSendSemaphore=true to avoid reentrancy/locking issues
                        await AddTabToQueue(targetId, null, false, true).ConfigureAwait(false);
                        knownTargetIds.Add(targetId);
                    }
                }
            }
 
            var queueArray = tabQueue.ToArray();
            if (queueArray.Length == 0)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No tabs for NextTab", this, GPALObjectType.PuppeteerCommunicator);
                return null;
            }
 
            // find where we are by target id, the way PreviousTab already does. The stored ActiveTabIndex is a
            // position, and a position points at the wrong tab as soon as a tab is added or removed. It stays as
            // the fallback for the case where the id is not in the queue at all
            var currentIndex = Array.FindIndex(queueArray, kvp => kvp.Key == currentTargetId);
            if (currentIndex == -1)
            {
                currentIndex = session.ActiveTabIndex;
            }
 
            var nextIndex = (currentIndex + 1) % queueArray.Length;
            var nextTargetId = await GoToTab(nextIndex).ConfigureAwait(false);
 
            session.ActiveTabIndex = nextIndex;
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG,
                $"Switched to index [{nextIndex}], ID [{nextTargetId}], Active window tab queue size [{queueArray.Length}]",
                this, GPALObjectType.PuppeteerCommunicator);
 
            return nextTargetId;
        }
        /*
        public async Task<string> NextTab(string currentTargetId)
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (windowArray.Length == 0 || _activeWindowIndex >= windowArray.Length)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No active window for NextTab", this, GPALObjectType.PuppeteerCommunicator);
                return null;
            }
 
            var tabQueue = windowArray[_activeWindowIndex].TabQueue;
            var queueArray = tabQueue.ToArray();
            if (queueArray.Length == 0)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No tabs for NextTab", this, GPALObjectType.PuppeteerCommunicator);
                return null;
            }
 
            var currentIndex = windowArray[_activeWindowIndex].ActiveTabIndex;
 
            var nextIndex = (currentIndex + 1) % queueArray.Length;
            var nextTargetId = await GoToTab(nextIndex);
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Switched to index [{nextIndex}], ID [{nextTargetId}], Active window tab queue size [{queueArray.Length}]", this, GPALObjectType.PuppeteerCommunicator);
 
            return nextTargetId;
        }
        */
        // Implementation for "next-window"

        public async Task<string> NextWindow(string currentTargetId)
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (windowArray.Length == 0)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No windows for NextWindow", this, GPALObjectType.PuppeteerCommunicator);
                return null;
            }
 
            var currentWindowIndex = -1;
            for (int i = 0; i < windowArray.Length; i++)
            {
                var tabArray = windowArray[i].TabQueue.ToArray();
                if (Array.Exists(tabArray, kvp => kvp.Key == currentTargetId))
                {
                    currentWindowIndex = i;
                    break;
                }
            }
            if (currentWindowIndex == -1)
            {
                currentWindowIndex = _activeWindowIndex;
            }
 
            var nextWindowIndex = (currentWindowIndex + 1) % windowArray.Length;
            SetActiveWindowIndex(nextWindowIndex);
 
            var nextWindowContextId = windowArray[nextWindowIndex].BrowserContextId;
            var nextTabQueue = windowArray[nextWindowIndex].TabQueue;
            var nextTabArray = nextTabQueue.ToArray();
            if (nextTabArray.Length == 0)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, "No tabs in next window for NextWindow", this, GPALObjectType.PuppeteerCommunicator);
                return null;
            }
 
            var nextTargetId = nextTabArray[windowArray[nextWindowIndex].ActiveTabIndex].Key;
            var nextSessionId = nextTabArray[windowArray[nextWindowIndex].ActiveTabIndex].Value;
 
            await SendCommand<object>(DevToolsMethods.TargetActivateTarget, new { targetId = nextTargetId }, null).ConfigureAwait(false);
 
            if (await SendCommand<object>(DevToolsMethods.PageEnable, new { }, nextSessionId).ConfigureAwait(false) == null)
            {
                var newSession = await SendCommand<object>(DevToolsMethods.TargetAttachToTarget, new { targetId = nextTargetId, flatten = true }, null).ConfigureAwait(false);
                if (newSession?.sessionId != null)
                {
                    nextSessionId = (string)newSession.sessionId;
                    RemoveTabFromQueue(nextTargetId);
                    await AddTabToQueue(nextTargetId, nextSessionId).ConfigureAwait(false);
                }
                else
                {
                    GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Failed to re-attach NextWindow tab ID [{nextTargetId}]", this, GPALObjectType.PuppeteerCommunicator);
                    return null;
                }
                await SendCommand<object>(DevToolsMethods.PageDisable, new { }, nextSessionId).ConfigureAwait(false);
            }
            else
            {
                await SendCommand<object>(DevToolsMethods.PageDisable, new { }, nextSessionId).ConfigureAwait(false);
            }
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"NextWindow: Switched to window index [{nextWindowIndex}], Context [{nextWindowContextId}], Tab ID [{nextTargetId}]", this, GPALObjectType.PuppeteerCommunicator);
            return nextTargetId;
        }
        // Implementation for "normal"
        /// Restores the browser window to its normal (non-maximized, non-minimized) state.
        /// Implementation for the "normal" workflow action.
        /// </summary>
        /// <param name="sessionId">CDP session ID; falls back to the current effective session if null.</param>
        /// <returns>Task that resolves to true once the window state has been set to normal.</returns>
        public async Task<bool> Normal(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            var windowId = await GetCurrentWindow(sessionId).ConfigureAwait(false);
            await SendCommand(DevToolsMethods.BrowserSetWindowBounds, new
            {
                windowId = windowId,
                bounds = new { windowState = "normal" }
            }, sessionId).ConfigureAwait(false);
 
            return true;
        }
 
        // Implementation for "open-window"
        public async Task<string> OpenWindow(string url = "https://google.com", string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            // Create the new target in its own browser context
            var context = await SendCommand<object>(DevToolsMethods.TargetCreateBrowserContext, new { }, sessionId).ConfigureAwait(false);
            string browserContextId = context.browserContextId.ToString();
 
            var result = await SendCommand<object>(DevToolsMethods.TargetCreateTarget,
                new { url, browserContextId }, null).ConfigureAwait(false);
 
            string targetId = result.targetId.ToString();
 
            // Activate and attach
            await SendCommand<object>(DevToolsMethods.TargetActivateTarget, new { targetId }, null).ConfigureAwait(false);
            var session = await SendCommand<object>(DevToolsMethods.TargetAttachToTarget,
                new { targetId, flatten = true }, null).ConfigureAwait(false);
 
            string newSessionId = session.sessionId.ToString();
 
            // Build tab queue for this window
            var tabQueue = new ConcurrentQueue<KeyValuePair<string, string>>();
            tabQueue.Enqueue(new KeyValuePair<string, string>(targetId, newSessionId));
 
            // Add new window with its tab queue into _windowSessionsQueue
            _windowSessionsQueue.Enqueue(new WindowSession(browserContextId, tabQueue, 0));
 
            // Update active window index to the newest one
            SetActiveWindowIndex(_windowSessionsQueue.Count - 1);
 
            ((PuppeteerClient)PuppeteerClient)._currentTargetId = targetId;
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG,
                $"Opened new window ContextId [{browserContextId}], TargetId [{targetId}], SessionId [{newSessionId}]",
                this, GPALObjectType.PuppeteerCommunicator);
 
            return targetId;
        }
        // Implementation for "override-referrer"
        public async Task OverrideReferrer(string url, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            await SendCommand<object>(DevToolsMethods.NetworkSetExtraHTTPHeaders, new { headers = new { Referer = url } }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "set-useragent"
        public async Task<dynamic> SetUserAgent(string userAgent, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            return await SendCommand<object>(DevToolsMethods.NetworkSetUserAgentOverride, new { userAgent }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "page-down"
        // PageDown: Scrolls down by one or more pages
        public async Task PageDown(int pagesToScroll = 1, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            for (int i = 0; i < pagesToScroll; i++)
            {
                await ScrollPageAsync("down", pagesToScroll, sessionId).ConfigureAwait(false);
            }
        }
 
        // PageEnd: Scrolls to the bottom of the page
        /// Scrolls to the very bottom of the page.
        /// Implementation for the "page-end" workflow action.
        /// </summary>
        /// <param name="sessionId">CDP session ID; falls back to the current effective session if null.</param>
        /// <returns>Task representing the asynchronous scroll operation.</returns>
        public async Task PageEnd(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            await ScrollToPositionAsync("end", sessionId).ConfigureAwait(false);
        }
 
        // PageTop: Scrolls to the top of the page
        public async Task PageTop(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            await ScrollToPositionAsync("top", sessionId).ConfigureAwait(false);
        }
 
        // PageUp: Scrolls up by one or more pages
        public async Task PageUp(int pagesToScroll = 1, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            for (int i = 0; i < pagesToScroll; i++)
            {
                await ScrollPageAsync("up", pagesToScroll, sessionId).ConfigureAwait(false);
            }
        }
 
        // Implementation for "press-modifier-key"
        public async Task PressModifierKey(int modifierKeys, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            await SendCommand<object>(DevToolsMethods.InputDispatchKeyEvent, new { type = "keyDown", modifiers = modifierKeys }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "previous-tab"
        public async Task<string> PreviousTab(string currentTargetId)
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (windowArray.Length == 0 || _activeWindowIndex >= windowArray.Length)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No active window for PreviousTab", this, GPALObjectType.PuppeteerCommunicator);
                return null;
            }
 
            var session = windowArray[_activeWindowIndex];
            var tabQueue = session.TabQueue;
            var browserContextId = session.BrowserContextId;  // Use stored BrowserContextId
 
            // Poll all targets via CDP to discover unknown pages
            var targetsResponse = await SendCommand<dynamic>(
                DevToolsMethods.TargetGetTargets,
                new { },
                null  // Browser-level command, no sessionId
            ).ConfigureAwait(false);
 
            if (targetsResponse?.targetInfos == null)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "Failed to get targets list in NextTab sync", this, GPALObjectType.PuppeteerCommunicator);
                // Proceed anyway with existing queue
            }
            else
            {
                var knownTargetIds = new HashSet<string>(tabQueue.Select(kv => kv.Key));
 
                foreach (var targetInfo in targetsResponse.targetInfos)
                {
                    string targetId = targetInfo.targetId?.ToString();
                    string type = targetInfo.type?.ToString();
                    string contextId = targetInfo.browserContextId?.ToString();
 
                    if (string.IsNullOrEmpty(targetId) || type != "page" || contextId != browserContextId)
                        continue;
 
                    if (!knownTargetIds.Contains(targetId))
                    {
                        // Add with doNotGetSendSemaphore=true to avoid reentrancy/locking issues
                        await AddTabToQueue(targetId, null, false, true).ConfigureAwait(false);
                        knownTargetIds.Add(targetId);
                    }
                }
            }
 
            var queueArray = tabQueue.ToArray();
            if (queueArray.Length == 0)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No tabs for PreviousTab", this, GPALObjectType.PuppeteerCommunicator);
                return null;
            }
 
            var currentIndex = Array.FindIndex(queueArray, kvp => kvp.Key == currentTargetId);
            if (currentIndex == -1)
            {
                currentIndex = windowArray[_activeWindowIndex].ActiveTabIndex;
            }
 
            var prevIndex = (currentIndex - 1 + queueArray.Length) % queueArray.Length;
            var prevTargetId = queueArray[prevIndex].Key;
            var prevSessionId = queueArray[prevIndex].Value;
 
            // Update ActiveTabIndex in WindowSession
            var windowList = _windowSessionsQueue.ToList();
            windowList[_activeWindowIndex] = new WindowSession(
                windowList[_activeWindowIndex].BrowserContextId,
                tabQueue,
                prevIndex
            );
            _windowSessionsQueue = new ConcurrentQueue<WindowSession>();
            foreach (var w in windowList)
            {
                _windowSessionsQueue.Enqueue(w);
            }
 
            ((PuppeteerClient)PuppeteerClient)._currentTargetId = prevTargetId;
 
            await SendCommand<object>(DevToolsMethods.TargetActivateTarget, new { targetId = prevTargetId }, null).ConfigureAwait(false);
 
            if (await SendCommand<object>(DevToolsMethods.PageEnable, new { }, prevSessionId).ConfigureAwait(false) == null)
            {
                var newSession = await SendCommand<object>(DevToolsMethods.TargetAttachToTarget, new { targetId = prevTargetId, flatten = true }, null).ConfigureAwait(false);
                if (newSession?.sessionId != null)
                {
                    prevSessionId = (string)newSession.sessionId;
                    RemoveTabFromQueue(prevTargetId);
                    await AddTabToQueue(prevTargetId, prevSessionId).ConfigureAwait(false);
                }
                else
                {
                    GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Failed to re-attach PreviousTab ID [{prevTargetId}]", this, GPALObjectType.PuppeteerCommunicator);
                    return null;
                }
                await SendCommand<object>(DevToolsMethods.PageDisable, new { }, prevSessionId).ConfigureAwait(false);
            }
            else
            {
                await SendCommand<object>(DevToolsMethods.PageDisable, new { }, prevSessionId).ConfigureAwait(false);
            }
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"PreviousTab: Switched to index [{prevIndex}], ID [{prevTargetId}], Active window tab queue size [{queueArray.Length}]", this, GPALObjectType.PuppeteerCommunicator);
            return prevTargetId;
        }
 
        // Implementation for "previous-window"
        /// Implementation for the "previous-window" workflow action.
        /// </summary>
        /// <param name="currentTargetId">Target ID of the currently active tab, used to determine which window is currently active.</param>
        /// <returns>Task that resolves to the target ID of the active tab in the previous window, or null if there are no windows or no tabs in the previous window.</returns>
        public async Task<string> PreviousWindow(string currentTargetId)
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (windowArray.Length == 0)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No windows for PreviousWindow", this, GPALObjectType.PuppeteerCommunicator);
                return null;
            }
 
            var currentWindowIndex = -1;
            for (int i = 0; i < windowArray.Length; i++)
            {
                var tabArray = windowArray[i].TabQueue.ToArray();
                if (Array.Exists(tabArray, kvp => kvp.Key == currentTargetId))
                {
                    currentWindowIndex = i;
                    break;
                }
            }
            if (currentWindowIndex == -1)
            {
                currentWindowIndex = _activeWindowIndex;
            }
 
            var prevWindowIndex = (currentWindowIndex - 1 + windowArray.Length) % windowArray.Length;
            SetActiveWindowIndex(prevWindowIndex);
 
            var prevWindowContextId = windowArray[prevWindowIndex].BrowserContextId;
            var prevTabQueue = windowArray[prevWindowIndex].TabQueue;
            var prevTabArray = prevTabQueue.ToArray();
            if (prevTabArray.Length == 0)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"No tabs in previous window for PreviousWindow (context [{prevWindowContextId}])", this, GPALObjectType.PuppeteerCommunicator);
                return null;
            }
 
            var prevTargetId = prevTabArray[windowArray[prevWindowIndex].ActiveTabIndex].Key;
            var prevSessionId = prevTabArray[windowArray[prevWindowIndex].ActiveTabIndex].Value;
 
            await SendCommand<object>(DevToolsMethods.TargetActivateTarget, new { targetId = prevTargetId }, null).ConfigureAwait(false);
 
            if (await SendCommand<object>(DevToolsMethods.PageEnable, new { }, prevSessionId).ConfigureAwait(false) == null)
            {
                var newSession = await SendCommand<object>(DevToolsMethods.TargetAttachToTarget, new { targetId = prevTargetId, flatten = true }, null).ConfigureAwait(false);
                if (newSession?.sessionId != null)
                {
                    prevSessionId = (string)newSession.sessionId;
                    RemoveTabFromQueue(prevTargetId);
                    await AddTabToQueue(prevTargetId, prevSessionId).ConfigureAwait(false);
                }
                else
                {
                    GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Failed to re-attach PreviousWindow tab ID [{prevTargetId}]", this, GPALObjectType.PuppeteerCommunicator);
                    return null;
                }
                await SendCommand<object>(DevToolsMethods.PageDisable, new { }, prevSessionId).ConfigureAwait(false);
            }
            else
            {
                await SendCommand<object>(DevToolsMethods.PageDisable, new { }, prevSessionId).ConfigureAwait(false);
            }
 
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"PreviousWindow: Switched to window index [{prevWindowIndex}], Context [{prevWindowContextId}], Tab ID [{prevTargetId}]", this, GPALObjectType.PuppeteerCommunicator);
            return prevTargetId;
        }        // Implementation for "query-selector"
        public async Task<dynamic> QuerySelector(string css, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            return await QueryByCss(css, sessionId).ConfigureAwait(false);
        }

        internal async Task<long> DocumentMark(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            var doc = await SendCommand<object>(DevToolsMethods.DOMGetDocument, new { depth = 0 }, sessionId).ConfigureAwait(false);
            long mark = null == doc || null == doc.root ? 0 : (long)doc.root.backendNodeId;
 
            return mark;
        }
 
        // Implementation for "query-selectors"
        public async Task<dynamic> QuerySelectors(string css, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            var doc = await SendCommand<object>(DevToolsMethods.DOMGetDocument, new { depth = 0 }, sessionId).ConfigureAwait(false);
 
            return await SendCommand<object>(DevToolsMethods.DOMQuerySelectorAll, new { nodeId = (int)doc.root.nodeId, selector = css }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "refresh"
        public async Task Refresh(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            await SendCommand<object>(DevToolsMethods.PageReload, new { }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "release-modifier-key"
        public async Task ReleaseModifierKey(int modifierKeys, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            await SendCommand<object>(DevToolsMethods.InputDispatchKeyEvent, new { type = "keyUp", modifiers = modifierKeys }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "restore"
        public async Task<bool> Restore(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            var windowId = await GetCurrentWindow(sessionId).ConfigureAwait(false);
            await SendCommand(DevToolsMethods.BrowserSetWindowBounds, new
            {
                windowId = windowId,
                bounds = new { windowState = "normal" }
            }, sessionId).ConfigureAwait(false);
 
            return true;
        }
 
        // Implementation for "middle-click"

        public async Task MiddleClick(string elementId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            List<GPALElement> elems = await EvaluateSelector(elementId, sessionId).ConfigureAwait(false);
            List<dynamic> responses = new List<dynamic>();
 
            foreach (GPALElement elem in elems)
            {
                await ScrollIntoView(elem, sessionId).ConfigureAwait(false);
                await ClickElement(elem, sessionId, responses, ClickType.MiddleClick).ConfigureAwait(false);
            }
        }
 
        // Implementation for "right-click"
        public async Task RightClick(string elementId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            List<GPALElement> elems = await EvaluateSelector(elementId, sessionId).ConfigureAwait(false);
            List<dynamic> responses = new List<dynamic>();
 
            foreach (GPALElement elem in elems)
            {
                await ScrollIntoView(elem, sessionId).ConfigureAwait(false);
                await ClickElement(elem, sessionId, responses, ClickType.RightClick).ConfigureAwait(false);
            }
        }
 
 
        // Implementation for "scroll-element"
        public async Task ScrollElement(string elementId, int hPixels, int vPixels, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new {
                    contextId = CurrentContextId,
                    expression = "document.getElementById('" + elementId + "').scrollBy(" + hPixels + ", " + vPixels + ")" 
                }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "scroll-into-view"
        public async Task<bool> ScrollIntoView(GPALElement element, string sessionId = null)
        {
            int backendNodeId = element.ElementBackendNodeId;
 
            sessionId ??= GetEffectiveSessionId();
 
            try
            {
                if ("GPALElement".Equals(element.TagName))
                    return true;     // it's already in view if it's a matched image
 
                // force layout engine to run before we interact
                if (true == Browser.BrowserSettings.UseHeadless)
                {
                    // force layout
                    await SendCommand<object>(DevToolsMethods.RuntimeEvaluate,
                        new {
                            contextId = CurrentContextId,
                            expression = @"
                                document.body.style.zoom = '100%';  // minor reflow trigger
                                window.dispatchEvent(new Event('resize'));
                                document.documentElement.scrollTop += 1; document.documentElement.scrollTop -= 1;" 
                        }, sessionId).ConfigureAwait(false);
                }
 
                // keep the items from bouncing around if they are already in view
                await SendCommand(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = @"
                            if (!document.querySelector('style[data-gpal-overscroll]')) {
                                const style = document.createElement('style');
                                style.setAttribute('data-gpal-overscroll', 'true');
                                style.textContent = `
                                    html, body {
                                        overscroll-behavior: none !important;
                                        overscroll-behavior-x: none !important;
                                        overscroll-behavior-y: none !important;
                                    }
                                `;
                                (document.head || document.documentElement).appendChild(style);
                            }
                        ",
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
 
                // Try native CDP scroll first (quick & usually sufficient when element is renderable)
                var scrollResult = await SendCommand<object>(
                    DevToolsMethods.DOMScrollIntoViewIfNeeded,
                    new { backendNodeId },
                    sessionId
                ).ConfigureAwait(false);
 
                if (true == Browser.BrowserSettings.UseHeadless)
                    await Task.Delay(250).ConfigureAwait(false); // Give layout/paint time to settle
 
                if (null == scrollResult)
                {
                    // Escape properly for JS string literal (handles quotes, backslashes)
                    var escapedSelector = element.Css.Replace(@"\", @"\\").Replace("'", @"\'");
 
                    var callResult = await SendCommand<dynamic>(
                        DevToolsMethods.RuntimeEvaluate,
                        new
                        {
                            expression = $@"
                            (function() {{
                                const el = document.querySelector(""{escapedSelector}"");
                                if (!el) {{
                                    console.warn('Element not found by selector: {escapedSelector}');
                                    return false;
                                }}
 
                                el.scrollIntoView({{
                                    behavior: 'instant',
                                    block: 'center',
                                    inline: 'center'
                                }});
 
                                // Force reflow/layout
                                void el.getBoundingClientRect();
                                void el.offsetHeight;
 
                                return new Promise(r => requestAnimationFrame(() => r(true)));
                            }})()",
                            awaitPromise = true,
                            contextId = CurrentContextId,
                            returnByValue = true
                        },
                        sessionId
                    ).ConfigureAwait(false);
 
                    //var success = callResult?.result?.value as bool? ?? false;
 
                    //if (!success)
                    //{
                    //    GPAL.PublishSimpleEvent(GPALEventType.WARNING,
                    //        $"JS scroll fallback failedfor element [{element.Css}]",
                    //        this, GPALObjectType.PuppeteerCommunicator);
                    //    // still return true if you want fail-forward, or false if stricter
                    //}
 
                    // Assume recovery succeeded after JS — we don't re-check box model
                    // we don't care about the return value, what else are we going to do, we have nothing to do
                }
 
                return true;
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION,
                    $"ScrollIntoView failed",
                    this, GPALObjectType.PuppeteerCommunicator, ex);
                return false;
            }
        }
        /*
        public async Task<dynamic> ScrollIntoView(int backendNodeId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            try
            {
                // === STEP 0: Let Chromium handle ALL scroll containers ===
                await SendCommand<object>(
                    DevToolsMethods.DOMScrollIntoViewIfNeeded,
                    new { backendNodeId },
                    sessionId
                );
 
                await Task.Delay(75); // allow paint tree to settle
 
                // === STEP 1: Get fresh box model AFTER scrolling ===
                var boxResult = await SendCommand<object>(
                    DevToolsMethods.DOMGetBoxModel,
                    new { backendNodeId },
                    sessionId
                );
 
                if (boxResult?.model?.content == null)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.ERROR,
                        $"No box model for node [{backendNodeId}]",
                        this, GPALObjectType.PuppeteerCommunicator);
                    return new { success = false };
                }
 
                var content = boxResult.model.content;
 
                double elX = content[0];
                double elY = content[1];
                double elW = content[2] - content[0];
                double elH = content[7] - content[1];
 
                // === STEP 2: Get viewport ===
                var vpResult = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = "({ height: window.innerHeight, width: window.innerWidth })",
                    returnByValue = true
                }, sessionId);
 
                int vpH = vpResult?.result?.value?.height ?? 0;
                int vpW = vpResult?.result?.value?.width ?? 0;
 
                if (vpH == 0 || vpW == 0)
                    return new { success = false };
 
                // === STEP 3: Clamp to viewport (now actually meaningful) ===
                double visLeft = Math.Max(elX, 0);
                double visTop = Math.Max(elY, 0);
                double visRight = Math.Min(elX + elW, vpW);
                double visBottom = Math.Min(elY + elH, vpH);
 
                if (visLeft >= visRight || visTop >= visBottom)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING,
                        $"Element [{backendNodeId}] not visible after CDP scroll",
                        this, GPALObjectType.PuppeteerCommunicator);
                    return new { success = false };
                }
 
                int clickX = (int)((visLeft + visRight) / 2);
                int clickY = (int)((visTop + visBottom) / 2);
 
                return new
                {
                    success = true,
                    point = new { x = clickX, y = clickY }
                };
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR,
                    $"ScrollIntoView failed for node [{backendNodeId}]",
                    this, GPALObjectType.PuppeteerCommunicator, ex);
                return new { success = false };
            }
        }
        */
        // Implementation for "scroll-window"
        public async Task ScrollWindow(int hPixels, int vPixels, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            await ScrollWindowByPixelsAsync(hPixels, vPixels, sessionId).ConfigureAwait(false);
            await Task.Delay(150).ConfigureAwait(false);  // NOTE: for headless
        }
 
        // Implementation for "send-key"
        public async Task<dynamic> SendKey(string key, string code, int vkCode, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            try
            {
                // For forms to submit on Enter, Chrome requires the text property to be "\r".
                // Otherwise, printable characters use their literal string value.
                string textPayload = (code == "Enter") ? "\r" : (key.Length == 1 ? key : null);
 
                // 1. Dispatch Key Down
                var keyDownParams = new
                {
                    type = "rawKeyDown",
                    key = key,
                    code = code,
                    windowsVirtualKeyCode = vkCode,
                    nativeVirtualKeyCode = vkCode
                };
                await SendCommand<object>(DevToolsMethods.InputDispatchKeyEvent, keyDownParams, sessionId).ConfigureAwait(false);
 
                // 2. Dispatch Char (Only if the key sequence produces an explicit input character)
                if (textPayload != null)
                {
                    var charParams = new
                    {
                        type = "char",
                        text = textPayload,
                        unmodifiedText = textPayload,
                        key = key,
                        code = code,
                        windowsVirtualKeyCode = vkCode,
                        nativeVirtualKeyCode = vkCode
                    };
                    await SendCommand<object>(DevToolsMethods.InputDispatchKeyEvent, charParams, sessionId).ConfigureAwait(false);
                }
 
                // 3. Dispatch Key Up
                var keyUpParams = new
                {
                    type = "keyUp",
                    key = key,
                    code = code,
                    windowsVirtualKeyCode = vkCode,
                    nativeVirtualKeyCode = vkCode
                };
                await SendCommand<dynamic>(DevToolsMethods.InputDispatchKeyEvent, keyUpParams, sessionId).ConfigureAwait(false);
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"SendKey execution failed for Code [{code}]", this, GPALObjectType.PuppeteerCommunicator, ex);
                return false;
            }
            return true;
        }


        private int GetVirtualKeyCode(string key)
        {
            if (string.IsNullOrEmpty(key))
                return 0;
 
            string k = key.ToLowerInvariant();
 
            switch (k)
            {
                case "enter":
                case "return":
                    return 0x0D;
 
                case "tab":
                    return 0x09;
 
                case "backspace":
                    return 0x08;
 
                case "delete":
                case "del":
                    return 0x2E;
 
                case "escape":
                case "esc":
                    return 0x1B;
 
                case "space":
                    return 0x20;
 
                case "arrowup":
                case "up":
                    return 0x26;
 
                case "arrowdown":
                case "down":
                    return 0x28;
 
                case "arrowleft":
                case "left":
                    return 0x25;
 
                case "arrowright":
                case "right":
                    return 0x27;
 
                case "home":
                    return 0x24;
 
                case "end":
                    return 0x23;
 
                case "pageup":
                    return 0x21;
 
                case "pagedown":
                    return 0x22;
 
                case "insert":
                    return 0x2D;
 
                case "f1": return 0x70;
                case "f2": return 0x71;
                case "f3": return 0x72;
                case "f4": return 0x73;
                case "f5": return 0x74;
                case "f6": return 0x75;
                case "f7": return 0x76;
                case "f8": return 0x77;
                case "f9": return 0x78;
                case "f10": return 0x79;
                case "f11": return 0x7A;
                case "f12": return 0x7B;
 
                default:
                    return 0;   // letters, numbers, symbols etc.
            }
        }
 
        // Implementation for "send-string"
        // NOTE: same as fillin
        public async Task SendString(string text, int delayMs = 0, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            if (0 == delayMs)
                await SendCommand<object>(DevToolsMethods.InputInsertText, new { text }, sessionId).ConfigureAwait(false);
            else
                await DispatchTextCharByChar(text, delayMs, sessionId).ConfigureAwait(false);
        }

        private async Task DispatchTextCharByChar(string text, int delayMs, string sessionId)
        {
            bool first = true;
            foreach (char c in text)
            {
                if (false == first && 0 < delayMs)
                    await Task.Delay(HardwareHelper.GetTypingDelay(delayMs)).ConfigureAwait(false);
 
                string key = c.ToString();
                int vkCode = (int)c; // Basic; improve with real VK map for specials/shifts
 
                await SendCommand(DevToolsMethods.InputDispatchKeyEvent, new
                {
                    type = "keyDown",
                    text = key,                // for printable chars
                    unmodifiedtext = key,
                    key = key,
                    code = GetKeyCode(c),      // e.g. "KeyA" for 'a'/'A'
                    windowsVirtualKeyCode = vkCode,
                    nativeVirtualKeyCode = vkCode
                }, sessionId).ConfigureAwait(false);
 
                await SendCommand(DevToolsMethods.InputDispatchKeyEvent, new
                {
                    type = "keyUp",
                    key = key,
                    code = GetKeyCode(c),
                    windowsVirtualKeyCode = vkCode
                }, sessionId).ConfigureAwait(false);
 
                first = false;
            }
        }
 
        // Implementation for "set-attribute"
        public async Task<dynamic> SetAttribute(int backendNodeId, string attribute, string value, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var nodeId = await GetNodeIdFromBackendNodeId(backendNodeId, sessionId).ConfigureAwait(false);
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Set attribute [{attribute}] to [{value}] on backendNodId [{backendNodeId}]", this, GPALObjectType.PuppeteerCommunicator);
            return await SendCommand<object>(DevToolsMethods.DOMSetAttributeValue, new { nodeId, name = attribute, value }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "set-download-filename"
        public async Task SetDownloadFilename(string downloadPath, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            await SendCommand<object>(DevToolsMethods.PageSetDownloadBehavior, new { behavior = "allow", downloadPath }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "scroll-element"
        public async Task<dynamic> SetRange(string elementId, string rangeValue, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            return await SendCommand<object>(DevToolsMethods.RuntimeEvaluate,
                new
                {
                    contextId = CurrentContextId,
                    expression = $@"var s = document.querySelector('{elementId}'); s.value = {rangeValue}; s.dispatchEvent(new Event('input', {{bubbles: true}})); s.dispatchEvent(new Event('change', {{bubbles: true}}));"
                }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "top-browser"
        public async Task TopBrowser(string sessionId = null)
        {
            // Page.bringToFront is top-level only, so this must never go to an iframe session - once we are inside
            // a cross-origin frame the effective session is that frame's and CDP rejects the command outright.
            // sessionId is deliberately ignored: any session that is not the top-level page target is wrong here
            await SendCommand<object>(DevToolsMethods.PageBringToFront, new { }, GetCurrentSessionId()).ConfigureAwait(false);
        }

        public async Task<bool> SetStorage(
            string storageType,
            string sessionId,
            string domain,
            string key,
            string data,
            string storeName = null,
            string path = null)
        {
            bool retVal = false;
            sessionId ??= GetEffectiveSessionId();
 
            try
            {
                switch (storageType)
                {
                    case "cookie":
                        {
                            IDictionary<string, object> cookieToSet;
 
                            path ??= "/";
                            domain ??= ""; // or handle wildcard logic as before
 
                            // 1. Get current cookies via CDP
                            dynamic cookiesResp = await GetStorage(storageType, sessionId, domain, storeName, path, key).ConfigureAwait(false);
 
                            // 2. Find the existing cookie (exact match on name + domain + path)
                            dynamic existing = null;
 
                            if (cookiesResp != null)
                            {
                                var cookies = JsonConvert.DeserializeObject<List<dynamic>>(cookiesResp) ?? new List<dynamic>();
                                foreach (dynamic c in cookies)
                                {
                                    string cDomain = ((dynamic)c).Domain ?? "";
                                    string cPath = ((dynamic)c).Path ?? "/";
                                    string cName = ((dynamic)c).Key ?? "";
 
                                    if (cName == key &&
                                        UrlHelper.CookieDomainMatches(cDomain, domain) &&
                                        cPath == path)
                                    {
                                        existing = c;
 
                                        cookieToSet = new System.Dynamic.ExpandoObject() as IDictionary<string, object>;
 
                                        cookieToSet["name"] = key;
                                        cookieToSet["value"] = data;
                                        cookieToSet["domain"] = ((dynamic)existing)?.Domain?.ToString();
                                        cookieToSet["path"] = path;
 
                                        cookieToSet["expires"] = ((dynamic)existing)?.Expires != null
                                                                 ? (double)existing.Expires
                                                                 : DateTimeOffset.UtcNow.ToUnixTimeSeconds() + (180L * 24 * 60 * 60); // ~6 months
 
                                        cookieToSet["secure"] = ((dynamic)existing)?.Secure ?? true;
                                        cookieToSet["httpOnly"] = ((dynamic)existing)?.HttpOnly ?? true;
                                        cookieToSet["sameSite"] = ((dynamic)existing)?.SameSite?.ToString() ?? "None";
 
                                        cookieToSet["session"] = ((dynamic)existing)?.Session ?? false;
                                        cookieToSet["priority"] = ((dynamic)existing)?.Priority?.ToString() ?? "Medium";
 
                                        cookieToSet["sourceScheme"] = ((dynamic)existing)?.SourceScheme?.ToString() ?? "Secure";
                                        cookieToSet["sourcePort"] = ((dynamic)existing)?.SourcePort ?? 443;
 
                                        // Only add partitionKey if it actually exists and is not null
                                        if (((dynamic)existing)?.PartitionKey != null)
                                        {
                                            cookieToSet["partitionKey"] = existing.PartitionKey;   // keep the original object
                                        }
 
                                        // 4. Set the cookie
                                        await SendCommand<dynamic>(DevToolsMethods.StorageSetCookies,
                                            new { cookies = new[] { cookieToSet } },
                                            sessionId).ConfigureAwait(false);
                                    }
                                }
                            }
                            else
                            {
                                // 3. Build the cookie to set (merge existing + supplied values)
                                cookieToSet = new System.Dynamic.ExpandoObject() as IDictionary<string, object>;
 
                                cookieToSet["name"] = key;
                                cookieToSet["value"] = data;
                                cookieToSet["domain"] = ((dynamic)existing)?.Domain?.ToString();
                                cookieToSet["path"] = path;
 
                                cookieToSet["expires"] = ((dynamic)existing)?.Expires != null
                                                         ? (double)existing.Expires
                                                         : DateTimeOffset.UtcNow.ToUnixTimeSeconds() + (180L * 24 * 60 * 60); // ~6 months
 
                                cookieToSet["secure"] = ((dynamic)existing)?.Secure ?? true;
                                cookieToSet["httpOnly"] = ((dynamic)existing)?.HttpOnly ?? true;
                                cookieToSet["sameSite"] = ((dynamic)existing)?.SameSite?.ToString() ?? "None";
 
                                cookieToSet["session"] = ((dynamic)existing)?.Session ?? false;
                                cookieToSet["priority"] = ((dynamic)existing)?.Priority?.ToString() ?? "Medium";
 
                                cookieToSet["sourceScheme"] = ((dynamic)existing)?.SourceScheme?.ToString() ?? "Secure";
                                cookieToSet["sourcePort"] = ((dynamic)existing)?.SourcePort ?? 443;
 
                                // Only add partitionKey if it actually exists and is not null
                                if (((dynamic)existing)?.PartitionKey != null)
                                {
                                    cookieToSet["partitionKey"] = existing.PartitionKey;   // keep the original object
                                }
 
                                // 4. Set the cookie
                                await SendCommand<dynamic>(DevToolsMethods.StorageSetCookies,
                                    new { cookies = new[] { cookieToSet } },
                                    sessionId).ConfigureAwait(false);
                            }
 
                            // Optional: return the cookie we just set (or the old list)
                            //resultJson = JsonConvert.SerializeObject(new[] { cookieToSet });
                            retVal = true;
                            break;
                        }
 
                    case "localStorage":
                    case "sessionStorage":
                        string jsStorage = $@"{storageType}.setItem('{EscapeJsString(key)}','{EscapeJsString(data)}');";
                        await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, 
                            new { 
                                expression = jsStorage, 
                                awaitPromise = false,
                                contextId = CurrentContextId,
                                returnByValue = true 
                            }, sessionId).ConfigureAwait(false);
                        retVal = true;
                        break;
 
                    case "indexedDb":
                        // Runtime.evaluate has no arguments array and injects no callback, so taking one the way
                        // selenium's executeAsyncScript hands it over threw a ReferenceError before the script ran.
                        // a promise is what awaitPromise on the evaluate call waits for
                        string js = $@"
                                    new Promise((callback) => {{
 
                                    (function() {{
                                        const dbName = '{EscapeJsString(path)}';
                                        const storeName = '{EscapeJsString(storeName)}';
                                        const inputKey = '{EscapeJsString(key)}';
                                        let rawValue = '{EscapeJsString(data)}';
 
                                        function resolve(val) {{
                                            callback(val);
                                        }}
 
                                        function fail(msg, err, db) {{
                                            console.error(msg, err?.name || err || '');
                                            try {{ db?.close(); }} catch {{ }}
                                            resolve(false);
                                        }}
 
                                        function parseValue(v) {{
                                            try {{
                                                return JSON.parse(v);
                                            }} catch {{
                                                return v;
                                            }}
                                        }}
 
                                        function isValidKey(k) {{
                                            if (k === undefined) return false;
                                            if (typeof k === 'string' || typeof k === 'number') return true;
                                            if (k instanceof Date) return true;
                                            if (Array.isArray(k)) return true;
                                            return false;
                                        }}
 
                                        function ensureInlineKey(value, keyPath, key, autoIncrement) {{
                                            if (keyPath === null) return {{ value, usedKey: key }};
 
                                            if (typeof value !== 'object' || value === null) {{
                                                if (keyPath && key !== undefined) {{
                                                    const wrapped = {{}};
 
                                                    if (typeof keyPath === 'string') {{
                                                        wrapped[keyPath] = key;
                                                    }} else if (Array.isArray(keyPath)) {{
                                                        if (!Array.isArray(key)) {{
                                                            throw new Error('Compound key requires array key');
                                                        }}
                                                        for (let i = 0; i < keyPath.length; i++) {{
                                                            wrapped[keyPath[i]] = key[i];
                                                        }}
                                                    }}
 
                                                    wrapped.value = value;
                                                    return {{ value: wrapped, usedKey: undefined }};
                                                }}
 
                                                if (autoIncrement) {{
                                                    return {{ value, usedKey: undefined }};
                                                }}
 
                                                throw new Error('Inline keyPath requires object value');
                                            }}
 
                                            if (typeof keyPath === 'string') {{
                                                if (!(keyPath in value)) {{
                                                    if (key !== undefined) {{
                                                        value[keyPath] = key;
                                                    }} else if (!autoIncrement) {{
                                                        throw new Error('Missing required inline keyPath property');
                                                    }}
                                                }}
                                            }} else if (Array.isArray(keyPath)) {{
                                                for (let i = 0; i < keyPath.length; i++) {{
                                                    const kp = keyPath[i];
                                                    if (!(kp in value)) {{
                                                        if (Array.isArray(key) && key[i] !== undefined) {{
                                                            value[kp] = key[i];
                                                        }} else if (!autoIncrement) {{
                                                            throw new Error('Missing compound keyPath property: ' + kp);
                                                        }}
                                                    }}
                                                }}
                                            }}
 
                                            return {{ value, usedKey: undefined }};
                                        }}
 
                                        const openReq = indexedDB.open(dbName);
 
                                        openReq.onerror = () => {{
                                            fail('Failed to open database', openReq.error);
                                        }};
 
                                        openReq.onsuccess = () => {{
                                            const db = openReq.result;
 
                                            let tx;
                                            try {{
                                                tx = db.transaction(storeName, 'readwrite');
                                            }} catch (e) {{
                                                fail('Transaction creation failed', e, db);
                                                return;
                                            }}
 
                                            const store = tx.objectStore(storeName);
 
                                            let value = parseValue(rawValue);
                                            let key = inputKey;
 
                                            if (key === '') key = undefined;
 
                                            if (key !== undefined && !isValidKey(key)) {{
                                                fail('Invalid key type', key, db);
                                                return;
                                            }}
 
                                            let finalValue, finalKey;
 
                                            try {{
                                                const result = ensureInlineKey(
                                                    value,
                                                    store.keyPath,
                                                    key,
                                                    store.autoIncrement
                                                );
 
                                                finalValue = result.value;
                                                finalKey = result.usedKey;
                                            }} catch (e) {{
                                                fail('Key handling failed', e, db);
                                                return;
                                            }}
 
                                            let putReq;
 
                                            try {{
                                                if (store.keyPath === null) {{
                                                    if (finalKey === undefined && !store.autoIncrement) {{
                                                        fail('Missing key for out-of-line store', null, db);
                                                        return;
                                                    }}
                                                    putReq = store.put(finalValue, finalKey);
                                                }} else {{
                                                    putReq = store.put(finalValue);
                                                }}
                                            }} catch (e) {{
                                                fail('Put setup error', e, db);
                                                return;
                                            }}
 
                                            // wait for transaction complete (not just put)
                                            tx.oncomplete = () => {{
                                                try {{ db.close(); }} catch {{ }}
                                                resolve(true);
                                            }};
 
                                            tx.onerror = (event) => {{
                                                fail('Transaction error', event.target.error, db);
                                            }};
 
                                            tx.onabort = (event) => {{
                                                fail('Transaction aborted', event.target.error, db);
                                            }};
                                        }};
                                    }})();
 
                                    }});
                                    ";
 
                        string indexedDbSaid = SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                        {
                            expression = js,
                            awaitPromise = true,
                            contextId = CurrentContextId,
                            returnByValue = true
                        }, sessionId).GetAwaiter().GetResult()?.ToString();
 
                        retVal = true == indexedDbSaid?.Contains("true");
 
                        // the script says why it could not write, and reducing its answer to a bool threw that
                        // away, so a store that refused the record looked the same as one that took it
                        if (false == retVal)
                            GPAL.PublishSimpleEvent(GPALEventType.WARNING,
                                $"IndexedDB [{path}] store [{storeName}] did not take key [{key}], the page answered [{indexedDbSaid}]",
                                null, GPALObjectType.None);
 
                        break;
 
                    case "cache":
                        string cacheName = EscapeJsString(storeName);
                        string requestUrl = EscapeJsString(key);   // Key = the cache key (URL)
 
                        js = $@"
                                (async () => {{
                                    try {{
                                        const cache = await caches.open('{cacheName}');
                
                                        const request = new Request('{requestUrl}', {{
                                            method: 'GET'
                                        }});
 
                                        const response = new Response('{EscapeJsString(data)}', {{
                                            status: 200,
                                            statusText: 'OK',
                                            headers: {{
                                                'Content-Type': 'text/plain;charset=utf-8',
                                                'Cache-Control': 'max-age=31536000'   // or make this configurable
                                            }}
                                        }});
 
                                        await cache.put(request, response);
                                        return {{ success: true, cacheName: '{cacheName}', key: '{requestUrl}' }};
                                    }} catch (err) {{
                                        console.error('Cache set failed:', err);
                                        return {{ success: false, error: err.message }};
                                    }}
                                }})();
                            ";
 
                        var evalResult = await SendCommand<dynamic>(
                            DevToolsMethods.RuntimeEvaluate,
                            new
                            {
                                expression = js,
                                awaitPromise = true,
                                contextId = CurrentContextId,
                                returnByValue = true
                            },
                            sessionId).ConfigureAwait(false);
 
                        // Check result
                        retVal = evalResult?.result?.value?.success == true;
                        break;
 
                    default:
                        GPAL.PublishSimpleEvent(
                            GPALEventType.ERROR,
                            $"Unsupported storage type: [{storageType}]",
                            this,
                            GPALObjectType.PuppeteerCommunicator);
                        break;
                }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(
                    GPALEventType.EXCEPTION,
                    $"SetStorage failed for [{storageType}] domain=[{domain}] storeName=[{storeName}] path=[{path}] key=[{key}]",
                    this,
                    GPALObjectType.PuppeteerCommunicator,
                    ex);
            }
 
            return retVal;
        }
 
        // Implementation for "set-value-from-element"
        public async Task<dynamic> SetValueFromElement(string srcCss, string destCss, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            return await SendCommand<object>(DevToolsMethods.RuntimeEvaluate,
                new
                {
                    contextId = CurrentContextId,
                    expression = $@"var s = document.querySelector('{srcCss}'); var d = document.querySelector('{destCss}'); d.value = s.value; d.dispatchEvent(new Event('input', {{bubbles: true}})); d.dispatchEvent(new Event('change', {{bubbles: true}}));"
                }, sessionId).ConfigureAwait(false);
        }
 
        // Implementation for "stealth-override-referrer"
        public async Task SetGoogleReferrer(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            await SendCommand<object>(DevToolsMethods.NetworkSetExtraHTTPHeaders, new { headers = new { Referer = "https://www.google.com" } }, sessionId).ConfigureAwait(false);
        }
 
 
        // Implementation for "switch-to-default-content"
        public Task SwitchToDefaultContent(string sessionId = null)
        {
            // dropping the frame state is the whole of the work, and none of it goes over the wire. window
            // ordering is not frame context and belongs to TopBrowser, so nothing is sent from here
            CurrentContextId = null;
            CurrentFrameId = null;
            CurrentFrameSessionId = null;
            CurrentRootObjectId = null;
 
            return Task.CompletedTask;
        }

        /// <summary>
        /// Switches the active tab/window to the one identified by a tab index or page URL, activating the corresponding
        /// CDP target and updating the active window/tab indices.
        /// </summary>
        /// <param name="tabIdOrUrl">Either an <see cref="int"/> index into the current tab queue, or a <see cref="string"/> URL to search for among open tabs.</param>
        /// <param name="sessionId">Session ID used when looking up the target by URL, or null to use the effective session.</param>
        /// <returns>A Task that resolves to the targetId of the activated tab, or null if no matching target was found.</returns>
        public async Task<string> GoToWindow(object tabIdOrUrl, string sessionId = null)
        {
            string targetId = null;
 
            if (tabIdOrUrl is int tabId)
            {
                var queueArray = CurrentSessions.ToArray();
                if (tabId >= 0 && tabId < queueArray.Length)
                {
                    targetId = queueArray[tabId].Key;
                    // Update active tab index
                    SetActiveTabIndex(tabId);
                }
            }
            else if (tabIdOrUrl is string url && !string.IsNullOrWhiteSpace(url))
            {
                targetId = await GetTargetTabIdByUrl(url, sessionId).ConfigureAwait(false);
                if (!string.IsNullOrEmpty(targetId))
                {
                    // Find and set active window and tab
                    int windowIndex = GetCurrentWindowIndex(targetId);
                    if (windowIndex >= 0)
                    {
                        SetActiveWindowIndex(windowIndex);
                        var windowArray = _windowSessionsQueue.ToArray();
                        var tabQueue = windowArray[windowIndex].TabQueue.ToArray();
                        int tabIndex = Array.FindIndex(tabQueue, kvp => kvp.Key == targetId);
                        if (tabIndex >= 0)
                        {
                            SetActiveTabIndex(tabIndex);
                        }
                    }
                }
            }
 
            if (string.IsNullOrEmpty(targetId))
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"No target found for tabIdOrUrl [{tabIdOrUrl}]", this, GPALObjectType.PuppeteerCommunicator);
                return null;
            }
 
            await SendCommand<object>(DevToolsMethods.TargetActivateTarget, new { targetId }, null).ConfigureAwait(false);
            ((PuppeteerClient)PuppeteerClient)._currentTargetId = targetId;
            return targetId;
        }
        // Implementation for "window-inner-height"
        public async Task<int> WindowInnerHeight(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new { 
                    expression = "window.innerHeight",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
            return (int)result.value;
        }
 
        // Implementation for "window-inner-width"
        public async Task<int> WindowInnerWidth(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new { 
                    expression = "window.innerWidth",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
            return (int)result.value;
        }
 
        // Implementation for "window-outer-height"

        public async Task<int> WindowOuterHeight(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new { 
                    expression = "window.outerHeight",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
            return (int)result.value;
        }
 
        // Implementation for "window-outer-width"
        public async Task<int> WindowOuterWidth(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new { 
                    expression = "window.outerWidth",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
            return (int)result.value;
        }
 
        // Implementation for "fetch"
        public async Task<string> Fetch(string url, string method = null, string body = null, string contentType = null, string[] headers = null, bool asBytes = false, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate,
                new
                {
                    expression = $@"
                        (async () => {{
                            {BrowserHelper.FetchSetupScript(url, method, body, contentType, headers, asBytes)}
 
                            try {{
                                var response = await fetch(target.toString(), options);
                                return await gpalEnvelope(response);
                            }} catch (error) {{
                                return gpalFailure(error);
                            }}
                        }})()",
                    contextId = CurrentContextId,
                    returnByValue = true,
                    awaitPromise = true
                }, sessionId).ConfigureAwait(false);
 
            // the response comes back deserialized by Newtonsoft, so it is indexed as a JObject rather than
            // reached through dynamic member access, which does not resolve to the string.
            // read step by step: a CDP error answers no "result" at all, and indexing straight through that
            // threw a null reference instead of saying what came back
            Newtonsoft.Json.Linq.JObject evaluated = result as Newtonsoft.Json.Linq.JObject;
            Newtonsoft.Json.Linq.JToken value = evaluated?["result"]?["value"];
 
            if (null == value)
                // SerializeObject, not JToken.ToString(Formatting), whose overload binds against whichever
                // Newtonsoft the host app loaded and throws MissingMethodException when that is not ours
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"The page did not answer the fetch. Runtime.evaluate returned [{(null == evaluated ? "nothing" : Newtonsoft.Json.JsonConvert.SerializeObject(evaluated))}]", null, GPALObjectType.PuppeteerCommunicator);
 
            return value?.ToString();
        }
 
        // Implementation for "window-page-xoffset"
        public async Task<int> WindowPageOffsetX(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new { 
                    expression = "window.pageXOffset",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
            return (int)result.value;
        }
 
        // Implementation for "window-page-yoffset"
        public async Task<int> WindowPageOffsetY(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new { 
                    expression = "window.pageYOffset",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
            return (int)result.value;
        }
 
        // Implementation for "window-screen-left"
        public async Task<int> WindowScreenLeft(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new { 
                    expression = "window.screenLeft",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
            return (int)result.value;
        }
 
        // Implementation for "window-screen-top"
        public async Task<int> WindowScreenTop(string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var result = await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, 
                new { 
                    expression = "window.screenTop",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
            return (int)result.value;
        }
 
        // Helper for getting nodeId by elementId
        private async Task<int> GetNodeIdFromBackendNodeId(int backendNodeId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            // Ensure we have a DOM loaded
            await SendCommand<dynamic>(DevToolsMethods.DOMGetDocument, new { depth = 1 }, sessionId).ConfigureAwait(false);
 
            // Push the backend node ID to get a current, valid node ID
            var result = await SendCommand<dynamic>(
                DevToolsMethods.DOMPushNodesByBackendIdsToFrontend,
                new { backendNodeIds = new[] { backendNodeId } },
                sessionId
            ).ConfigureAwait(false);
 
            // The result has nodeIds as an array of integers
            if (result?.nodeIds is Newtonsoft.Json.Linq.JArray nodeIdsArray && nodeIdsArray.Count > 0)
            {
                return nodeIdsArray[0].Value<int>();
            }
 
            return 0;
        }

        public async Task<string> GetObjectIdFromBackendNodeId(int backendNodeId, string sessionId = null, long? contextId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            // Use iframe session if we're currently in an iframe
            string effectiveSessionId = !string.IsNullOrEmpty(CurrentFrameSessionId)
                ? CurrentFrameSessionId
                : sessionId;
 
            // Use provided contextId or fall back to current iframe context
            long? effectiveContextId = contextId ?? CurrentContextId;
 
            try
            {
                // Step 1: Resolve backendNodeId > nodeId (in the correct session)
                var resolveNodeParams = new Dictionary<string, object>
                {
                    ["backendNodeId"] = backendNodeId
                };
 
                // Add contextId only if we have one (important for iframes)
                if (effectiveContextId.HasValue)
                {
                    resolveNodeParams["executionContextId"] = effectiveContextId.Value;
                }
 
                var resolveResult = await SendCommand<dynamic>(DevToolsMethods.DOMResolveNode, resolveNodeParams, effectiveSessionId).ConfigureAwait(false);
 
                string objectId = resolveResult?.@object?.objectId?.ToString();
 
                if (!string.IsNullOrEmpty(objectId))
                    return objectId;
 
                // Fallback: Try without executionContextId
                var fallbackResult = await SendCommand<dynamic>(DevToolsMethods.DOMResolveNode, new
                {
                    backendNodeId = backendNodeId
                }, effectiveSessionId).ConfigureAwait(false);
 
                return fallbackResult?.@object?.objectId?.ToString() ?? string.Empty;
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG,
                    $"GetObjectIdFromBackendNodeId failed for backendNodeId [{backendNodeId}]",
                    this, GPALObjectType.PuppeteerCommunicator, ex);
 
                return string.Empty;
            }
        }
 
        // Helper for getting element X coordinate
        private async Task<int> GetElementRandomCenterX(int backendNodeId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var rect = await GetBoundingClientRect(backendNodeId, sessionId).ConfigureAwait(false);
            return (int)rect.X + rect.Width / new Random().Next(2, 3);
        }
 
        // Helper for getting element Y coordinate
        private async Task<int> GetElementRandomCenterY(int backendNodeId, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
            var rect = await GetBoundingClientRect(backendNodeId, sessionId).ConfigureAwait(false);
            return (int)rect.Y + rect.Width / new Random().Next(2, 3);
        }
        // get the json protocol to dynamically build a list of extraction variable for sendcommand to return useful data
        internal string GetProtocolJSON()
        {
            using var http = new System.Net.Http.HttpClient();
            var json = http.GetStringAsync($"{_puppeteerUrl}/json/protocol").Result;
            return Newtonsoft.Json.Linq.JObject.Parse(json).ToString();
        }
        internal string GetActiveWindowId()
        {
            var windows = _windowSessionsQueue.ToArray();
            if (_activeWindowIndex < 0 || _activeWindowIndex >= windows.Length)
                return null;
            return windows[_activeWindowIndex].BrowserContextId;
        }
        // Get active window's tab queue (embedded in windows queue)
        private ConcurrentQueue<KeyValuePair<string, string>> GetActiveWindowTabQueue()
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (windowArray.Length == 0 || _activeWindowIndex >= windowArray.Length) return null;
            return windowArray[_activeWindowIndex].TabQueue;
        }

        public string GetEffectiveSessionId()
        {
            return !string.IsNullOrEmpty(CurrentFrameSessionId)
                ? CurrentFrameSessionId
                : GetCurrentSessionId();
        }
        
        // Get current sessionId (active window -> active tab)
        internal void ClearCurrentSessionId()
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (0 == windowArray.Length || _activeWindowIndex >= windowArray.Length)
                return;
 
            var window = windowArray[_activeWindowIndex];
            var tabArray = window.TabQueue.ToArray();
            if (0 == tabArray.Length || window.ActiveTabIndex >= tabArray.Length)
                return;
 
            string targetId = tabArray[window.ActiveTabIndex].Key;
            var newQueue = new ConcurrentQueue<KeyValuePair<string, string>>();
 
            foreach (var kvp in tabArray)
                newQueue.Enqueue(kvp.Key == targetId ? new KeyValuePair<string, string>(kvp.Key, null) : kvp);
 
            window.TabQueue = newQueue;
        }
        public string GetCurrentSessionId()
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (windowArray.Length == 0 || _activeWindowIndex >= windowArray.Length) return null;
 
            var window = windowArray[_activeWindowIndex];
            var tabQueue = window.TabQueue;
            var tabArray = tabQueue.ToArray();
            var activeTabIndex = window.ActiveTabIndex;
            if (tabArray.Length == 0 || activeTabIndex >= tabArray.Length) return null;
 
            var targetId = tabArray[activeTabIndex].Key;
            var sessionId = tabArray[activeTabIndex].Value;
 
            if (sessionId == null)
            {
                var attachResult = SendCommand<dynamic>(DevToolsMethods.TargetAttachToTarget, new
                {
                    targetId,
                    flatten = true
                }, null).GetAwaiter().GetResult();
 
                string newSessionId = attachResult.sessionId;
 
                // rebuild queue with updated value
                var newQueue = new ConcurrentQueue<KeyValuePair<string, string>>();
                foreach (var kvp in tabArray)
                    newQueue.Enqueue(kvp.Key == targetId
                        ? new KeyValuePair<string, string>(kvp.Key, newSessionId)
                        : kvp);
 
                window.TabQueue = newQueue;
                sessionId = newSessionId;
            }
 
            return sessionId;
        }
 
        // Get current targetId (active window -> active tab)
        public string GetCurrentTargetId()
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (windowArray.Length == 0 || _activeWindowIndex >= windowArray.Length) return null;
            var tabQueue = windowArray[_activeWindowIndex].TabQueue;
            var tabArray = tabQueue.ToArray();
            var activeTabIndex = windowArray[_activeWindowIndex].ActiveTabIndex;
            if (tabArray.Length == 0 || activeTabIndex >= tabArray.Length) return null;
            return tabArray[activeTabIndex].Key;
        }
        // Get current window targetId (active window)
        public string GetCurrentWindowTargetId()
        {
            var windowArray = _windowSessionsQueue.ToArray();
 
            return windowArray[_activeWindowIndex].BrowserContextId;
        }
        // Add tab to active window's embedded tab queue, set as active tab
        internal async Task AddTabToQueue(string targetId, string sessionId, bool isActive = true, bool doNotGetSendSemaphore = false)
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (windowArray.Length == 0 || _activeWindowIndex >= windowArray.Length)
            {
                // TODO: this needs to be pushed onto a queue, then the next time send 
                var targets = await SendCommand<object>(DevToolsMethods.TargetGetTargets, new { }, null, 3, doNotGetSendSemaphore).ConfigureAwait(false);
                var target = ((IEnumerable<dynamic>)targets.targetInfos)
                    .FirstOrDefault(t => t.targetId == targetId && t.type == "page");
 
                if (target == null)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Target ID [{targetId}] not found in CDP", this, GPALObjectType.PuppeteerCommunicator);
                    return;
                }
 
                string browserContextId = target.browserContextId?.ToString() ?? "";
 
                var newTabQueue = new ConcurrentQueue<KeyValuePair<string, string>>();
                newTabQueue.Enqueue(new KeyValuePair<string, string>(targetId, sessionId));
                _windowSessionsQueue.Enqueue(new WindowSession(browserContextId, newTabQueue, 0));
                _activeWindowIndex = 0;
                ((PuppeteerClient)PuppeteerClient)._currentTargetId = targetId;
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Created window with browserContextId [{browserContextId}], added tab ID [{targetId}], Active window [0], tab [0]", this, GPALObjectType.PuppeteerCommunicator);
                return;
            }
 
            var tabQueue = windowArray[_activeWindowIndex].TabQueue;
            tabQueue.Enqueue(new KeyValuePair<string, string>(targetId, sessionId));
 
            // Update ActiveTabIndex in the WindowSession
            var windowList = _windowSessionsQueue.ToList();
            windowList[_activeWindowIndex] = new WindowSession(
                windowList[_activeWindowIndex].BrowserContextId,
                tabQueue,
                true == isActive ? tabQueue.Count - 1 : windowList[_activeWindowIndex].ActiveTabIndex   // we do not know if the new tab is active, just that it is being added
            );
            _windowSessionsQueue = new ConcurrentQueue<WindowSession>();
            foreach (var w in windowList)
            {
                _windowSessionsQueue.Enqueue(w);
            }
            var newTabIdx = tabQueue.Count - 1;
 
            if (true == isActive)
                ((PuppeteerClient)PuppeteerClient)._currentTargetId = targetId;
 
            // said separately, because the tab that was added and the tab that is active are only the same when
            // the tab was added as active. printing the added position as "Active tab index" read as a switch
            // that had not happened
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Added tab to active window at index [{newTabIdx}], ID [{targetId}], Tab queue size [{tabQueue.Count}], active tab is now index [{windowList[_activeWindowIndex].ActiveTabIndex}]", this, GPALObjectType.PuppeteerCommunicator);
        }        // Set active tab index in active window's embedded tab queue
        internal void SetActiveTabIndex(int index)
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (windowArray.Length == 0 || _activeWindowIndex >= windowArray.Length)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No active window for SetActiveTabIndex", this, GPALObjectType.PuppeteerCommunicator);
                return;
            }
            var tabQueue = windowArray[_activeWindowIndex].TabQueue;
            var tabArray = tabQueue.ToArray();
            index = index % tabArray.Length;
            if (index < 0) index += tabArray.Length;
 
            // Update ActiveTabIndex in the WindowSession
            var windowList = _windowSessionsQueue.ToList();
            windowList[_activeWindowIndex] = new WindowSession(
                windowList[_activeWindowIndex].BrowserContextId,
                windowList[_activeWindowIndex].TabQueue,
                index
            );
            _windowSessionsQueue = new ConcurrentQueue<WindowSession>();
            foreach (var w in windowList)
            {
                _windowSessionsQueue.Enqueue(w);
            }
 
            ((PuppeteerClient)PuppeteerClient)._currentTargetId = tabArray[index].Key;
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Set active tab index [{index}] in active window, ID [{tabArray[index].Key}]", this, GPALObjectType.PuppeteerCommunicator);
        }
        // Remove tab from active window's embedded tab queue by targetId
        internal bool RemoveTabFromQueue(string targetId)
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (windowArray.Length == 0 || _activeWindowIndex >= windowArray.Length)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"No active window for RemoveTabFromQueue [{targetId}]", this, GPALObjectType.PuppeteerCommunicator);
                return false;
            }
 
            var tabQueue = windowArray[_activeWindowIndex].TabQueue;
            var queueList = tabQueue.ToList();
            var indexToRemove = queueList.FindIndex(kvp => kvp.Key == targetId);
            if (indexToRemove == -1)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Tab ID [{targetId}] not found in active window queue", this, GPALObjectType.PuppeteerCommunicator);
                return false;
            }
 
            queueList.RemoveAt(indexToRemove);
            var newTabQueue = new ConcurrentQueue<KeyValuePair<string, string>>();
            foreach (var kvp in queueList)
            {
                newTabQueue.Enqueue(kvp);
            }
 
            // Update ActiveTabIndex in WindowSession
            var newActiveTabIndex = windowArray[_activeWindowIndex].ActiveTabIndex;
            if (newTabQueue.IsEmpty)
            {
                newActiveTabIndex = 0;
            }
            else if (newActiveTabIndex > indexToRemove)
            {
                newActiveTabIndex--;
            }
            else if (newActiveTabIndex == indexToRemove)
            {
                newActiveTabIndex = Math.Max(0, newActiveTabIndex - 1);
            }
 
            var windowList = _windowSessionsQueue.ToList();
            windowList[_activeWindowIndex] = new WindowSession(
                windowList[_activeWindowIndex].BrowserContextId,
                newTabQueue,
                newActiveTabIndex
            );
            _windowSessionsQueue = new ConcurrentQueue<WindowSession>();
            foreach (var w in windowList)
            {
                _windowSessionsQueue.Enqueue(w);
            }
 
            ((PuppeteerClient)PuppeteerClient)._currentTargetId = newTabQueue.IsEmpty ? null : newTabQueue.ToArray()[newActiveTabIndex].Key;
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Removed tab ID [{targetId}] from active window, Active tab index now [{newActiveTabIndex}], Tab queue size [{newTabQueue.Count}]", this, GPALObjectType.PuppeteerCommunicator);
            return true;
        }

        public int GetCurrentWindowIndex(string targetId)
        {
            var windows = _windowSessionsQueue.ToArray(); // assuming you track sessions per window
            for (int i = 0; i < windows.Length; i++)
            {
                foreach (var tab in windows[i].TabQueue)
                    if (tab.Key == targetId)
                        return i;
            }
            return -1;
        }

        /// Sets the active window index, wrapping the index into range, and updates the current target ID
        /// to the active tab of the newly active window.
        /// </summary>
        /// <param name="index">The desired window index, wrapped (modulo) into the valid range of the window queue.</param>
        internal void SetActiveWindowIndex(int index)
        {
            var windowArray = _windowSessionsQueue.ToArray();
            if (windowArray.Length == 0)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "No windows for SetActiveWindowIndex", this, GPALObjectType.PuppeteerCommunicator);
                return;
            }
            index = index % windowArray.Length;
            if (index < 0) index += windowArray.Length;
            _activeWindowIndex = index;
 
            ((PuppeteerClient)PuppeteerClient)._currentTargetId = GetCurrentTargetId();
            GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Set active window index [{_activeWindowIndex}], Active tab index [{windowArray[_activeWindowIndex].ActiveTabIndex}], Target ID [{((PuppeteerClient)PuppeteerClient)._currentTargetId}]", this, GPALObjectType.PuppeteerCommunicator);
        }
        // Remove window from queue by browserContextId or targetId
        internal bool RemoveWindowFromQueue(string browserContextId = null, string targetId = null)
        {
            var windowArray = _windowSessionsQueue.ToArray();
            var indexToRemove = -1;
 
            if (browserContextId != null)
            {
                indexToRemove = Array.FindIndex(windowArray, w => w.BrowserContextId == browserContextId);
            }
            else if (targetId != null)
            {
                for (int i = 0; i < windowArray.Length; i++)
                {
                    var tabArray = windowArray[i].TabQueue.ToArray();
                    if (Array.Exists(tabArray, kvp => kvp.Key == targetId))
                    {
                        indexToRemove = i;
                        browserContextId = windowArray[i].BrowserContextId;
                        break;
                    }
                }
            }
 
            if (indexToRemove == -1)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Window/Context ID [{browserContextId ?? targetId}] not found", this, GPALObjectType.PuppeteerCommunicator);
                return false;
            }
 
            var queueList = _windowSessionsQueue.ToList();
            queueList.RemoveAt(indexToRemove);
 
            _windowSessionsQueue = new ConcurrentQueue<WindowSession>();
            foreach (var w in queueList)
            {
                _windowSessionsQueue.Enqueue(w);
            }
 
            if (queueList.Count == 0)
            {
                _activeWindowIndex = 0;
                ((PuppeteerClient)PuppeteerClient)._currentTargetId = null;
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"No windows remain after removing window with browserContextId [{browserContextId}]", this, GPALObjectType.PuppeteerCommunicator);
            }
            else
            {
                if (_activeWindowIndex > indexToRemove)
                {
                    _activeWindowIndex--;
                }
                else if (_activeWindowIndex == indexToRemove)
                {
                    _activeWindowIndex = Math.Max(0, _activeWindowIndex - 1);
                }
                ((PuppeteerClient)PuppeteerClient)._currentTargetId = GetCurrentTargetId();
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Removed window with browserContextId [{browserContextId}], Active window index now [{_activeWindowIndex}], Active tab index [{windowArray[_activeWindowIndex].ActiveTabIndex}], New active target [{((PuppeteerClient)PuppeteerClient)._currentTargetId}]", this, GPALObjectType.PuppeteerCommunicator);
            }
 
            return true;
        }
        public async Task<bool> ScrollPageAsync(string direction, int pagesToScroll, string s)
        {
            double initialScrollY = 0;
            bool retVal = false;
 
            try
            {
                // Validate direction
                if (direction != "up" && direction != "down")
                {
                    return retVal;
                }
 
                // Step 1: Check overflow property
                var overflowResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = @"getComputedStyle(document.documentElement).overflow",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, s).ConfigureAwait(false);
                string overflow = overflowResult?["result"]?["value"].ToString();
 
                // Step 2: Try window.scrollBy if overflow is not 'hidden' - which means we have scroll bars
                if (overflow != "hidden")
                {
                    for (int count = 0; count < pagesToScroll; count++)
                    {
                        if (true == (retVal = await scrollPage().ConfigureAwait(false)))
                            continue;
                        else
                            break;
                    }
                }
                if (false == retVal)
                    for (int count = 0; count < pagesToScroll; count++)
                    {
 
                        if (true == (retVal = await scrollSinglePageApp().ConfigureAwait(false)))
                            continue;
                        else
                            break;
                    }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Unable to page [{direction}] for [{pagesToScroll}] pages.", this, GPALObjectType.PuppeteerClient, ex);
            }
 
            async Task<bool> scrollPage()
            {
                // Get initial scroll position
                var initialScrollResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = @"window.scrollY",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, s).ConfigureAwait(false);
                initialScrollY = Convert.ToDouble(initialScrollResult?["result"]?["value"]);
 
                // Try window.scrollBy
                string scrollDirection = direction == "down" ? "window.innerHeight" : "-window.innerHeight";
                await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = $"window.scrollBy({{ left: 0, top: {scrollDirection}, behavior: 'instant' }})",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, s).ConfigureAwait(false);
 
                // Verify scroll
                var afterScrollResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = @"window.scrollY",
                    contextId = CurrentContextId,
                    returnByValue = true
 
                }, s).ConfigureAwait(false);
                double afterScrollY = Convert.ToDouble(afterScrollResult?["result"]?["value"]);
 
                if (afterScrollY != initialScrollY)
                {
                    return true; // Scroll worked
                }
                return false;
            }
 
            async Task<bool> scrollSinglePageApp()
            {
                // Step 3: Try scrolling the scrollable element
                var elementScrollResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = $@"(function() {{
                                        const isDown = '{direction}' === 'down';
                                        const scrollAmount = isDown ? window.innerHeight : -window.innerHeight;
                                        const scrollable = Array.from(document.querySelectorAll('*')).find(el => 
                                            el.scrollHeight > el.clientHeight && getComputedStyle(el).overflowY !== 'hidden'
                                        ) || document.body;
                                        const initialScrollTop = scrollable.scrollTop;
                                        scrollable.scrollBy({{ left: 0, top: scrollAmount, behavior: 'instant' }});
                                        return {{ initialScrollTop, scrollTop: scrollable.scrollTop, element: scrollable.className || 'body' }};
                                    }})()",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, s).ConfigureAwait(false);
 
                double initialScrollTop = Convert.ToDouble(elementScrollResult?["result"]?["value"]["initialScrollTop"]);
                double elementScrollTop = Convert.ToDouble(elementScrollResult?["result"]?["value"]["scrollTop"]);
 
                if (elementScrollTop != initialScrollTop)
                {
                    return true; // Scroll worked
                }
 
                return await scrollByKeyPress().ConfigureAwait(false);
 
                async Task<bool> scrollByKeyPress()
                {
                    // Step 4: Fallback to Page Up/Down key press
                    // Focus scrollable element
                    await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
                    {
                        expression = @"(function() {
                                    const scrollable = Array.from(document.querySelectorAll('*')).find(el => 
                                        el.scrollHeight > el.clientHeight && getComputedStyle(el).overflowY !== 'hidden'
                                    ) || document.body;
                                    scrollable.focus();
                                    return scrollable.className || 'body';
                                })()",
                        contextId = CurrentContextId,
                        returnByValue = true
                    }, s).ConfigureAwait(false);
 
                    // Send keyDown
                    int keyCode = direction == "down" ? 34 : 33;
                    string keyName = direction == "down" ? "PageDown" : "PageUp";
                    await SendCommand<object>(DevToolsMethods.InputDispatchKeyEvent, new
                    {
                        type = "keyDown",
                        windowsVirtualKeyCode = keyCode,
                        key = keyName,
                        code = keyName
                    }, s).ConfigureAwait(false);
 
                    // Send keyUp
                    await SendCommand<object>(DevToolsMethods.InputDispatchKeyEvent, new
                    {
                        type = "keyUp",
                        windowsVirtualKeyCode = keyCode,
                        key = keyName,
                        code = keyName
                    }, s).ConfigureAwait(false);
 
                    // Step 5: Verify scroll
                    var keyScrollResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                    {
                        expression = @"(function() {
                                    const scrollable = Array.from(document.querySelectorAll('*')).find(el => 
                                        el.scrollHeight > el.clientHeight && getComputedStyle(el).overflowY !== 'hidden'
                                    ) || document.body;
                                    return { scrollTop: scrollable.scrollTop, element: scrollable.className || 'body' };
                                })()",
                        contextId = CurrentContextId,
                        returnByValue = true
                    }, s).ConfigureAwait(false);
 
                    double keyScrollTop = Convert.ToDouble(keyScrollResult?["result"]?["value"]["scrollTop"]);
                    return keyScrollTop != initialScrollTop || keyScrollTop > 0; // Return true if scrolled
                }
            }
 
            return retVal;
        }
        public async Task<bool> ScrollToPositionAsync(string position, string s)
        {
            try
            {
                // Validate position
                if (position != "top" && position != "end")
                {
                    return false;
                }
 
                // Step 1: Check overflow property
                var overflowResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = $@"(function() {{
                                        return getComputedStyle(document.documentElement).overflow;
                                    }})()",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, s).ConfigureAwait(false);
                string overflow = overflowResult?["result"]?["value"].ToString();
 
                // Step 2: Try window.scrollTo if overflow is not 'hidden'
                double initialScrollY = 0;
                if (overflow != "hidden")
                {
                    // Get initial scroll position
                    var initialScrollResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                    {
                        expression = @"window.scrollY",
                        contextId = CurrentContextId,
                        returnByValue = true
                    }, s).ConfigureAwait(false);
                    initialScrollY = Convert.ToDouble(initialScrollResult?["result"]?["value"]);
 
                    // Try window.scrollTo
                    string scrollTarget = position == "end" ? "document.body.scrollHeight" : "0";
                    await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
                    {
                        expression = $"window.scrollTo(0, {scrollTarget})",
                        contextId = CurrentContextId,
                        returnByValue = true
                    }, s).ConfigureAwait(false);
 
                    // Verify scroll
                    var afterScrollResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                    {
                        contextId = CurrentContextId,
                        expression = @"window.scrollY"
                    }, s).ConfigureAwait(false);
                    double afterScrollY = Convert.ToDouble(afterScrollResult?["result"]?["value"]);
 
                    if (afterScrollY != initialScrollY)
                    {
                        return true; // Scroll worked
                    }
                }
 
                // Step 3: Try scrolling the scrollable element
                var elementScrollResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = $@"(function() {{
                                        const scrollable = Array.from(document.querySelectorAll('*')).find(el => 
                                            el.scrollHeight > el.clientHeight && getComputedStyle(el).overflowY !== 'hidden'
                                        ) || document.body;
                                        const initialScrollTop = scrollable.scrollTop;
                                        const scrollTarget = {(position == "end" ? "scrollable.scrollHeight" : "0")};
                                        scrollable.scrollTo({{left: 0, top: scrollTarget, behavior: 'instant'}});
                                        return {{ initialScrollTop, scrollTop: scrollable.scrollTop, element: scrollable.className || 'body' }};
                                    }})()",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, s).ConfigureAwait(false);
 
                double initialScrollTop = Convert.ToDouble(elementScrollResult?["result"]?["value"]["initialScrollTop"]);
                double elementScrollTop = Convert.ToDouble(elementScrollResult?["result"]?["value"]["scrollTop"]);
 
                if (elementScrollTop != initialScrollTop)
                {
                    return true; // Scroll worked
                }
 
                // Step 4: Fallback to Home/End key press
                // Focus scrollable element
                await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = @"(function() {
                                    const scrollable = Array.from(document.querySelectorAll('*')).find(el => 
                                        el.scrollHeight > el.clientHeight && getComputedStyle(el).overflowY !== 'hidden'
                                    ) || document.body;
                                    scrollable.focus();
                                    return scrollable.className || 'body';
                                })()",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, s).ConfigureAwait(false);
 
                // Send keyDown
                int keyCode = position == "end" ? 35 : 36;
                string keyName = position == "end" ? "End" : "Home";
                await SendCommand<object>(DevToolsMethods.InputDispatchKeyEvent, new
                {
                    type = "keyDown",
                    windowsVirtualKeyCode = keyCode,
                    key = keyName,
                    code = keyName
                }, s).ConfigureAwait(false);
 
                // Send keyUp
                await SendCommand<object>(DevToolsMethods.InputDispatchKeyEvent, new
                {
                    type = "keyUp",
                    windowsVirtualKeyCode = keyCode,
                    key = keyName,
                    code = keyName
                }, s).ConfigureAwait(false);
 
                // Step 5: Verify scroll
                var keyScrollResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = @"(function() {
                                    const scrollable = Array.from(document.querySelectorAll('*')).find(el => 
                                        el.scrollHeight > el.clientHeight && getComputedStyle(el).overflowY !== 'hidden'
                                    ) || document.body;
                                    return { scrollTop: scrollable.scrollTop, element: scrollable.className || 'body' };
                                })()",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, s).ConfigureAwait(false);
 
                double keyScrollTop = Convert.ToDouble(keyScrollResult?["result"]?["value"]["scrollTop"]);
                return keyScrollTop != initialScrollTop || keyScrollTop > 0; // Return true if scrolled
            }
            catch
            {
                return false;
            }
        }
        public async Task<bool> ScrollWindowByPixelsAsync(int hPixels, int vPixels, string sessionId)
        {
            try
            {
                // Check for main window scrollability
                var overflowResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = $@"(function() {{
                                        return getComputedStyle(document.documentElement).overflow;
                                    }})()",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
                string overflow = overflowResult?.result?.value?.ToString();
 
                // Try window.scrollBy if overflow is not 'hidden'
                if (overflow != "hidden")
                {
                    // Get initial scroll position
                    var initialScrollResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                    {
                        expression = @"[window.scrollX, window.scrollY]",
                        contextId = CurrentContextId,
                        returnByValue = true
                    }, sessionId).ConfigureAwait(false);
                    var initialScrollX = initialScrollResult?.result?.value?.First;
                    var initialScrollY = initialScrollResult?.result?.value?.Last;
 
                    // Try window.scrollBy
                    await SendCommand<object>(DevToolsMethods.RuntimeEvaluate, new
                    {
                        expression = $"window.scrollBy({hPixels}, {vPixels})",
                        contextId = CurrentContextId,
                        returnByValue = true
                    }, sessionId).ConfigureAwait(false);
 
                    // Verify scroll
                    var afterScrollResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                    {
                        expression = @"[window.scrollX, window.scrollY]",
                        contextId = CurrentContextId,
                        returnByValue = true
                    }, sessionId).ConfigureAwait(false);
                    var afterScrollX = afterScrollResult?.result?.value?.First;
                    var afterScrollY = afterScrollResult?.result?.value?.Last;
 
                    if (afterScrollX != initialScrollX || afterScrollY != initialScrollY)
                    {
                        return true; // Scroll worked
                    }
                }
 
                // Try scrolling the scrollable element
                var elementScrollResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = $@"(function() {{
                                const scrollable = Array.from(document.querySelectorAll('*')).find(el => 
                                    (el.scrollHeight > el.clientHeight && getComputedStyle(el).overflowY !== 'hidden') ||
                                    (el.scrollWidth > el.clientWidth && getComputedStyle(el).overflowX !== 'hidden')
                                ) || document.body;
                                const initialScrollLeft = scrollable.scrollLeft;
                                const initialScrollTop = scrollable.scrollTop;
                                scrollable.scrollBy({hPixels}, {vPixels});
                                return {{ initialScrollLeft, initialScrollTop, scrollLeft: scrollable.scrollLeft, scrollTop: scrollable.scrollTop, element: scrollable.className || 'body' }};
                            }})()",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
 
                double initialScrollLeft = Convert.ToDouble(elementScrollResult?.result?.value?.initialScrollLeft ?? 0);
                double initialScrollTop = Convert.ToDouble(elementScrollResult?.result?.value?.initialScrollTop ?? 0);
                double elementScrollLeft = Convert.ToDouble(elementScrollResult?.result?.value?.scrollLeft ?? 0);
                double elementScrollTop = Convert.ToDouble(elementScrollResult?.result?.value?.scrollTop ?? 0);
 
                if (elementScrollLeft != initialScrollLeft || elementScrollTop != initialScrollTop)
                {
                    return true; // Scroll worked
                }
 
                // Fallback to Input.synthesizeScrollGesture (touch-based scrolling)
                // This is a more robust alternative to keyboard keys for relative pixel scrolling
                await SendCommand<object>(DevToolsMethods.InputSynthesizeScrollGesture, new
                {
                    x = 100,  // Arbitrary start position
                    y = 100,  // Arbitrary start position
                    xDistance = -hPixels, // Note: xDistance is positive for scrolling left
                    yDistance = -vPixels, // Note: yDistance is positive for scrolling up
                    speed = 800 // Optional speed control
                }, sessionId).ConfigureAwait(false);
 
                // Verify scroll again after the gesture
                var finalScrollResult = await SendCommand<dynamic>(DevToolsMethods.RuntimeEvaluate, new
                {
                    expression = @"(function() {
                            const scrollable = Array.from(document.querySelectorAll('*')).find(el => 
                                (el.scrollHeight > el.clientHeight && getComputedStyle(el).overflowY !== 'hidden') ||
                                (el.scrollWidth > el.clientWidth && getComputedStyle(el).overflowX !== 'hidden')
                            ) || document.body;
                            return { scrollLeft: scrollable.scrollLeft, scrollTop: scrollable.scrollTop };
                        })()",
                    contextId = CurrentContextId,
                    returnByValue = true
                }, sessionId).ConfigureAwait(false);
 
                double finalScrollLeft = Convert.ToDouble(finalScrollResult?.result?.value?.scrollLeft ?? 0);
                double finalScrollTop = Convert.ToDouble(finalScrollResult?.result?.value?.scrollTop ?? 0);
 
                // This verification is simpler; just check that a change occurred.
                return (finalScrollLeft != initialScrollLeft || finalScrollTop != initialScrollTop);
            }
            catch
            {
                return false;
            }
        }
        public async Task<bool> SelectByValue(string ElementHandle, string value, string sessionId = null)
        {
            var result = await SendCommand<dynamic>(
                DevToolsMethods.RuntimeCallFunctionOn,
                new
                {
                    objectId = ElementHandle,
                    contextId = CurrentContextId,
                    functionDeclaration = @"
                        function(value) {
                            const oldValue = this.value;
                            this.value = value;
                            const changed = this.value !== oldValue;
                            this.dispatchEvent(new Event('input', { bubbles: true }));
                            this.dispatchEvent(new Event('change', { bubbles: true }));
                            return changed;
                        }",
                    arguments = new[] { new { value = value } }
                },
                sessionId ?? GetEffectiveSessionId()).ConfigureAwait(false);
 
            return result?.result?.value == true;
        }
        public async Task<bool> SelectByIndex(string ElementHandle, int index, string sessionId = null)
        {
            var result = await SendCommand<dynamic>(
                DevToolsMethods.RuntimeCallFunctionOn,
                new
                {
                    objectId = ElementHandle,
                    contextId = CurrentContextId,
                    functionDeclaration = @"
                        function(idx) {
                            if (idx < 0 || idx >= this.options.length) {
                                return false;
                            }
                            const oldIndex = this.selectedIndex;
                            this.selectedIndex = idx;
                            const changed = this.selectedIndex !== oldIndex;
                            this.dispatchEvent(new Event('input', { bubbles: true }));
                            this.dispatchEvent(new Event('change', { bubbles: true }));
                            return changed;
                        }",
                    arguments = new[] { new { value = index } }
                },
                sessionId ?? GetEffectiveSessionId()).ConfigureAwait(false);
 
            return result?.result?.value == true;
        }
        #region HELPERS
        internal async Task<bool> SetWindowSize(Rectangle windowSize, string sessionId = null)
        {
            sessionId ??= GetEffectiveSessionId();
 
            var screen = System.Windows.Forms.Screen.PrimaryScreen.Bounds;
 
            var windowId = await GetCurrentWindow(sessionId).ConfigureAwait(false);
 
            await SendCommand(DevToolsMethods.BrowserSetWindowBounds, new
            {
                windowId,
                bounds = new
                {
                    left = windowSize.X,
                    top = windowSize.Y,
                    width = windowSize.Width,
                    height = windowSize.Height
                }
            }, sessionId).ConfigureAwait(false);
 
            return true;
        }        
        #endregion HELPERS
    }
    internal static class DevToolsCommandBuilder
    {
        // Complete list of CDP DOM methods that require a nodeId parameter
        // Based on Chrome DevTools Protocol (version 1.3, stable as of Chrome 126+)
        internal static readonly HashSet<string> MethodsRequiringNodeId = new HashSet<string>
                            {
                                // DOM domain methods that require nodeId
                                "DOM.copyTo",
                                "DOM.describeNode",
                                "DOM.focus",
                                "DOM.getAttributes",
                                "DOM.getBoxModel",
                                "DOM.getContentQuads",
                                "DOM.getFlattenedDocument",
                                "DOM.getNodeForLocation",
                                "DOM.getOuterHTML",
                                "DOM.getRelayoutBoundary",
                                "DOM.moveTo",
                                "DOM.querySelector",
                                "DOM.querySelectorAll",
                                "DOM.removeAttribute",
                                "DOM.removeNode",
                                "DOM.requestNode",
                                "DOM.setAttributeValue",
                                "DOM.setAttributesAsText",
                                "DOM.setNodeName",
                                "DOM.setNodeValue",
                                "DOM.setOuterHTML",
                                "DOM.collectClassNames",
                                "DOM.getNodeStackTraces",
                                "DOM.scrollIntoViewIfNeeded",
                                // Accessibility domain methods that require nodeId
                                "Accessibility.getPartialAXTree",
                                "Accessibility.getFullAXTree",
                                // CSS domain methods that require nodeId
                                "CSS.getComputedStyleForNode",
                                "CSS.getInlineStylesForNode",
                                "CSS.getMatchedStylesForNode",
                                "CSS.getBackgroundColors",
                                // Add any experimental or newer methods if needed (none currently require nodeId in stable CDP)
                            };
 
        public static string BuildCommand<TParameters>(
                DevToolsMethods method,
                TParameters parameters,
                long commandId,
                string sessionId = null,
                int docRootId = 1)
        {
            string methodString = GetMethodString(method);
            object finalParameters = parameters;
 
            // Check if the method requires a nodeId and parameters are provided
            if (MethodsRequiringNodeId.Contains(methodString) && parameters != null)
            {
                // Convert parameters to dictionary for manipulation
                IDictionary<string, object> paramDict;
                if (parameters is IDictionary<string, object> dict)
                {
                    paramDict = dict;
                }
                else
                {
                    // Handle anonymous objects
                    paramDict = parameters.GetType()
                        .GetProperties()
                        .ToDictionary(p => p.Name, p => p.GetValue(parameters));
                }
 
                finalParameters = paramDict;
            }
 
            string paramsString = "";
            if (finalParameters != null)
            {
                IDictionary<string, object> paramDict;
                if (finalParameters is IDictionary<string, object> dict)
                {
                    paramDict = dict;
                }
                else
                {
                    paramDict = finalParameters.GetType()
                        .GetProperties()
                        .ToDictionary(p => p.Name, p => p.GetValue(finalParameters));
                }
 
                var filteredDict = paramDict.Where(kvp => kvp.Value != null)
                                           .ToDictionary(kvp => kvp.Key, kvp => kvp.Value);
                if (filteredDict.Count > 0)
                {
                    paramsString = $", \"params\": {JsonConvert.SerializeObject(filteredDict)}";
                }
            }
 
            string sessionString = sessionId != null ? $"\"sessionId\": \"{sessionId}\"," : "";
            string command = $"{{\"id\": {commandId}, {sessionString} \"method\": \"{methodString}\"{paramsString}}}";
 
            // NOTE: this can be quite excessive
            GPAL.PublishSimpleEvent(GPALEventType.DEEPDEBUG, $"Generated command: [{command}]");
 
            return command;
        }

        internal static string GetMethodString(DevToolsMethods method)
        {
            var attr = method.GetAttributeOfType<CommandAttribute>();
            return attr?.CommandString ?? method.ToString().Replace('_', '.');
        }
    }
 
    public static class EnumExtensions
    {
        public static TAttribute GetAttributeOfType<TAttribute>(this Enum enumVal) where TAttribute : Attribute
        {
            var type = enumVal.GetType();
            var memInfo = type.GetMember(enumVal.ToString());
            var attributes = memInfo[0].GetCustomAttributes(typeof(TAttribute), false);
            return (attributes.Length > 0) ? (TAttribute)attributes[0] : null;
        }
    }
    public static class TaskExtensions
    {
        public static async Task<T> TimeoutAfter<T>(this Task<T> task, TimeSpan timeout, string what = null)
        {
            Task completedTask = null;
            using (var cts = new CancellationTokenSource())
            {
                var delayTask = Task.Delay(timeout, cts.Token);
                try
                {
                    completedTask = await Task.WhenAny(task, delayTask).ConfigureAwait(false);
                }
                catch (Exception ex)
                {
                    var ex2 = ex;
                }
 
                if (completedTask == delayTask)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"[{what ?? "Operation"}] timed out after [{timeout.TotalSeconds}]s", null, GPALObjectType.Puppeteer);
                    return default;
                }
 
                // Cancel the delay task immediately so it stops consuming system resources
                cts.Cancel();
 
                if (task.IsFaulted)
                {
                    if (false == task.Exception?.InnerException?.Message.Contains("wasn't found"))
                        GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Task faulted: [{task.Exception?.InnerException?.Message ?? "Unknown error"}]", null, GPALObjectType.Puppeteer);
                    return default;
                }
 
                if (task.IsCanceled)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, "Task canceled", null, GPALObjectType.Puppeteer);
                    return default;
                }
 
                // using task.Result avoids spinning up another await context state machine.
                return task.Result;
            }
        }
    }
 
    public class BoxModelResponse
    {
        public Model Model { get; set; }
    }
 
    public class Model
    {
        public double[] Content { get; set; } // Use double[] for the array of numbers
        public double[] Padding { get; set; }
        public double[] Border { get; set; }
        public double[] Margin { get; set; }
        public int Width { get; set; }
        public int Height { get; set; }
    }
}