#20259 - three things a reviewer would have found first

ContentVirtualizationDiagnostics -> ContainerVirtualization: a behaviour
kill switch does not belong in a class named for diagnostics. Pure
rename, no call site changed shape.

DataTemplate.MinPoolSizePerKey gets a setter. It is documented as the
warmup-depth knob and was unreachable from the markup meant to configure
it, while MaxPoolSizePerKey one line above was settable and
FuncDataTemplate.MinPoolSizePerKey already was.

AdjustElementSize stops being a protected internal virtual test seam.
The protected half made it public API by accident and nothing in
production wants to change a measured size, so it is now the internal
ElementSizeAdjustmentForTesting delegate, applied in GetElementSizeU
where the method was called.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: alexander.marek

src/Avalonia.Controls/ItemsControl.cs

@@ -474,7 +474,7 @@ protected internal virtual void ClearContainerForItemOverride(Control container)
                 // the same condition NeedsContainer<T> keys on.
                 // When we skip clearing, the Child stays attached to this container
                 var shouldSkipClear = cc.Presenter != null &&
-                                      ContentVirtualizationDiagnostics.IsEnabled &&
+                                      ContainerVirtualization.IsEnabled &&
                                       Presenter?.Panel is VirtualizingStackPanel &&
                                       cc.ContentTemplate is IVirtualizingDataTemplate vdt &&
                                       vdt.GetKey(cc.Content) != null;
@@ -494,7 +494,7 @@ cc.ContentTemplate is IVirtualizingDataTemplate vdt &&
                 // only for a template that opted in by handing out a recycle key for this item -
                 // the same condition NeedsContainer<T> keys on.
                 // When we skip clearing, the Child stays attached to this container
-                var shouldSkipClear = ContentVirtualizationDiagnostics.IsEnabled &&
+                var shouldSkipClear = ContainerVirtualization.IsEnabled &&
                                       Presenter?.Panel is VirtualizingStackPanel &&
                                       p.ContentTemplate is IVirtualizingDataTemplate vdt &&
                                       vdt.GetKey(p.Content) != null;
@@ -576,7 +576,7 @@ protected bool NeedsContainer<T>(object? item, out object? recycleKey) where T :
             // for this item. Keys partition the container pool so a container is only ever reused
             // for data that its retained Child can display. Anything else falls through to stock
             // behaviour - a single shared pool under DefaultRecycleKey.
-            if (ContentVirtualizationDiagnostics.IsEnabled &&
+            if (ContainerVirtualization.IsEnabled &&
                 Presenter?.Panel is VirtualizingStackPanel &&
                 GetEffectiveItemTemplate() is IVirtualizingDataTemplate vdt &&
                 vdt.GetKey(item) is { } key)
@@ -982,9 +982,9 @@ bool IChildIndexProvider.TryGetTotalCount(out int count)
     }
 
     /// <summary>
-    /// Provides diagnostics for content virtualization.
+    /// Global switch for opt-in container-level virtualization.
     /// </summary>
-    public static class ContentVirtualizationDiagnostics
+    public static class ContainerVirtualization
     {
         /// <summary>
         /// Gets or sets whether container-level virtualization is globally enabled.

src/Avalonia.Controls/VirtualizingStackPanel.cs

@@ -1526,29 +1526,29 @@ private double GetOrEstimateElementU(int index)
         }
 
         /// <summary>
-        /// Called after each element is measured during realization. Override in tests
-        /// to simulate non-deterministic measurement (async image loading, text wrapping)
-        /// by returning a modified size. The default implementation returns the measured
-        /// size unchanged.
+        /// Test-only seam applied to every size the panel reads off an element, so a test can
+        /// simulate non-deterministic measurement (async image loading, text wrapping) without a
+        /// template that actually behaves that way. Takes the item index and the measured size in
+        /// the layout orientation, and returns the size the panel should use.
         /// </summary>
-        /// <param name="index">The item index.</param>
-        /// <param name="measuredSizeU">The element's measured size in the layout orientation.</param>
-        /// <returns>The size to use for layout. Defaults to <paramref name="measuredSizeU"/>.</returns>
-        protected internal virtual double AdjustElementSize(int index, double measuredSizeU)
-            => measuredSizeU;
+        /// <remarks>
+        /// Deliberately internal and not a <c>protected virtual</c> method: nothing in production
+        /// wants to change a measured size, so this must not become public API.
+        /// </remarks>
+        internal Func<int, double, double>? ElementSizeAdjustmentForTesting { get; set; }
 
         /// <summary>
         /// The panel's single view of an element's size along the layout axis. Every place that
         /// records or re-checks a size must go through here: if size *recording* applied
