From 95a009ef9a8192a422052ee32d263041fd0f3212 Mon Sep 17 00:00:00 2001
From: Ionite <dev@ionite.io>
Date: Mon, 17 Aug 2026 15:27:58 -0700
Subject: [PATCH] feat: accessible names for icon-only controls and
 --overlay-popups flag

UI Automation (and screen readers) saw icon-only buttons as their content's
ToString - "FluentAvalonia.UI.Controls.SymbolIcon" - making them
indistinguishable. Adds AutomationProperties.Name to the package card action
buttons, the DocsHelpButton theme, and the NavigationView pane toggle.

Adds --overlay-popups to render popups inside the window on Windows (already
the default on Linux/macOS), so window captures and the window's automation
subtree include open flyouts and dropdowns.

Platform options are now composed into one instance per platform before
applying: .With<T>() replaces the registered options wholesale, so the
per-flag instances were silently dropping earlier settings (X11 OverlayPopups
under --disable-gpu-rendering, macOS OverlayPopups under any rendering flag).

Co-Authored-By: Lykos (Fable 5) <noreply@lykos.ai>
---
 StabilityMatrix.Avalonia/Models/AppArgs.cs    |  8 +++
 StabilityMatrix.Avalonia/Program.cs           | 49 +++++--------------
 .../ControlThemes/DocsHelpButtonStyles.axaml  |  1 +
 .../Views/MainWindow.axaml                    |  7 +++
 .../MainPackageManagerView.axaml              | 16 +++++-
 .../AutomationNameTests.cs                    | 47 ++++++++++++++++++
 6 files changed, 90 insertions(+), 38 deletions(-)
 create mode 100644 StabilityMatrix.UITests/AutomationNameTests.cs

diff --git a/StabilityMatrix.Avalonia/Models/AppArgs.cs b/StabilityMatrix.Avalonia/Models/AppArgs.cs
index 66441ad34..ab11f68fd 100644
--- a/StabilityMatrix.Avalonia/Models/AppArgs.cs
+++ b/StabilityMatrix.Avalonia/Models/AppArgs.cs
@@ -74,6 +74,14 @@ public class AppArgs
     [Option("vulkan", HelpText = "Prefer Vulkan rendering")]
     public bool UseVulkanRendering { get; set; }
 
+    /// <summary>
+    /// Flag to render popups (flyouts, dropdowns, menus) inside the window instead of as
+    /// separate OS windows, so window captures and UI automation can see them.
+    /// Popups are clipped to the window bounds in this mode.
+    /// </summary>
+    [Option("overlay-popups", HelpText = "Render popups inside the window (for UI automation / capture)")]
+    public bool UseOverlayPopups { get; set; }
+
     /// <summary>
     /// Override global app home directory
     /// Defaults to (%APPDATA%|~/.config)/StabilityMatrix
diff --git a/StabilityMatrix.Avalonia/Program.cs b/StabilityMatrix.Avalonia/Program.cs
index 25b17cf31..838b018d0 100644
--- a/StabilityMatrix.Avalonia/Program.cs
+++ b/StabilityMatrix.Avalonia/Program.cs
@@ -236,56 +236,31 @@ public static AppBuilder BuildAvaloniaApp()
 
         var app = AppBuilder.Configure<App>().UsePlatformDetect().WithInterFont().LogToTrace();
 
