Add accessibility rules, collectors, and tests

Introduce a full accessibility audit subsystem: add AccessibilityRulesPlugin and register it in PluginHost; expand AccessibilityAuditContext with ComputedStyles, DuplicateIds and DocumentLanguage; add ComputedStyleInfo type. Implement collectors (ComputedStyleCollector, DuplicateIdCollector, DocumentLanguageCollector) and ContrastCalculator for WCAG luminance/contrast logic. Add a set of accessibility rules (color contrast, duplicate id, empty button/link, heading hierarchy, missing lang/landmark, unlabeled form control) and wire pre-fetching into Page.RunAccessibilityAuditAsync. Update CdpJsonContext with DOM/CSS CDP types used by collectors. Remove previous builtin rule registration from BrowserContext. Add comprehensive unit & integration tests for rules and contrast calculations.

Author: TorreyBetts

src/Motus.Abstractions/Types/AccessibilityAuditContext.cs

@@ -5,6 +5,12 @@ namespace Motus.Abstractions;
 /// </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>
+/// <param name="ComputedStyles">Pre-fetched computed styles keyed by BackendDOMNodeId.</param>
+/// <param name="DuplicateIds">Set of HTML id values that appear more than once in the document.</param>
+/// <param name="DocumentLanguage">The lang attribute value of the document element, or null if absent.</param>
 public sealed record AccessibilityAuditContext(
     IReadOnlyList<AccessibilityNode> AllNodes,
-    IPage Page);
+    IPage Page,
+    IReadOnlyDictionary<long, ComputedStyleInfo>? ComputedStyles = null,
+    IReadOnlySet<string>? DuplicateIds = null,
+    string? DocumentLanguage = null);

src/Motus.Abstractions/Types/ComputedStyleInfo.cs

@@ -0,0 +1,11 @@
+namespace Motus.Abstractions;
+
+/// <summary>
+/// Pre-fetched computed style properties for an element, used by accessibility rules
+/// that need CSS information (e.g., color contrast checks).
+/// </summary>
+public sealed record ComputedStyleInfo(
+    string? Color,
+    string? BackgroundColor,
+    string? FontSize,
+    string? FontWeight);

src/Motus/Accessibility/AccessibilityRulesPlugin.cs

@@ -0,0 +1,33 @@
+using Motus.Abstractions;
+
+namespace Motus;
+
+/// <summary>
+/// Built-in plugin that registers all WCAG 2.1 Level A and AA accessibility rules.
+/// Registered as a built-in in PluginHost (not via [MotusPlugin]) because
+/// internal types are not visible to user assemblies through the source generator.
+/// </summary>
+internal sealed class AccessibilityRulesPlugin : IPlugin
+{
+    public string PluginId => "motus.accessibility-rules";
+    public string Name => "Accessibility Rules";
+    public string Version => "1.0.0";
+    public string? Author => "Motus";
+    public string? Description => "Built-in WCAG 2.1 Level A and AA accessibility rules.";
+
+    public Task OnLoadedAsync(IPluginContext context)
+    {
+        context.RegisterAccessibilityRule(new AltTextAccessibilityRule());
+        context.RegisterAccessibilityRule(new UnlabeledFormControlRule());
+        context.RegisterAccessibilityRule(new MissingLandmarkRule());
+        context.RegisterAccessibilityRule(new HeadingHierarchyRule());
+        context.RegisterAccessibilityRule(new EmptyButtonRule());
+        context.RegisterAccessibilityRule(new EmptyLinkRule());
+        context.RegisterAccessibilityRule(new ColorContrastRule());
+        context.RegisterAccessibilityRule(new DuplicateIdRule());
+        context.RegisterAccessibilityRule(new MissingDocumentLanguageRule());
+        return Task.CompletedTask;
+    }
+
+    public Task OnUnloadedAsync() => Task.CompletedTask;
+}

src/Motus/Accessibility/ComputedStyleCollector.cs

