Merge pull request #5 from g4-api/development

Development

Author: gravity-api

src/Common.Domain/Models/RecorderNodeModel.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using System.Text.Json.Serialization;
 
 using Common.Domain.Extensions;
@@ -10,6 +11,7 @@ namespace Common.Domain.Models
     /// </summary>
     public class RecorderNodeModel<T>
     {
+        #region *** Properties   ***
         /// <summary>
         /// The automation-specific identifier assigned to the element (AutomationId).
         /// </summary>
@@ -76,11 +78,18 @@ public class RecorderNodeModel<T>
         /// </summary>
         public int ProcessId { get; set; }
 
+        /// <summary>
+        /// Gets or sets a collection of key-value pairs representing additional properties.
+        /// </summary>
+        public Dictionary<string, object> Properties { get; set; }
+
         /// <summary>
         /// The runtime identifier assigned by UIA to uniquely identify the element.
         /// </summary>
         public int[] RuntimeId { get; set; }
+        #endregion
 
+        #region *** Nested Types ***
         /// <summary>
         /// Represents the bounding rectangle of a UI element in screen coordinates.
         /// </summary>
@@ -140,5 +149,6 @@ public class PatternDataModel
             /// </summary>
             public string Name { get; set; }
         }
+        #endregion
     }
 }

src/UiaPeek.Domain/Extensions/LocalExtensions.cs

@@ -5,6 +5,7 @@
 using System.Linq;
 using System.Runtime.InteropServices;
 using System.Text;
+using System.Text.RegularExpressions;
 
 using UiaPeek.Domain.Models;
 
@@ -135,9 +136,7 @@ public static UiaChainModel NewAncestorChain(this CUIAutomation8 automation, IUI
         /// <returns>A deterministic locator string beginning with <c>/Desktop</c>.</returns>
         public static string ResolveLocator(this UiaChainModel chain)
         {
-            // Identifiers containing quotes cannot be safely embedded in XPath attribute predicates.
-            static bool IsBroken(string input) => input.Contains('\'') || input.Contains('"');
-
+            // Extract the ancestor nodes from the chain, defaulting to an empty list if the chain is null.
             var nodes = chain?.Path ?? [];
             var builder = new StringBuilder("/Desktop");
 
@@ -163,9 +162,12 @@ public static string ResolveLocator(this UiaChainModel chain)
                 var separator = isGap ? "//" : "/";
                 isGap = false;
 
+                // Attempt to use AutomationId as the strongest available identifier, falling back to Name when safe,
+                // otherwise using a positional index among siblings of the same ControlType.
                 var automationId = node.AutomationId;
                 var name = node.Name;
 
+                // Identifiers that contain quotes cannot be used in XPath predicates and are considered broken.
                 var hasAutomationId = !string.IsNullOrEmpty(automationId) && !IsBroken(automationId);
                 var hasName = !string.IsNullOrEmpty(name) && !IsBroken(name);
 
@@ -186,9 +188,98 @@ public static string ResolveLocator(this UiaChainModel chain)
                 }
             }
 
+            // Return the constructed locator string.
             return builder.ToString();