-        /// <see cref="AdjustElementSize"/> but size *checking* did not, the two would disagree by
-        /// the adjustment on every pass and each pass would look like a fresh resize.
+        /// <see cref="ElementSizeAdjustmentForTesting"/> but size *checking* did not, the two would
+        /// disagree by the adjustment on every pass and each pass would look like a fresh resize.
         /// </summary>
         private double GetElementSizeU(Control element, int index)
         {
             var sizeU = Orientation == Orientation.Horizontal
                 ? element.DesiredSize.Width
                 : element.DesiredSize.Height;
-            return AdjustElementSize(index, sizeU);
+            return ElementSizeAdjustmentForTesting is { } adjust ? adjust(index, sizeU) : sizeU;
         }
 
         private void RealizeElements(

src/Markup/Avalonia.Markup.Xaml/Templates/DataTemplate.cs

@@ -28,11 +28,11 @@ public class DataTemplate : IRecyclingDataTemplate, ITypedDataTemplate, IVirtual
         public int MaxPoolSizePerKey { get; set; } = 5;
 
         /// <summary>
-        /// Gets the minimum number of controls to keep in the recycle pool
+        /// Gets or sets the minimum number of controls to keep in the recycle pool
         /// for each key. Default is 2.
         /// This is only used when warmup is enabled
         /// </summary>
-        public int MinPoolSizePerKey { get; } = 2;
+        public int MinPoolSizePerKey { get; set; } = 2;
 
         public bool Match(object? data)
         {

tests/Avalonia.Controls.UnitTests/ContainerVirtualizationTests.cs

@@ -74,17 +74,43 @@ public void MaxPoolSizePerKey_Is_Respected_For_DataTemplate_With_EnableVirtualiz
             Assert.Equal(2, PooledCount(panel));
         }
 
+        /// <summary>
+        /// <c>MinPoolSizePerKey</c> is the warmup-depth knob, and the markup it is meant to be
+        /// configured from is a XAML <c>DataTemplate</c> - so it has to be settable there and the
+        /// value has to reach <c>DiscoverTemplateKeys</c>, which is the only thing that reads it.
+        /// </summary>
+        [Fact]
+        public void MinPoolSizePerKey_Set_On_A_DataTemplate_Reaches_Warmup()
+        {
+            using var app = App();
+
+            var template = CanvasTemplate(enableVirtualization: true, dataType: typeof(TypeA_Item));
+            template.MinPoolSizePerKey = 7;
+            var items = CreateItems<TypeA_Item>(200);
+
+            var (panel, _, _, _) = CreateTarget(items, template);
+
+            var keys = panel.DiscoverTemplateKeys();
+
+            Assert.True(keys.TryGetValue(typeof(TypeA_Item), out var depth),
+                "The template's key was never encountered, so warmup depth was not resolved at all.");
+
+            // 3 is DefaultWarmupPoolSizePerKey - i.e. what this asserts is that the template was
+            // asked, not that some default happened to match.
+            Assert.Equal(7, depth);
+        }
+
         // ===== (c) IsEnabled = false is a kill switch back to stock behaviour =====
 
         [Fact]
         public void IsEnabled_False_Forces_Default_Recycle_Key_And_Clears_Content()
         {
             using var app = App();
-            var original = ContentVirtualizationDiagnostics.IsEnabled;
+            var original = ContainerVirtualization.IsEnabled;
 
             try
             {
-                ContentVirtualizationDiagnostics.IsEnabled = false;
+                ContainerVirtualization.IsEnabled = false;
 
                 // A template that opts in and keys per item type - with the kill switch off it must
                 // be ignored entirely.
@@ -122,7 +148,7 @@ public void IsEnabled_False_Forces_Default_Recycle_Key_And_Clears_Content()
             }
             finally
             {
-                ContentVirtualizationDiagnostics.IsEnabled = original;
+                ContainerVirtualization.IsEnabled = original;
             }
         }