@@ -0,0 +1,105 @@
+using Motus.Abstractions;
+
+namespace Motus;
+
+/// <summary>
+/// Pre-fetches computed CSS styles for accessibility nodes that need contrast checking.
+/// Uses CSS.getComputedStyleForNode via CDP to resolve color and background-color.
+/// </summary>
+internal static class ComputedStyleCollector
+{
+    private static readonly HashSet<string> TextBearingRoles = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "heading", "text", "paragraph", "label", "link", "button",
+        "menuitem", "menuitemcheckbox", "menuitemradio", "tab",
+        "treeitem", "option", "cell", "columnheader", "rowheader",
+        "gridcell", "listitem", "caption"
+    };
+
+    internal static async Task<Dictionary<long, ComputedStyleInfo>> CollectAsync(
+        IMotusSession session,
+        IReadOnlyList<AccessibilityNode> nodes,
+        CancellationToken ct)
+    {
+        var result = new Dictionary<long, ComputedStyleInfo>();
+
+        if ((session.Capabilities & MotusCapabilities.AccessibilityTree) == 0)
+            return result;
+
+        // Gather text-bearing nodes with BackendDOMNodeIds
+        var candidates = new List<(long backendNodeId, AccessibilityNode node)>();
+        foreach (var node in nodes)
+        {
+            if (node.BackendDOMNodeId.HasValue &&
+                !string.IsNullOrWhiteSpace(node.Name) &&
+                node.Role is not null &&
+                TextBearingRoles.Contains(node.Role))
+            {
+                candidates.Add((node.BackendDOMNodeId.Value, node));
+            }
+        }
+
+        if (candidates.Count == 0)
+            return result;
+
+        try
+        {
+            // Enable CSS domain
+            await session.SendAsync(
+                "CSS.enable",
+                CdpJsonContext.Default.CssEnableResult,
+                ct).ConfigureAwait(false);
+
+            // Push backend node IDs to get DOM node IDs
+            var backendIds = candidates.Select(c => (int)c.backendNodeId).ToArray();
+            var pushResult = await session.SendAsync(
+                "DOM.pushNodesByBackendIds",
+                new DomPushNodesByBackendIdsParams(backendIds),
+                CdpJsonContext.Default.DomPushNodesByBackendIdsParams,
+                CdpJsonContext.Default.DomPushNodesByBackendIdsResult,
+                ct).ConfigureAwait(false);
+
+            for (int i = 0; i < candidates.Count && i < pushResult.NodeIds.Length; i++)
+            {
+                var domNodeId = pushResult.NodeIds[i];
+                if (domNodeId <= 0)
+                    continue;
+
+                try
+                {
+                    var styleResult = await session.SendAsync(
+                        "CSS.getComputedStyleForNode",
+                        new CssGetComputedStyleForNodeParams(domNodeId),
+                        CdpJsonContext.Default.CssGetComputedStyleForNodeParams,
+                        CdpJsonContext.Default.CssGetComputedStyleForNodeResult,
+                        ct).ConfigureAwait(false);
+
+                    string? color = null, bgColor = null, fontSize = null, fontWeight = null;
+                    foreach (var prop in styleResult.ComputedStyle)
+                    {
+                        switch (prop.Name)
+                        {
+                            case "color": color = prop.Value; break;
+                            case "background-color": bgColor = prop.Value; break;
+                            case "font-size": fontSize = prop.Value; break;
+                            case "font-weight": fontWeight = prop.Value; break;
+                        }
+                    }
+
+                    result[candidates[i].backendNodeId] = new ComputedStyleInfo(color, bgColor, fontSize, fontWeight);
+                }
+                catch
+                {
+                    // Skip nodes whose styles can't be resolved
+                }
+            }
+        }
+        catch
+        {
+            // CSS domain not available or DOM push failed; return partial results
+        }
+
+        return result;
+    }
+
+}

src/Motus/Accessibility/ContrastCalculator.cs