-        if (Compat.IsLinux)
-        {
-            app = app.With(new X11PlatformOptions { OverlayPopups = true, WmClass = "stabilitymatrix" });
-        }
-        else if (Compat.IsMacOS)
-        {
-            app = app.With(new AvaloniaNativePlatformOptions { OverlayPopups = true });
-        }
+        // .With<T>() replaces the registered options instance wholesale, so each platform's
+        // options must be composed into a single object before applying.
+        var win32Options = new Win32PlatformOptions { OverlayPopups = Args.UseOverlayPopups };
+        var x11Options = new X11PlatformOptions { OverlayPopups = true, WmClass = "stabilitymatrix" };
+        var macOptions = new AvaloniaNativePlatformOptions { OverlayPopups = true };
 
         if (Args.UseOpenGlRendering)
         {
-            app = app.With(
-                new Win32PlatformOptions
-                {
-                    RenderingMode = [Win32RenderingMode.Wgl, Win32RenderingMode.Software],
-                }
-            );
+            win32Options.RenderingMode = [Win32RenderingMode.Wgl, Win32RenderingMode.Software];
         }
 
         if (Args.UseVulkanRendering)
         {
-            app = app.With(
-                    new X11PlatformOptions
-                    {
-                        RenderingMode = [X11RenderingMode.Vulkan],
-                        WmClass = "stabilitymatrix",
-                    }
-                )
-                .With(new Win32PlatformOptions { RenderingMode = [Win32RenderingMode.Vulkan] });
+            win32Options.RenderingMode = [Win32RenderingMode.Vulkan];
+            x11Options.RenderingMode = [X11RenderingMode.Vulkan];
         }
 
         if (Args.DisableGpuRendering)
         {
-            app = app.With(new Win32PlatformOptions { RenderingMode = new[] { Win32RenderingMode.Software } })
-                .With(
-                    new X11PlatformOptions
-                    {
-                        RenderingMode = new[] { X11RenderingMode.Software },
-                        WmClass = "stabilitymatrix",
-                    }
-                )
-                .With(
-                    new AvaloniaNativePlatformOptions
-                    {
-                        RenderingMode = new[] { AvaloniaNativeRenderingMode.Software },
-                    }
-                );
+            win32Options.RenderingMode = [Win32RenderingMode.Software];
+            x11Options.RenderingMode = [X11RenderingMode.Software];
+            macOptions.RenderingMode = [AvaloniaNativeRenderingMode.Software];
         }
 
-        return app;
+        return app.With(win32Options).With(x11Options).With(macOptions);
     }
 
     private static void HandleUpdateReplacement()
diff --git a/StabilityMatrix.Avalonia/Styles/ControlThemes/DocsHelpButtonStyles.axaml b/StabilityMatrix.Avalonia/Styles/ControlThemes/DocsHelpButtonStyles.axaml
index 5d5aeaee6..80d6b8f6e 100644
--- a/StabilityMatrix.Avalonia/Styles/ControlThemes/DocsHelpButtonStyles.axaml
+++ b/StabilityMatrix.Avalonia/Styles/ControlThemes/DocsHelpButtonStyles.axaml
@@ -25,6 +25,7 @@
         <Setter Property="VerticalAlignment" Value="Center" />
         <Setter Property="Foreground" Value="{DynamicResource TextFillColorSecondaryBrush}" />
         <Setter Property="ToolTip.Tip" Value="{x:Static lang:Resources.Label_ViewDocumentation}" />
+        <Setter Property="AutomationProperties.Name" Value="{x:Static lang:Resources.Label_ViewDocumentation}" />
 
         <Setter Property="Template">
             <ControlTemplate>
diff --git a/StabilityMatrix.Avalonia/Views/MainWindow.axaml b/StabilityMatrix.Avalonia/Views/MainWindow.axaml
index 30ecc7b21..c6b9900df 100644
--- a/StabilityMatrix.Avalonia/Views/MainWindow.axaml
+++ b/StabilityMatrix.Avalonia/Views/MainWindow.axaml
@@ -38,6 +38,13 @@
         <KeyBinding Command="{Binding OpenDocumentationCommand}" Gesture="F1" />
     </controls:AppWindowBase.KeyBindings>
 
+    <controls:AppWindowBase.Styles>
+        <!--  FluentAvalonia's template gives this icon-only button no accessible name  -->
+        <Style Selector="ui|NavigationView /template/ Button#TogglePaneButton">
+            <Setter Property="AutomationProperties.Name" Value="Toggle Navigation" />
+        </Style>
+    </controls:AppWindowBase.Styles>
+
     <Grid RowDefinitions="Auto,Auto,Auto,*">
         <Grid
             Name="TitleBarHost"
