MarkdownTextBlock: address review feedback (PR #785)

- Revert WriteText buffer-growth change to pre-PR implementation; defer the
  allocation optimization to a follow-up (review comment).
- Expose the rerender flag through Build(bool rerender = true) so callers can
  tune document reload behavior deliberately.
- Clarify the theme-update coalescing intent in OnThemePropertyChanged /
  OnActualThemeChanged comments.
- Make MyImage(HtmlNode, MarkdownTextBlock) control non-nullable and drop the
  related null suppression.
- Shorten RichTextBlock <see cref> references in MyFlowDocument so the correct
  MUX/WUX type resolves via global usings.
- Document that ImageMaxWidth/ImageMaxHeight default of 0 means 'no constraint'.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: niels9001

components/MarkdownTextBlock/src/MarkdownTextBlock.Properties.cs

@@ -157,8 +157,17 @@ private static void OnIsTextSelectionEnabledChanged(DependencyObject d, Dependen
 
     // ── Theme DPs ───────────────────────────────────────────────────────
     // Defaults come from the XAML style. C# defaults are type-appropriate
-    // fallbacks only. The shared property-changed callback batches multiple
-    // simultaneous DP updates (e.g. theme switch) into a single re-render.
+    // fallbacks only.
+    //
+    // The shared property-changed callback coalesces the burst of synchronous
+    // DP updates produced by a single theme/style swap into one re-render. DP
+    // callbacks fire synchronously on the UI thread, so the first update queues
+    // a single re-render on the dispatcher and flips _themePropertyChangeQueued;
+    // the remaining updates in the same burst are skipped by the flag. Because
+    // the queued callback only runs after the current synchronous work drains,
+    // ApplyText executes exactly once, after every property has been applied.
+    // The flag is shared with OnActualThemeChanged so the theme event and the
+    // DP updates it triggers collapse into the same single re-render.
 
     private static void OnThemePropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
     {

components/MarkdownTextBlock/src/MarkdownTextBlock.xaml

@@ -220,7 +220,7 @@
         <Setter Property="QuoteCornerRadius" Value="4" />
         <Setter Property="QuoteBarMargin" Value="0,0,4,0" />
 
-        <!--  Image properties  -->
+        <!--  Image properties (0 = no max constraint; image uses its natural / markdown-specified size)  -->
         <Setter Property="ImageMaxWidth" Value="0" />
         <Setter Property="ImageMaxHeight" Value="0" />
         <Setter Property="ImageStretch" Value="Uniform" />

components/MarkdownTextBlock/src/MarkdownTextBlock.xaml.cs

@@ -69,6 +69,9 @@ private void OnUnloaded(object sender, RoutedEventArgs e)
 
     private void OnActualThemeChanged(FrameworkElement sender, object args)
     {
+        // Coalesces with the theme DP callbacks (see OnThemePropertyChanged):
+        // the shared flag collapses this event and the DP updates it triggers
+        // into a single re-render queued on the dispatcher.
         if (!_themePropertyChangeQueued)
         {
             _themePropertyChangeQueued = true;
@@ -121,7 +124,7 @@ private void ApplyText(bool rerender)
         }
     }
 
-    private void Build()
+    private void Build(bool rerender = true)
     {
         if (_renderer == null)
         {
@@ -155,6 +158,6 @@ private void Build()
         }
         _pipeline.Setup(_renderer);
 
-        ApplyText(true);
+        ApplyText(rerender);
     }
 }

components/MarkdownTextBlock/src/Renderers/WinUIRenderer.cs

@@ -118,10 +118,14 @@ public void WriteText(string? text, int offset, int length)
         {
             if (length > _buffer.Length)
             {
-                _buffer = new char[Math.Max(length, _buffer.Length * 2)];
+                _buffer = text.ToCharArray();
+                WriteText(new string(_buffer, offset, length));
+            }
+            else
+            {
+                text.CopyTo(offset, _buffer, 0, length);
+                WriteText(new string(_buffer, 0, length));
             }
-            text.CopyTo(offset, _buffer, 0, length);
-            WriteText(new string(_buffer, 0, length));
         }
     }
 

components/MarkdownTextBlock/src/TextElements/MyFlowDocument.cs

@@ -15,7 +15,7 @@
 namespace CommunityToolkit.WinUI.Controls.TextElements;
 
 /// <summary>
-/// Represents a flow document that wraps a <see cref="Microsoft.UI.Xaml.Controls.RichTextBlock"/> for rendering markdown or HTML content.
+/// Represents a flow document that wraps a <see cref="RichTextBlock"/> for rendering markdown or HTML content.
 /// </summary>
 public class MyFlowDocument : IAddChild
 {
@@ -26,7 +26,7 @@ public class MyFlowDocument : IAddChild
     /// <summary>Gets or sets the text element (unused, required by <see cref="IAddChild"/>).</summary>
     public TextElement TextElement { get; set; } = new Run();
 
-    /// <summary>Gets or sets the underlying <see cref="Microsoft.UI.Xaml.Controls.RichTextBlock"/>.</summary>
+    /// <summary>Gets or sets the underlying <see cref="RichTextBlock"/>.</summary>
     public RichTextBlock RichTextBlock
     {
         get => _richTextBlock;

components/MarkdownTextBlock/src/TextElements/MyImage.cs

@@ -51,17 +51,15 @@ public MyImage(LinkInline linkInline, Uri uri, MarkdownTextBlock control)
         }
     }
 
-#pragma warning disable CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider declaring as nullable.
-    public MyImage(HtmlNode htmlNode, MarkdownTextBlock? control)
-#pragma warning restore CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider declaring as nullable.
+    public MyImage(HtmlNode htmlNode, MarkdownTextBlock control)
     {
 #pragma warning disable CS8601 // Possible null reference assignment.
         Uri.TryCreate(htmlNode.GetAttribute("src", "#"), UriKind.RelativeOrAbsolute, out _uri);
 #pragma warning restore CS8601 // Possible null reference assignment.
         _htmlNode = htmlNode;
-        _imageProvider = control?.ImageProvider;
-        _svgRenderer = control?.SVGRenderer ?? _defaultSvgRenderer;
-        _control = control!;
+        _imageProvider = control.ImageProvider;
+        _svgRenderer = control.SVGRenderer ?? _defaultSvgRenderer;
+        _control = control;
         Init();
         int.TryParse(
             htmlNode.GetAttribute("width", "0"),