@@ -0,0 +1,176 @@
+using System.Globalization;
+
+namespace Motus;
+
+/// <summary>
+/// Implements WCAG 2.1 relative luminance and contrast ratio calculations.
+/// </summary>
+internal static class ContrastCalculator
+{
+    /// <summary>
+    /// WCAG AA minimum contrast ratio for normal text.
+    /// </summary>
+    internal const double NormalTextThreshold = 4.5;
+
+    /// <summary>
+    /// WCAG AA minimum contrast ratio for large text (>= 18pt or bold >= 14pt).
+    /// </summary>
+    internal const double LargeTextThreshold = 3.0;
+
+    /// <summary>
+    /// Computes the WCAG contrast ratio between two colors.
+    /// Returns a value >= 1.0 where 1.0 means no contrast and 21.0 is maximum.
+    /// </summary>
+    internal static double ContrastRatio(double luminance1, double luminance2)
+    {
+        var lighter = Math.Max(luminance1, luminance2);
+        var darker = Math.Min(luminance1, luminance2);
+        return (lighter + 0.05) / (darker + 0.05);
+    }
+
+    /// <summary>
+    /// Computes relative luminance per WCAG 2.1 definition.
+    /// Input is an sRGB color with components in [0, 255].
+    /// </summary>
+    internal static double RelativeLuminance(int r, int g, int b)
+    {
+        var rLin = Linearize(r / 255.0);
+        var gLin = Linearize(g / 255.0);
+        var bLin = Linearize(b / 255.0);
+        return 0.2126 * rLin + 0.7152 * gLin + 0.0722 * bLin;
+    }
+
+    /// <summary>
+    /// Converts an sRGB component (0..1) to linear light.
+    /// </summary>
+    internal static double Linearize(double c) =>
+        c <= 0.04045 ? c / 12.92 : Math.Pow((c + 0.055) / 1.055, 2.4);
+
+    /// <summary>
+    /// Determines whether text is "large" per WCAG criteria.
+    /// Large text is >= 18pt (24px) or bold >= 14pt (18.66px).
+    /// </summary>
+    internal static bool IsLargeText(string? fontSize, string? fontWeight)
+    {
+        var px = ParsePx(fontSize);
+        if (px is null)
+            return false;
+
+        var isBold = IsBold(fontWeight);
+
+        // 18pt = 24px, 14pt = 18.66px
+        return px.Value >= 24.0 || (isBold && px.Value >= 18.66);
+    }
+
+    /// <summary>
+    /// Parses a CSS color string (rgb/rgba format from computed styles) into RGB components.
+    /// Returns false if the format is not recognized.
+    /// </summary>
+    internal static bool TryParseColor(string? color, out int r, out int g, out int b)
+    {
+        r = g = b = 0;
+        if (string.IsNullOrWhiteSpace(color))
+            return false;
+
+        var span = color.AsSpan().Trim();
+
+        // Handle "rgb(r, g, b)" and "rgba(r, g, b, a)"
+        if (span.StartsWith("rgb"))
+        {
+            var open = span.IndexOf('(');
+            var close = span.IndexOf(')');
+            if (open < 0 || close < 0 || close <= open + 1)
+                return false;
+
+            var inner = span.Slice(open + 1, close - open - 1);
+            return ParseRgbComponents(inner, out r, out g, out b);
+        }
+
+        // Handle "#RRGGBB" and "#RGB"
+        if (span.Length > 0 && span[0] == '#')
+        {
+            return TryParseHexColor(span.Slice(1), out r, out g, out b);
+        }
+
+        return false;
+    }
+
+    private static bool ParseRgbComponents(ReadOnlySpan<char> inner, out int r, out int g, out int b)
+    {
+        r = g = b = 0;
+
+        // Split by comma or space (modern CSS allows both)
+        Span<Range> parts = stackalloc Range[5];
+        int count;
+
+        if (inner.Contains(','))
+        {
+            count = inner.Split(parts, ',', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries);
+        }
+        else
+        {
+            count = inner.Split(parts, ' ', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries);
+        }
+
+        if (count < 3)
+            return false;
+
+        return int.TryParse(inner[parts[0]], NumberStyles.Integer, CultureInfo.InvariantCulture, out r) &&
+               int.TryParse(inner[parts[1]], NumberStyles.Integer, CultureInfo.InvariantCulture, out g) &&
+               int.TryParse(inner[parts[2]], NumberStyles.Integer, CultureInfo.InvariantCulture, out b);
+    }
+
+    private static bool TryParseHexColor(ReadOnlySpan<char> hex, out int r, out int g, out int b)
+    {
+        r = g = b = 0;
+
+        if (hex.Length == 6 || hex.Length == 8)
+        {
+            return int.TryParse(hex.Slice(0, 2), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out r) &&
+                   int.TryParse(hex.Slice(2, 2), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out g) &&
+                   int.TryParse(hex.Slice(4, 2), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out b);
+        }
+
+        if (hex.Length == 3 || hex.Length == 4)
+        {
+            if (!int.TryParse(hex.Slice(0, 1), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out r) ||
+                !int.TryParse(hex.Slice(1, 1), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out g) ||
+                !int.TryParse(hex.Slice(2, 1), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out b))
+                return false;
+
+            r = r * 16 + r;
+            g = g * 16 + g;
+            b = b * 16 + b;
+            return true;
+        }
+
+        return false;
+    }
+
+    private static double? ParsePx(string? fontSize)
+    {
+        if (string.IsNullOrWhiteSpace(fontSize))
+            return null;
+
+        var span = fontSize.AsSpan().Trim();
+        if (span.EndsWith("px", StringComparison.OrdinalIgnoreCase))
+            span = span.Slice(0, span.Length - 2);
+
+        return double.TryParse(span, NumberStyles.Float, CultureInfo.InvariantCulture, out var val)
+            ? val
+            : null;
+    }
+
+    private static bool IsBold(string? fontWeight)
+    {
+        if (string.IsNullOrWhiteSpace(fontWeight))
+            return false;
+
+        if (string.Equals(fontWeight, "bold", StringComparison.OrdinalIgnoreCase) ||
+            string.Equals(fontWeight, "bolder", StringComparison.OrdinalIgnoreCase))
+            return true;
+
+        return int.TryParse(fontWeight, NumberStyles.Integer, CultureInfo.InvariantCulture, out var weight) &&
+               weight >= 700;
+    }
+}

src/Motus/Accessibility/DocumentLanguageCollector.cs

@@ -0,0 +1,27 @@
+namespace Motus;
+
+/// <summary>
+/// Pre-fetches the document's lang attribute via Runtime.evaluate.
+/// </summary>
+internal static class DocumentLanguageCollector
+{
+    internal static async Task<string?> CollectAsync(IMotusSession session, CancellationToken ct)
+    {
+        try
+        {
+            var result = await session.SendAsync(
+                "Runtime.evaluate",
+                new RuntimeEvaluateParams("document.documentElement.lang || ''", ReturnByValue: true),
+                CdpJsonContext.Default.RuntimeEvaluateParams,
+                CdpJsonContext.Default.RuntimeEvaluateResult,
+                ct).ConfigureAwait(false);
+
+            var lang = result.Result.Value?.ToString();
+            return string.IsNullOrWhiteSpace(lang) ? null : lang;
+        }
+        catch
+        {
+            return null;
+        }
+    }
+}