Docs viewer: content zoom, scrollbar inset, fix code-span link rendering

- Browser-style zoom (50-200%, persisted in settings): the document
  wrapper is re-parented into a LayoutTransformControl inside the
  internal scroll viewer, so content scales but the scrollbar doesn't;
  compact zoom overlay in the bottom-right corner
- 18px right inset between content and the overlay scrollbar
- Links whose text is inline code (the docs breadcrumbs, e.g.
  [`Home`](../README.md)) rendered as literal text — Markdown.Avalonia
  can't parse code spans inside link text, so strip the backticks in a
  fence-aware preprocessing pass before rendering

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mohnjiles

StabilityMatrix.Avalonia/Controls/DocumentationMarkdownViewer.cs

@@ -1,8 +1,10 @@
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Windows.Input;
 using Avalonia;
 using Avalonia.Controls;
+using Avalonia.Media;
 using Avalonia.Threading;
 using Avalonia.VisualTree;
 using ColorTextBlock.Avalonia;
@@ -42,16 +44,61 @@ public ICommand? LinkCommand
         set => SetValue(LinkCommandProperty, value);
     }
 
+    /// <summary>
+    /// Zoom factor applied to the rendered document content (1.0 = 100%).
+    /// Scales the content inside the internal scroll viewer, so the scrollbar is unaffected.
+    /// </summary>
+    public static readonly StyledProperty<double> ContentZoomProperty = AvaloniaProperty.Register<
+        DocumentationMarkdownViewer,
+        double
+    >(nameof(ContentZoom), 1.0);
+
     public string? ImageBaseUrl
     {
         get => GetValue(ImageBaseUrlProperty);
         set => SetValue(ImageBaseUrlProperty, value);
     }
 
+    public double ContentZoom
+    {
+        get => GetValue(ContentZoomProperty);
+        set => SetValue(ContentZoomProperty, value);
+    }
+
+    /// <summary>
+    /// Hosts the document content inside the internal scroll viewer so zoom can scale the
+    /// content without scaling the scrollbar. Null if the base control's composition changes.
+    /// </summary>
+    private readonly LayoutTransformControl? zoomHost;
+
     public DocumentationMarkdownViewer()
     {
         ApplyLinkCommand();
         ApplyImageBaseUrl();
+
+        // The base ctor composes a non-templated inner ScrollViewer (a direct visual child)
+        // whose Content is the document wrapper, and never reassigns Content afterwards
+        // (page changes only swap the wrapper's Document). Re-parent the wrapper into a
+        // LayoutTransformControl so zoom scales the document but not the scrollbar, and add
+        // right margin so the overlay scrollbar doesn't cover the rightmost text.
+        if (this.GetVisualChildren().OfType<ScrollViewer>().FirstOrDefault() is { } innerViewer)
+        {
+            if (innerViewer.Content is Control content)
+            {
+                innerViewer.Content = null;
+                zoomHost = new LayoutTransformControl
+                {
+                    Child = content,
+                    Margin = new Thickness(0, 0, 18, 0),
+                };
+                innerViewer.Content = zoomHost;
+            }
+            else
+            {
+                // Fallback: at least keep the scrollbar off the content.
+                innerViewer.Padding = new Thickness(0, 0, 18, 0);
+            }
+        }
     }
 
     protected override void OnPropertyChanged(AvaloniaPropertyChangedEventArgs change)
@@ -66,6 +113,20 @@ protected override void OnPropertyChanged(AvaloniaPropertyChangedEventArgs chang
         {
             ApplyImageBaseUrl();
         }
+        else if (change.Property == ContentZoomProperty)
+        {
+            ApplyContentZoom();
+        }
+    }
+
+    private void ApplyContentZoom()
+    {
+        if (zoomHost is null)
+            return;
+
+        // Guard against zero/negative values from bad bindings.
+        var zoom = Math.Clamp(ContentZoom, 0.25, 4.0);
+        zoomHost.LayoutTransform = new ScaleTransform(zoom, zoom);
     }
 
     private void ApplyLinkCommand()