diff --git a/StabilityMatrix.Avalonia/Views/PackageManager/MainPackageManagerView.axaml b/StabilityMatrix.Avalonia/Views/PackageManager/MainPackageManagerView.axaml
index e05e94c0c..f99825e7c 100644
--- a/StabilityMatrix.Avalonia/Views/PackageManager/MainPackageManagerView.axaml
+++ b/StabilityMatrix.Avalonia/Views/PackageManager/MainPackageManagerView.axaml
@@ -113,8 +113,10 @@
                                         VerticalAlignment="Top"
                                         HorizontalContentAlignment="Right"
                                         VerticalContentAlignment="Top"
+                                        AutomationProperties.Name="More Options"
                                         BorderThickness="0"
-                                        Classes="transparent">
+                                        Classes="transparent"
+                                        ToolTip.Tip="More Options">
                                         <ui:SymbolIcon FontSize="18" Symbol="MoreVertical" />
                                         <Button.Flyout>
                                             <MenuFlyout Placement="BottomEdgeAlignedLeft">
@@ -347,6 +349,7 @@
                                         <Button
                                             Margin="4,4,4,0"
                                             Padding="6"
+                                            AutomationProperties.Name="{x:Static lang:Resources.Action_CheckForUpdates}"
                                             Classes="transparent"
                                             Command="{Binding OnLoadedAsync}"
                                             ToolTip.Tip="{x:Static lang:Resources.Action_CheckForUpdates}">
@@ -363,6 +366,7 @@
                                         <Button
                                             Margin="4,4,4,0"
                                             Padding="4"
+                                            AutomationProperties.Name="{x:Static lang:Resources.Action_Update}"
                                             Classes="borderless-success"
                                             Command="{Binding Update}"
                                             IsEnabled="{Binding !IsRunning}"
@@ -414,6 +418,7 @@
                                         <Button
                                             Margin="4,4,4,0"
                                             Padding="6"
+                                            AutomationProperties.Name="Launch Options"
                                             Classes="transparent"
                                             Command="{Binding ShowLaunchOptionsCommand}"
                                             IsVisible="{Binding !IsUnknownPackage}"
@@ -423,6 +428,7 @@
                                         <Button
                                             Margin="4,4,4,0"
                                             Padding="6"
+                                            AutomationProperties.Name="Extensions"
                                             Classes="transparent"
                                             Command="{Binding OpenExtensionsDialogCommand}"
                                             IsVisible="{Binding CanUseExtensions}"
@@ -444,6 +450,7 @@
                                             Name="LaunchButton"
                                             HorizontalAlignment="Stretch"
                                             VerticalAlignment="Bottom"
+                                            AutomationProperties.Name="{x:Static lang:Resources.Action_Launch}"
                                             Classes="accent"
                                             Command="{Binding Launch}">
                                             <Button.IsVisible>
@@ -465,6 +472,7 @@
                                             Name="SplitLaunchButton"
                                             HorizontalAlignment="Stretch"
                                             VerticalAlignment="Bottom"
+                                            AutomationProperties.Name="{x:Static lang:Resources.Action_Launch}"
                                             Classes="accent"
                                             Command="{Binding Launch}">
                                             <Button.IsVisible>
@@ -503,6 +511,7 @@
                                         <Button
                                             HorizontalAlignment="Stretch"
                                             VerticalAlignment="Bottom"
+                                            AutomationProperties.Name="{x:Static lang:Resources.Action_Stop}"
                                             Classes="borderless-danger"
                                             Command="{Binding StopCommand}"
                                             IsVisible="{Binding IsRunning}">
@@ -517,6 +526,7 @@
                                         <Button
                                             HorizontalAlignment="Stretch"
                                             VerticalAlignment="Bottom"