+
+            // Identifiers containing quotes cannot be safely embedded in XPath attribute predicates.
+            static bool IsBroken(string input) => input.Contains('\'') || input.Contains('"');
+        }
+
+        // TODO: Add support for other stable attributes such as ClassName when they can be safely used in XPath predicates.
+        /// <summary>
+        /// Builds a compact semantic XPath from the fallback UIA XPath.
+        /// </summary>
+        /// <param name="chain">The UIA chain model that contains the fallback locator.</param>
+        /// <returns>
+        /// A normalized XPath that starts from <c>/Desktop</c> and targets the final
+        /// element by a stable identity, or <c>null</c> when a safe normalized locator
+        /// cannot be generated.
+        /// </returns>
+        public static string FormatXpath(this UiaChainModel chain)
+        {
+            // Get the original full fallback XPath from the UIA chain.
+            var xpath = chain?.FallbackLocator;
+
+            // A valid fallback XPath must be present and must start from the root.
+            if (string.IsNullOrWhiteSpace(xpath) || !xpath.StartsWith('/'))
+            {
+                return null;
+            }
+
+            // Split the XPath into segments.
+            // The regex captures each XPath separator and the segment that follows it.
+            var matches = Regex.Matches(xpath, @"(/+)([^/]+)");
+
+            // A normalized locator needs at least a root segment and a target segment.
+            if (matches.Count < 2)
+            {
+                return null;
+            }
+
+            // Keep only the segment text.
+            // Example: "/Desktop/Window[1]/Button[@Name='OK']"
+            // becomes: "Desktop", "Window[1]", "Button[@Name='OK']".
+            var segments = matches
+                .Select(m => m.Groups[2].Value)
+                .ToArray();
+
+            // The final segment is the selected UIA element.
+            var finalSegment = segments[^1];
+
+            // The final element must have a stable identity.
+            // Index-only locators are intentionally rejected for normalized output.
+            if (!finalSegment.Contains("[@AutomationId=") && !finalSegment.Contains("[@Name="))
+            {
+                return null;
+            }
+
+            // Do not generate a normalized element locator when the selected target
+            // is itself a Window.
+            if (ControlType(finalSegment).Equals("Window", StringComparison.OrdinalIgnoreCase))
+            {
+                return null;
+            }
+
+            // Find the first Window ancestor before the final target segment.
+            // The target itself is excluded from this search.
+            var windowSegment = segments[..^1]
+                .FirstOrDefault(s => ControlType(s).Equals("Window", StringComparison.OrdinalIgnoreCase));
+
+            // If no Window ancestor exists, search from Desktop directly to the target.
+            if (windowSegment == null)
+            {
+                return $"/Desktop//{finalSegment}";
+            }
+
+            // Anchor the locator through the Window ancestor and then search below it
+            // for the final target element.
+            var result = $"/Desktop//{windowSegment}//{finalSegment}";
+
+            // Return null when normalization produced the same value as the fallback.
+            return result == xpath ? null : result;
+
+            // Gets the control type name from an XPath segment.
+            static string ControlType(string segment)
+            {
+                // The control type is stored before the first '[' character.
+                var idx = segment.IndexOf('[');
+
+                // If the segment has no predicate, the whole segment is the control type.
+                return idx < 0 ? segment : segment[..idx];
+            }
         }
 