StabilityMatrix.Avalonia/ViewModels/DocumentationViewModel.cs

@@ -27,8 +27,13 @@ namespace StabilityMatrix.Avalonia.ViewModels;
 [RegisterSingleton<DocumentationViewModel>]
 public partial class DocumentationViewModel : PageViewModelBase
 {
+    private const double MinZoom = 0.5;
+    private const double MaxZoom = 2.0;
+    private const double ZoomStep = 0.1;
+
     private readonly ILogger<DocumentationViewModel> logger;
     private readonly IDocumentationService documentationService;
+    private readonly ISettingsManager settingsManager;
 
     public override string Title => "Documentation";
 
@@ -72,6 +77,14 @@ public partial class DocumentationViewModel : PageViewModelBase
     [NotifyPropertyChangedFor(nameof(IsContentVisible))]
     private bool isDocsUnavailable;
 
+    /// <summary>Content zoom factor for the markdown viewer (1.0 = 100%). Persisted in settings.</summary>
+    [ObservableProperty]
+    [NotifyPropertyChangedFor(nameof(ZoomPercentText))]
+    public partial double ZoomFactor { get; set; }
+
+    /// <summary>Current zoom level formatted for display, e.g. "100%".</summary>
+    public string ZoomPercentText => $"{Math.Round(ZoomFactor * 100)}%";
+
     public bool HasError => !string.IsNullOrEmpty(ErrorMessage);
 
     public bool IsContentVisible => !IsDocsUnavailable;
@@ -87,24 +100,41 @@ public partial class DocumentationViewModel : PageViewModelBase
 
     private CancellationTokenSource? pageCts;
     private bool hasLoadedTree;
+    private bool hasRegisteredSettingsRelays;
 
     /// <summary>Anchor slug to scroll to after the next page load completes (cross-page anchor links).</summary>
     private string? pendingAnchor;
 
     public DocumentationViewModel(
         ILogger<DocumentationViewModel> logger,
-        IDocumentationService documentationService
+        IDocumentationService documentationService,
+        ISettingsManager settingsManager
     )
     {
         this.logger = logger;
         this.documentationService = documentationService;
+        this.settingsManager = settingsManager;
         LinkClickedCommand = new RelayCommand<string>(OnLinkClicked);
+        ZoomFactor = 1.0;
     }
 
     public override async Task OnLoadedAsync()
     {
         await base.OnLoadedAsync();
 
+        if (!hasRegisteredSettingsRelays)
+        {
+            hasRegisteredSettingsRelays = true;
+
+            // Load the persisted zoom level and keep it saved on change.
+            settingsManager.RelayPropertyFor(
+                this,
+                vm => vm.ZoomFactor,
+                settings => settings.DocumentationZoomFactor,
+                true
+            );
+        }
+
         if (!hasLoadedTree)
         {
             await LoadTreeAsync();
@@ -117,6 +147,24 @@ private async Task RetryAsync()
         await LoadTreeAsync(forceRefresh: true);
     }
 
+    [RelayCommand]
+    private void ZoomIn()
+    {
+        ZoomFactor = Math.Min(MaxZoom, Math.Round(ZoomFactor + ZoomStep, 2));
+    }
+
+    [RelayCommand]
+    private void ZoomOut()
+    {
+        ZoomFactor = Math.Max(MinZoom, Math.Round(ZoomFactor - ZoomStep, 2));
+    }
+
+    [RelayCommand]
+    private void ResetZoom()
+    {
+        ZoomFactor = 1.0;
+    }
+
     private async Task LoadTreeAsync(bool forceRefresh = false)
     {
         IsTreeLoading = true;
@@ -229,6 +277,9 @@ private async Task LoadPageAsync(string docsRelativePath, string? anchor = null)
             );
             ct.ThrowIfCancellationRequested();
 
+            // Fold code-span link text ([`Home`](url) -> [Home](url)) that the markdown
+            // renderer can't parse, then absolutize relative image URLs.
+            markdown = DocumentationPathResolver.RewriteCodeSpanLinks(markdown);
             CurrentMarkdown = DocumentationPathResolver.RewriteImageUrls(docsRelativePath, markdown);
             CurrentImageBaseUrl = GetPageFolderRawUrl(docsRelativePath);
 

StabilityMatrix.Avalonia/Views/DocumentationPage.axaml

@@ -138,10 +138,51 @@
                 <controls:DocumentationMarkdownViewer
                     x:Name="MarkdownViewer"
                     Margin="24,16"
+                    ContentZoom="{Binding ZoomFactor}"
                     ImageBaseUrl="{Binding CurrentImageBaseUrl}"
                     IsVisible="{Binding !HasError}"
                     LinkCommand="{Binding LinkClickedCommand}"
                     Markdown="{Binding CurrentMarkdown, Mode=OneWay}" />
+
+                <!--  Zoom overlay (bottom-right corner, clear of the scrollbar)  -->
+                <Border
+                    Margin="0,0,32,20"
+                    Padding="2"
+                    HorizontalAlignment="Right"
+                    VerticalAlignment="Bottom"
+                    Background="{DynamicResource CardBackgroundFillColorDefaultBrush}"
+                    BorderBrush="{DynamicResource CardStrokeColorDefaultBrush}"
+                    BorderThickness="1"
+                    CornerRadius="8"
+                    IsVisible="{Binding !HasError}">
+                    <StackPanel Orientation="Horizontal" Spacing="2">
+                        <Button
+                            Padding="6"
+                            Classes="transparent"
+                            Command="{Binding ZoomOutCommand}"
+                            ToolTip.Tip="Zoom out">
+                            <fluentAvalonia:SymbolIcon FontSize="16" Symbol="ZoomOut" />
+                        </Button>
+                        <Button
+                            MinWidth="48"
+                            Padding="6"
+                            Classes="transparent"
+                            Command="{Binding ResetZoomCommand}"
+                            ToolTip.Tip="Reset zoom">
+                            <TextBlock
+                                HorizontalAlignment="Center"
+                                FontSize="12"
+                                Text="{Binding ZoomPercentText}" />
+                        </Button>
+                        <Button
+                            Padding="6"
+                            Classes="transparent"
+                            Command="{Binding ZoomInCommand}"
+                            ToolTip.Tip="Zoom in">
+                            <fluentAvalonia:SymbolIcon FontSize="16" Symbol="ZoomIn" />
+                        </Button>
+                    </StackPanel>
+                </Border>
             </Grid>
         </Grid>
     </Grid>

StabilityMatrix.Core/Models/Documentation/DocumentationPathResolver.cs

@@ -207,6 +207,58 @@ public static string RewriteImageUrls(string currentPagePath, string markdown)
         );
     }
 
