Add accessibility audit engine and CDP AX support

Introduce an accessibility audit subsystem: new abstractions (IAccessibilityRule, AccessibilityNode, AccessibilityViolation, AccessibilityAuditContext/Result, AccessibilityViolationSeverity), a rule engine, and a CDP-based tree query + selector helper. Add a built-in alt-text rule and a rule collection with plugin registration plumbing (PluginContext/BrowserContext integration). Expose transport capabilities on sessions and extend MotusCapabilities (AccessibilityTree, SecurityOverrides) with capability guards where appropriate; non-CDP transports now return a diagnostic message instead of failing. Include unit tests covering the engine, tree query, alt-text rule, and capability guard behavior.

Author: TorreyBetts

src/Motus.Abstractions/Enums/AccessibilityViolationSeverity.cs

@@ -0,0 +1,16 @@
+namespace Motus.Abstractions;
+
+/// <summary>
+/// Classifies the severity of an accessibility rule violation.
+/// </summary>
+public enum AccessibilityViolationSeverity
+{
+    /// <summary>A definite accessibility failure that prevents use.</summary>
+    Error,
+
+    /// <summary>A likely issue that may impair some users.</summary>
+    Warning,
+
+    /// <summary>An informational finding; not necessarily a defect.</summary>
+    Info
+}

src/Motus.Abstractions/Plugins/IAccessibilityRule.cs

@@ -0,0 +1,28 @@
+namespace Motus.Abstractions;
+
+/// <summary>
+/// Evaluates a single accessibility rule against one node in the accessibility tree.
+/// </summary>
+public interface IAccessibilityRule
+{
+    /// <summary>
+    /// Gets the unique identifier for this rule (e.g. "a11y-alt-text").
+    /// </summary>
+    string RuleId { get; }
+
+    /// <summary>
+    /// Gets a human-readable description of what this rule checks.
+    /// </summary>
+    string Description { get; }
+
+    /// <summary>
+    /// Evaluates the rule against the given node.
+    /// </summary>
+    /// <param name="node">The node to evaluate.</param>
+    /// <param name="context">The audit context providing tree-wide data and page access.</param>
+    /// <returns>
+    /// A <see cref="AccessibilityViolation"/> if this node violates the rule;
+    /// <c>null</c> if the node passes or this rule does not apply to the node.
+    /// </returns>
+    AccessibilityViolation? Evaluate(AccessibilityNode node, AccessibilityAuditContext context);
+}

src/Motus.Abstractions/Plugins/IPluginContext.cs

@@ -29,6 +29,12 @@ public interface IPluginContext
     /// <param name="reporter">The reporter to register.</param>
     void RegisterReporter(IReporter reporter);
 
+    /// <summary>
+    /// Registers a custom accessibility rule that will be invoked during accessibility audits.
+    /// </summary>
+    /// <param name="rule">The accessibility rule to register.</param>
+    void RegisterAccessibilityRule(IAccessibilityRule rule);
+
     /// <summary>
     /// Creates a logger scoped to the calling plugin.
     /// </summary>

src/Motus.Abstractions/Types/AccessibilityAuditContext.cs

@@ -0,0 +1,10 @@
+namespace Motus.Abstractions;
+
+/// <summary>
+/// Provides rules with access to the full tree and the page during an audit.
+/// </summary>
+/// <param name="AllNodes">All walkable nodes in the accessibility tree, in depth-first order.</param>
+/// <param name="Page">The page being audited, for computed-style queries.</param>
+public sealed record AccessibilityAuditContext(
+    IReadOnlyList<AccessibilityNode> AllNodes,
+    IPage Page);

src/Motus.Abstractions/Types/AccessibilityAuditResult.cs

@@ -0,0 +1,19 @@
+namespace Motus.Abstractions;
+
+/// <summary>
+/// The outcome of an accessibility audit over a page's accessibility tree.
+/// </summary>
+/// <param name="Violations">All unique violations found during the audit.</param>
+/// <param name="PassCount">Number of (node, rule) pairs that passed.</param>
+/// <param name="ViolationCount">Number of unique violations found.</param>
+/// <param name="Duration">Wall-clock time taken to perform the audit.</param>
+/// <param name="DiagnosticMessage">
+/// Optional message when the audit could not run fully
+/// (e.g. transport does not support accessibility queries).
+/// </param>
+public sealed record AccessibilityAuditResult(
+    IReadOnlyList<AccessibilityViolation> Violations,
+    int PassCount,
+    int ViolationCount,
+    TimeSpan Duration,
+    string? DiagnosticMessage = null);

src/Motus.Abstractions/Types/AccessibilityNode.cs

@@ -0,0 +1,24 @@
+namespace Motus.Abstractions;
+
+/// <summary>
+/// Represents a single node in the browser's accessibility tree.
+/// </summary>
+/// <param name="NodeId">The protocol-assigned node identifier.</param>
+/// <param name="Role">The ARIA or implicit role (e.g. "button", "img").</param>
+/// <param name="Name">The accessible name.</param>
+/// <param name="Value">The current value, for form controls.</param>
+/// <param name="Description">The accessible description.</param>
+/// <param name="Properties">Additional AX properties keyed by property name.</param>
+/// <param name="Children">Child nodes in tree order.</param>
+/// <param name="BackendDOMNodeId">The backend DOM node ID for element resolution.</param>
+/// <param name="Ignored">True if the node was ignored by the browser and excluded from the walkable tree.</param>
+public sealed record AccessibilityNode(
+    string NodeId,
+    string? Role,
+    string? Name,
+    string? Value,
+    string? Description,
+    IReadOnlyDictionary<string, string?> Properties,
+    IReadOnlyList<AccessibilityNode> Children,
+    long? BackendDOMNodeId,
+    bool Ignored = false);