+        // TODO: Export all properties that can be safely retrieved from the element, such as IsContentElement, IsControlElement, IsEnabled, etc.
         // Converts an IUIAutomationElement into a UiaNodeModel representation.
         private static UiaNodeModel Convert(IUIAutomationElement element, bool metadata)
         {
@@ -341,32 +432,44 @@ private static (int All, int SameControlType) GetSiblingIndexes(
 
             try
             {
+                // Start with the first child of the parent element.
+                // If the parent has no children or retrieval fails, this will be null and the loop will be skipped.
                 var child = Safe(() => walker.GetFirstChildElement(parent), fallback: null);
 
+                // Walk through siblings until the target element is found, counting positions.
                 while (child != null)
                 {
                     // Check whether this sibling is the target element.
                     var isTarget = false;
 
+                    // CompareElements can throw if either element is stale or the provider
+                    // is buggy, so we catch exceptions and treat them as non-matches.
                     try
                     {
                         isTarget = automation.CompareElements(child, target) == 1;
                     }
                     catch (COMException) { }
                     catch (InvalidComObjectException) { }
 
+                    // If this sibling is the target, stop counting; otherwise,
+                    // increment counts and move to the next sibling.
                     if (isTarget)
                     {
                         break;
                     }
 
+                    // Increment the count of all siblings encountered so far.
+                    // This count is used to determine the target's position among all siblings.
                     allCount++;
 
+                    // If this sibling shares the same ControlTypeId as the target, increment the same-type count.
                     if (Safe(() => child.CurrentControlType) == targetControlTypeId)
                     {
                         sameTypeCount++;
                     }
 
+                    // Move to the next sibling element, handling potential COM exceptions safely.
+                    // If retrieval fails, child will be set to null and the loop will exit.
                     child = Safe(() => walker.GetNextSiblingElement(child), fallback: null);
                 }
             }

src/UiaPeek.Domain/Middlewares/UiaEventCaptureService.cs

@@ -455,7 +455,7 @@ private void ResolveMouseEvent(EventRecord eventRecord)
                 var clickMessage = new UiaEventModel
                 {
                     Chain = _repository.Peek(x: mouse.pt.X, y: mouse.pt.Y), // UI element at cursor position.
-                    Event = GetMouseEventName(eventRecord.WParam),         // Resolve readable event name.
+                    Event = GetMouseEventName(eventRecord.WParam),          // Resolve readable event name.
                     Timestamp = eventRecord.Timestamp,
                     Type = "Mouse",
                     Value = new

src/UiaPeek.Domain/Models/UiaChainModel.cs

@@ -12,7 +12,9 @@ namespace UiaPeek.Domain.Models
     /// </summary>
     public class UiaChainModel : ChainModel<UiaNodeModel>
     {
-        // Intentionally empty — provides a domain-specific type for UIA chains.
-        // Add members here if UIA chains require additional metadata or logic.
+        /// <summary>
+        /// Gets or sets a fallback locator string for the trigger element.
+        /// </summary>
+        public string FallbackLocator { get; set; } = string.Empty;
     }
 }

src/UiaPeek.Domain/UiaPeekRepository.cs

@@ -26,7 +26,13 @@ public UiaChainModel Peek(int x, int y)
             chain.Point = new RecorderPointModel { XPos = x, YPos = y };
 
             // Build the absolute XPath locator for the ancestor chain.
-            chain.Locator = chain.ResolveLocator();
+            chain.FallbackLocator = chain.ResolveLocator();
+            chain.Locator = chain.FormatXpath();
+
+            // If the formatted XPath locator is empty, fall back to the absolute locator.
+            chain.Locator = string.IsNullOrEmpty(chain.Locator)
+                ? chain.FallbackLocator
+                : chain.Locator;
 
             // Indicate that this chain was triggered by a hover action.
             chain.Trigger = "Hover";
@@ -49,11 +55,17 @@ public UiaChainModel Peek()
             var chain = automation.NewAncestorChain(element) ?? new UiaChainModel();
 
             // Generate the absolute XPath locator for the ancestor chain.
-            chain.Locator = chain.ResolveLocator();
+            chain.FallbackLocator = chain.ResolveLocator();
+            chain.Locator = chain.FormatXpath();
 
             // Indicate that this chain was triggered by a focus action.
             chain.Trigger = "Focus";
 
+            // If the formatted XPath locator is empty, fall back to the absolute locator.
+            chain.Locator = string.IsNullOrEmpty(chain.Locator)
+                ? chain.FallbackLocator
+                : chain.Locator;
+
             // Return the ancestor chain model.
             return chain;
         }

src/UiaPeek.PathFinder/MainWindow.xaml

@@ -53,6 +53,18 @@
                 AccessKeyManager.AccessKeyPressed="BtnTestPath_AccessKeyPressed"
                 Cursor="Hand"/>
 
+        <Button Content="_Toggle Path"
+                HorizontalAlignment="Left"
+                Margin="235,162,0,0"
+                VerticalAlignment="Top"
+                RenderTransformOrigin="-0.57,1.481"
+                Height="30"
+                Width="70"
+                Name="BtnTogglePath"
+                Click="BtnTogglePath_Click"
+                AccessKeyManager.AccessKeyPressed="BtnTogglePath_AccessKeyPressed"
+                Cursor="Hand"/>
+
         <Label Content="Idle"
                HorizontalAlignment="Left"
                Margin="11,133,0,0"
@@ -129,5 +141,12 @@
                 Click="BtnSetPosition_Click"
                 AccessKeyManager.AccessKeyPressed="BtnSetPosition_AccessKeyPressed"
                 Cursor="Hand"/>
+
+        <Label Content=""
+               HorizontalAlignment="Left"
+               Margin="350,238,0,0"
+               Name="LblHidden"
+               VerticalAlignment="Top"
+               Visibility="Hidden"/>
     </Grid>
 </Window>

src/UiaPeek.PathFinder/MainWindow.xaml.cs

@@ -50,6 +50,52 @@ public MainWindow()
             InitializeComponent();
         }
 