+    // Matches a (non-image) markdown link whose text contains inline code, e.g. [`Home`](../README.md)
+    private static readonly Regex CodeSpanLinkRegex = new(
+        @"(?<!!)\[(?<text>[^\]]*`[^\]]*)\]\((?<url>[^)]+)\)",
+        RegexOptions.Compiled
+    );
+
+    /// <summary>
+    /// Rewrites markdown links whose link text contains inline code spans
+    /// (e.g. <c>[`Home`](../README.md)</c>) into plain-text links (<c>[Home](../README.md)</c>),
+    /// because Markdown.Avalonia's inline parser cannot parse code spans inside link text and
+    /// renders the whole construct literally. Content inside fenced code blocks
+    /// (<c>```</c>/<c>~~~</c>) is left untouched.
+    /// </summary>
+    /// <param name="markdown">The raw markdown content.</param>
+    public static string RewriteCodeSpanLinks(string markdown)
+    {
+        if (string.IsNullOrEmpty(markdown) || !markdown.Contains('`'))
+            return markdown;
+
+        // Split into lines so fenced code blocks can be skipped; '\n' split keeps any '\r'
+        // at line ends, and rejoining with '\n' restores the original line endings.
+        var lines = markdown.Split('\n');
+        var inFence = false;
+
+        for (var i = 0; i < lines.Length; i++)
+        {
+            var trimmed = lines[i].TrimStart();
+            if (
+                trimmed.StartsWith("```", StringComparison.Ordinal)
+                || trimmed.StartsWith("~~~", StringComparison.Ordinal)
+            )
+            {
+                inFence = !inFence;
+                continue;
+            }
+
+            if (inFence)
+                continue;
+
+            lines[i] = CodeSpanLinkRegex.Replace(
+                lines[i],
+                match =>
+                {
+                    var text = match.Groups["text"].Value.Replace("`", string.Empty);
+                    return $"[{text}]({match.Groups["url"].Value})";
+                }
+            );
+        }
+
+        return string.Join('\n', lines);
+    }
+
     /// <summary>
     /// Resolves a relative image path in the current page into an absolute raw URL so it renders.
     /// </summary>