src/Motus.Abstractions/Types/AccessibilityViolation.cs

@@ -0,0 +1,20 @@
+namespace Motus.Abstractions;
+
+/// <summary>
+/// Describes a single accessibility rule violation found during an audit.
+/// </summary>
+/// <param name="RuleId">The identifier of the rule that produced this violation (e.g. "a11y-alt-text").</param>
+/// <param name="Severity">The severity of the violation.</param>
+/// <param name="Message">A human-readable description of the violation.</param>
+/// <param name="NodeRole">The ARIA role of the violating node.</param>
+/// <param name="NodeName">The accessible name of the violating node.</param>
+/// <param name="BackendDOMNodeId">The backend DOM node ID for element targeting, if available.</param>
+/// <param name="Selector">Best-effort CSS selector for the violating element, or null.</param>
+public sealed record AccessibilityViolation(
+    string RuleId,
+    AccessibilityViolationSeverity Severity,
+    string Message,
+    string? NodeRole,
+    string? NodeName,
+    long? BackendDOMNodeId,
+    string? Selector);

src/Motus/Accessibility/AccessibilityRuleEngine.cs

@@ -0,0 +1,71 @@
+using System.Diagnostics;
+using Motus.Abstractions;
+
+namespace Motus;
+
+/// <summary>
+/// Walks the accessibility tree and invokes all registered rules on each node.
+/// </summary>
+internal sealed class AccessibilityRuleEngine
+{
+    private readonly IReadOnlyList<IAccessibilityRule> _rules;
+
+    internal AccessibilityRuleEngine(IReadOnlyList<IAccessibilityRule> rules)
+    {
+        _rules = rules;
+    }
+
+    /// <summary>
+    /// Executes the rule engine against the provided node list and context.
+    /// </summary>
+    internal AccessibilityAuditResult Run(
+        IReadOnlyList<AccessibilityNode> nodes,
+        AccessibilityAuditContext context,
+        string? diagnosticMessage = null)
+    {
+        var sw = Stopwatch.StartNew();
+
+        if (nodes.Count == 0 || _rules.Count == 0)
+        {
+            return new AccessibilityAuditResult(
+                Violations: [],
+                PassCount: 0,
+                ViolationCount: 0,
+                Duration: sw.Elapsed,
+                DiagnosticMessage: diagnosticMessage);
+        }
+
+        // Deduplication keyed on (RuleId, dedupeKey) where dedupeKey prefers
+        // BackendDOMNodeId for stability, falling back to NodeId for virtual nodes.
+        var seen = new HashSet<(string ruleId, string dedupeKey)>();
+        var violations = new List<AccessibilityViolation>();
+        int passCount = 0;
+
+        foreach (var node in nodes)
+        {
+            foreach (var rule in _rules)
+            {
+                var violation = rule.Evaluate(node, context);
+                if (violation is null)
+                {
+                    passCount++;
+                    continue;
+                }
+
+                var dedupeKey = node.BackendDOMNodeId.HasValue
+                    ? node.BackendDOMNodeId.Value.ToString()
+                    : node.NodeId;
+
+                if (seen.Add((violation.RuleId, dedupeKey)))
+                    violations.Add(violation);
+            }
+        }
+
+        return new AccessibilityAuditResult(
+            Violations: violations,
+            PassCount: passCount,
+            ViolationCount: violations.Count,
+            Duration: sw.Elapsed,
+            DiagnosticMessage: diagnosticMessage);
+    }
+}

src/Motus/Accessibility/AccessibilitySelectorHelper.cs

@@ -0,0 +1,69 @@
+using System.Text;
+using System.Text.Json;
+
+namespace Motus;
+
+/// <summary>
+/// Derives a best-effort CSS selector for an element using DOM.describeNode.
+/// </summary>
+internal static class AccessibilitySelectorHelper
+{
+    /// <summary>
+    /// Attempts to build a CSS selector for the given backend DOM node.
+    /// Returns null if the node cannot be described. Never throws.
+    /// </summary>
+    internal static async Task<string?> TryGetSelectorAsync(
+        IMotusSession session, long backendDOMNodeId, CancellationToken ct)
+    {
+        try
+        {
+            var result = await session.SendAsync(
+                "DOM.describeNode",
+                new DomDescribeNodeParams(BackendNodeId: (int)backendDOMNodeId),
+                CdpJsonContext.Default.DomDescribeNodeParams,
+                CdpJsonContext.Default.DomDescribeNodeResult,
+                ct).ConfigureAwait(false);
+
+            return BuildSelector(result.Node);
+        }
+        catch
+        {
+            return null;
+        }
+    }
+
+    private static string? BuildSelector(DomNodeDescription node)
+    {
+        if (node.LocalName is null)
+            return null;
+
+        var sb = new StringBuilder(node.LocalName.ToLowerInvariant());
+
+        // CDP describeNode returns attributes as a flat [name, value, name, value, ...] array.
+        if (node.Attributes is { ValueKind: JsonValueKind.Array } attrs)
+        {
+            var attrArray = attrs.EnumerateArray().ToArray();
+            for (int i = 0; i < attrArray.Length - 1; i += 2)
+            {
+                var name = attrArray[i].GetString();
+                var value = attrArray[i + 1].GetString();
+
+                if (name == "id" && !string.IsNullOrEmpty(value))
+                {
+                    sb.Append('#');
+                    sb.Append(value);
+                }
+                else if (name == "class" && !string.IsNullOrEmpty(value))
+                {
+                    foreach (var cls in value.Split(' ', StringSplitOptions.RemoveEmptyEntries))
+                    {
+                        sb.Append('.');
+                        sb.Append(cls);
+                    }
+                }
+            }
+        }
+
+        return sb.ToString();
+    }
+}