+                                            AutomationProperties.Name="{x:Static lang:Resources.Action_Restart}"
                                             BorderBrush="Transparent"
                                             Classes="borderless-info"
                                             Command="{Binding RestartCommand}"
@@ -532,6 +542,7 @@
                                         <Button
                                             HorizontalAlignment="Stretch"
                                             VerticalAlignment="Bottom"
+                                            AutomationProperties.Name="{x:Static lang:Resources.Label_Console}"
                                             Classes="accent"
                                             Command="{Binding NavToConsole}"
                                             IsVisible="{Binding IsRunning}">
@@ -546,6 +557,7 @@
                                         <Button
                                             HorizontalAlignment="Stretch"
                                             VerticalAlignment="Bottom"
+                                            AutomationProperties.Name="{x:Static lang:Resources.Label_WebUi}"
                                             Classes="accent"
                                             Command="{Binding LaunchWebUi}"
                                             IsVisible="{Binding ShowWebUiButton}">
@@ -560,6 +572,7 @@
                                         <Button
                                             HorizontalAlignment="Stretch"
                                             VerticalAlignment="Bottom"
+                                            AutomationProperties.Name="{x:Static lang:Resources.Action_Import}"
                                             Classes="transparent-info"
                                             Command="{Binding Import}"
                                             IsVisible="{Binding IsUnknownPackage}">
@@ -641,6 +654,7 @@
             Margin="0,8,0,0"
             HorizontalAlignment="Stretch"
             VerticalAlignment="Bottom"
+            AutomationProperties.Name="{x:Static lang:Resources.Action_AddPackage}"
             Classes="transparent"
             Command="{Binding ShowInstallDialog}">
             <StackPanel Margin="8" Orientation="Horizontal">
diff --git a/StabilityMatrix.UITests/AutomationNameTests.cs b/StabilityMatrix.UITests/AutomationNameTests.cs
new file mode 100644
index 000000000..8a468a75c
--- /dev/null
+++ b/StabilityMatrix.UITests/AutomationNameTests.cs
@@ -0,0 +1,47 @@
+using Avalonia.Automation;
+using Avalonia.Controls;
+using Avalonia.VisualTree;
+using FluentAvalonia.UI.Controls;
+using StabilityMatrix.Avalonia.Controls;
+using StabilityMatrix.Avalonia.Languages;
+using StabilityMatrix.Core.Models.Documentation;
+
+namespace StabilityMatrix.UITests;
+
+[Collection("TempDir")]
+public class AutomationNameTests : TestBase
+{
+    /// <summary>
+    /// The pane toggle is named via a /template/ style selector in MainWindow.axaml, which
+    /// silently matches nothing if FluentAvalonia renames the template part.
+    /// </summary>
+    [AvaloniaFact]
+    public async Task NavigationTogglePaneButton_ShouldHaveAutomationName()
+    {
+        var (window, _) = GetMainWindow();
+        await DoInitialSetup();
+
+        var toggleButton = window
+            .FindDescendantOfType<NavigationView>()!
+            .GetVisualDescendants()
+            .OfType<Button>()
+            .FirstOrDefault(b => b.Name == "TogglePaneButton");
+
+        Assert.NotNull(toggleButton);
+        Assert.Equal("Toggle Navigation", AutomationProperties.GetName(toggleButton));
+    }
+
+    /// <summary>
+    /// Icon-only control: the accessible name comes from the control theme, not content.
+    /// </summary>
+    [AvaloniaFact]
+    public void DocsHelpButton_ShouldHaveAutomationName()
+    {
+        var button = new DocsHelpButton { DocsPath = DocumentationPages.EnvironmentVariables };
+        var window = new Window { Content = button };
+
+        window.Show();
+
+        Assert.Equal(Resources.Label_ViewDocumentation, AutomationProperties.GetName(button));
+    }
+}