StabilityMatrix.Core/Models/Settings/Settings.cs

@@ -260,6 +260,9 @@ public IReadOnlyDictionary<string, string> EnvironmentVariables
 
     public double CivArchiveBrowserResizeFactor { get; set; } = 1.0d;
 
+    /// <summary>Content zoom factor for the in-app documentation viewer (1.0 = 100%).</summary>
+    public double DocumentationZoomFactor { get; set; } = 1.0d;
+
     public bool CivArchiveBrowserFitCardImages { get; set; } = true;
 
     public bool HideEarlyAccessModels { get; set; }

StabilityMatrix.Tests/Core/DocumentationPathResolverTests.cs

@@ -141,6 +141,48 @@ public void Slugify_ProducesGitHubStyleSlug(string input, string expected)
         Assert.AreEqual(expected, DocumentationPathResolver.Slugify(input));
     }
 
+    [TestMethod]
+    public void RewriteCodeSpanLinks_FoldsCodeSpanLinkText()
+    {
+        const string markdown = "[`Home`](../README.md) > [`Section Overview`](overview.md)";
+
+        var result = DocumentationPathResolver.RewriteCodeSpanLinks(markdown);
+
+        Assert.AreEqual("[Home](../README.md) > [Section Overview](overview.md)", result);
+    }
+
+    [TestMethod]
+    public void RewriteCodeSpanLinks_MultipleCodeSpansInOneLink_StripsAllBackticks()
+    {
+        const string markdown = "[`a` and `b`](target.md)";
+
+        var result = DocumentationPathResolver.RewriteCodeSpanLinks(markdown);
+
+        Assert.AreEqual("[a and b](target.md)", result);
+    }
+
+    [TestMethod]
+    public void RewriteCodeSpanLinks_InsideFencedCodeBlock_IsUntouched()
+    {
+        const string markdown = "before\n\n```md\n[`Home`](../README.md)\n```\n\n[`Home`](../README.md)\n";
+
+        var result = DocumentationPathResolver.RewriteCodeSpanLinks(markdown);
+
+        // The occurrence inside the fence is untouched; the one outside is rewritten.
+        StringAssert.Contains(result, "```md\n[`Home`](../README.md)\n```");
+        StringAssert.Contains(result, "\n\n[Home](../README.md)\n");
+    }
+
+    [TestMethod]
+    public void RewriteCodeSpanLinks_PlainLinksAndText_AreUntouched()
+    {
+        const string markdown = "[Home](../README.md) with `inline code` and ![`alt`](img.png) image\n";
+
+        var result = DocumentationPathResolver.RewriteCodeSpanLinks(markdown);
+
+        Assert.AreEqual(markdown, result);
+    }
+
     [TestMethod]
     public void ResolveImageUrl_RelativeParentPath_ResolvesToRawUrl()
     {