+        #region *** Toggle Path  ***
+        /// <summary>
+        /// Handles the path toggle button click and swaps the visible path value
+        /// with the hidden path value.
+        /// </summary>
+        /// <param name="sender">The button that raised the click event.</param>
+        /// <param name="e">The routed event arguments for the click event.</param>
+        private void BtnTogglePath_Click(object sender, RoutedEventArgs e)
+        {
+            TogglePath();
+        }
+
+        /// <summary>
+        /// Handles the access key press for the path toggle button and swaps the
+        /// visible path value with the hidden path value.
+        /// </summary>
+        /// <param name="sender">The control that raised the access key event.</param>
+        /// <param name="e">The access key event arguments.</param>
+        private void BtnTogglePath_AccessKeyPressed(object sender, AccessKeyPressedEventArgs e)
+        {
+            TogglePath();
+        }
+
+        // Swaps the value displayed in the path text box with the value stored in
+        // the hidden label.
+        private void TogglePath()
+        {
+            Task.Run(() =>
+            {
+                // Marshal the UI update back to the WPF dispatcher thread because
+                // TxbPath and LblHidden are UI elements and must be accessed from it.
+                Dispatcher.BeginInvoke(() =>
+                {
+                    // Capture the current visible path before replacing it.
+                    var path = TxbPath.Text.Trim();
+
+                    // Move the hidden path value into the visible text box.
+                    TxbPath.Text = LblHidden?.Content?.ToString();
+
+                    // Store the previous visible path as the new hidden path value.
+                    LblHidden.Content = path;
+                });
+            });
+        }
+        #endregion
+
         #region *** Start/Stop   ***
         /// <summary>
         /// Handles the Click event for the Start/Stop button.
@@ -101,6 +147,7 @@ private void StartStop(Button startStopButton)
                         TxbPath.Text = xpath;
                         TxbAxisX.Text = point.X.ToString();
                         TxbAxisY.Text = point.Y.ToString();
+                        LblHidden.Content = chain.FallbackLocator;
                     });
 
                     // Delay the loop iteration to avoid excessive updates
@@ -168,6 +215,7 @@ private void SetPosition()
         }
         #endregion
 
+        // TODO: Bug, xpath does not resolve as it supposed to while it resolves just fine in the driver using the same parser.
         #region *** Test Path    ***
         // Handles the Click event for the Test Path button.
         private void BtnTestPath_Click(object sender, RoutedEventArgs e)

src/UiaPeek.PathFinder/XpathParser.cs

@@ -57,9 +57,10 @@ private static List<string> FormatXpath(string xpath)
             var matches = Regex.Matches(xpath, pattern);
 
             // Convert the matches to a list of strings, trim whitespace, and filter out empty tokens
-            return [.. matches.Cast<Match>()
+            return matches.Cast<Match>()
                 .Select(match => match.Value.Trim(' ', '/'))
-                .Where(token => !string.IsNullOrEmpty(token))];
+                .Where(token => !string.IsNullOrEmpty(token))
+                .ToList();
         }
 
         // Creates a new UI Automation condition tree based on the specified segments.

src/UiaPeek/AppSettings.cs

@@ -0,0 +1,6 @@
+namespace UiaPeek
+{
+    public static class AppSettings
+    {
+    }
+}