spec(047): Phase 3-final Batch G1 — flat ItemsHost ports (ListBox, ComboBox, RadioButtons)

Migrate the three flat-Items descriptors off the .OneWay<string[]>
escape-hatch and onto the ItemsHost child strategy delivered by G-prep.
The engine now dispatches ItemsHost inline between RentControl and the
prop loop, so SelectedIndex's initial write lands against a populated
collection (no more silent clamp-to-minus-one against empty Items).

Shipped:
- ListBoxDescriptor: ItemsHost flat — string[] -> IReadOnlyList<object>
  via array reference covariance; ListBoxItemsEqual helper removed.
- ComboBoxDescriptor: ItemsHost flat — string items OR Element items
  (ItemElements wins when non-null); the setter escape-hatch the prior
  port required is no longer needed for the Items population path.
- RadioButtonsDescriptor: ItemsHost flat — same string[] projection;
  RadioButtonsItemsEqual helper removed.
- Three new TAP fixtures (Desc_<Name>_Items_*) exercise the dispatch
  ordering: initial SelectedIndex honored against populated items, no
  mount-time echo, clear-to-empty + repopulate cycle, same-ref idempotent
  short-circuit.

Carved (none): all three controls fit the flat-IList<object> shape;
typed templated lists go through G2.

V1 ON: 534 ok / 0 failures
V1 OFF: 534 ok / 0 failures

Author: codemonkeychris

src/Reactor/Core/V1Protocol/Descriptor/Descriptors/ComboBoxDescriptor.cs

@@ -25,23 +25,16 @@ namespace Microsoft.UI.Reactor.Core.V1Protocol.Descriptor.Descriptors;
 ///   conditional per the legacy guards.</item>
 /// </list></para>
 ///
-/// <para><b>Known gaps vs. hand-coded handler — Items collection
-/// escape-hatched:</b> the descriptor does NOT touch <c>cb.Items</c>.
-/// ComboBox's items collection requires the legacy arm's full
-/// mode-switch logic (string[] vs Element[] keyed reconciliation
-/// against <c>requestRerender</c>) — none of which the descriptor
-/// builders can yet express. Authors who need ComboBox items must
-/// either:
-/// <list type="bullet">
-///   <item>Run under V1 OFF (legacy arm handles Items + SelectedIndex
-///   together).</item>
-///   <item>Populate <c>cb.Items</c> via a <c>.Set</c> setter chain (the
-///   setter runs after the descriptor's prop writes and can append items
-///   directly — this trades reconciliation for an imperative escape).</item>
-/// </list>
-/// The fixture exercises SelectedIndex / Header / DropDownOpened/Closed
-/// only — items are pre-populated via the setter chain to prove the
-/// descriptor's SelectedIndex write coordinates with a populated list.</para>
+/// <para><b>Items handling (Phase 3-final batch G1):</b> declared via the
+/// <see cref="ItemsHost{TElement,TControl}"/> child strategy. The engine
+/// populates <c>cb.Items</c> BEFORE the prop loop so <c>SelectedIndex</c>'s
+/// initial write lands against a populated collection. Both string items
+/// (<see cref="ComboBoxElement.Items"/>) and <see cref="Element"/> items
+/// (<see cref="ComboBoxElement.ItemElements"/>) are supported — when
+/// <c>ItemElements</c> is non-null it takes precedence and the engine routes
+/// each child through the reconciler so descendant component state survives
+/// re-renders. Reconciliation is positional (clear + add on structural
+/// delta); keyed reconciliation for templated lists lands in batch G2.</para>
 /// </summary>
 [Experimental("REACTOR_V1_PREVIEW")]
 internal static class ComboBoxDescriptor
@@ -63,7 +56,18 @@ internal static class ComboBoxDescriptor
     public static readonly ControlDescriptor<ComboBoxElement, WinUI.ComboBox> Descriptor =
         new ControlDescriptor<ComboBoxElement, WinUI.ComboBox>
         {
-            Children = new None<ComboBoxElement, WinUI.ComboBox>(),
+            // §14 Phase 3-final batch G1: items declared as a child strategy.
+            // Engine dispatches BEFORE the prop loop so the initial
+            // SelectedIndex write lands against a populated collection.
+            // ItemElements takes precedence when non-null (typed Element
+            // items → engine routes through Reconciler.MountChild); otherwise
+            // the string[] items are used. Both casts are valid via array
+            // reference covariance (reference element types).
+            Children = new ItemsHost<ComboBoxElement, WinUI.ComboBox>(
+                GetItems: static e => e.ItemElements is not null
+                    ? (global::System.Collections.Generic.IReadOnlyList<object>)e.ItemElements
+                    : (global::System.Collections.Generic.IReadOnlyList<object>)e.Items,
+                GetCollection: static c => c.Items),
             GetSetters = static e => e.Setters,
         }
         .HandCodedControlled<ComboBoxEventPayload, int, WinUI.SelectionChangedEventHandler>(

src/Reactor/Core/V1Protocol/Descriptor/Descriptors/ListBoxDescriptor.cs

@@ -5,15 +5,17 @@
 namespace Microsoft.UI.Reactor.Core.V1Protocol.Descriptor.Descriptors;
 
 /// <summary>
-/// Spec 047 §14 Phase 3 (batch 11) — descriptor variant of the hand-coded
-/// <c>MountListBox</c> / <c>UpdateListBox</c> arms in
-/// <see cref="Reconciler"/>.
+/// Spec 047 §14 Phase 3 (batch 11; revised in Phase 3-final batch G1) —
+/// descriptor variant of the hand-coded <c>MountListBox</c> /
+/// <c>UpdateListBox</c> arms in <see cref="Reconciler"/>.
 ///
 /// <para><b>Coverage:</b>
 /// <list type="bullet">
-///   <item><c>Items</c> — one-way Clear + Add cycle gated on a sequence
-///   compare (mirrors the legacy <c>StringArrayEquals</c> guard). Same
-///   non-keyed shape as <see cref="RadioButtonsDescriptor"/>.</item>
+///   <item><c>Items</c> — declared via the
+///   <see cref="ItemsHost{TElement,TControl}"/> child strategy. The engine
+///   populates the items collection BEFORE the prop loop runs (see
+///   <see cref="DescriptorHandler{TElement,TControl}"/>), so
+///   <c>SelectedIndex</c>'s initial write lands against a populated list.</item>
 ///   <item><c>SelectedIndex</c> — <see cref="ControlDescriptor{TElement,TControl}.HandCodedControlled{TPayload,TValue,TDelegate}"/>
 ///   with a typed <c>SelectionChanged</c> trampoline. The trampoline fires
 ///   BOTH <c>OnSelectedIndexChanged</c> and the multi-select snapshot
@@ -22,7 +24,7 @@ namespace Microsoft.UI.Reactor.Core.V1Protocol.Descriptor.Descriptors;
 /// </list></para>
 ///
 /// <para><b>Known gaps vs. hand-coded handler:</b> Items reconciliation is
-/// non-keyed (full rebuild on any sequence delta). Acceptable for short
+/// non-keyed (full rebuild on any structural delta). Acceptable for short
 /// ListBoxes (typical 3–15 options).</para>
 /// </summary>
 [Experimental("REACTOR_V1_PREVIEW")]
@@ -51,19 +53,20 @@ internal static class ListBoxDescriptor
     public static readonly ControlDescriptor<ListBoxElement, WinUI.ListBox> Descriptor =
         new ControlDescriptor<ListBoxElement, WinUI.ListBox>
         {
-            Children = new None<ListBoxElement, WinUI.ListBox>(),
+            // §14 Phase 3-final batch G1: items declared as a child strategy.
+            // The engine dispatches ItemsHost BEFORE the prop loop, so
+            // SelectedIndex's initial write lands against the populated
+            // collection (WinUI clamps SelectedIndex against an empty
+            // Items collection).
+            //
+            // string[] -> IReadOnlyList<object> is valid via array reference
+            // covariance (reference element types only) — zero-alloc and the
+            // cast never throws at runtime for empty or non-empty arrays.
+            Children = new ItemsHost<ListBoxElement, WinUI.ListBox>(
+                GetItems:      static e => (global::System.Collections.Generic.IReadOnlyList<object>)e.Items,
+                GetCollection: static c => c.Items),
             GetSetters = static e => e.Setters,
         }
-        // Items BEFORE SelectedIndex so SelectedIndex lands against the
-        // populated collection.
-        .OneWay<string[]>(
-            get: static e => e.Items,
-            set: static (c, items) =>
-            {
-                if (ListBoxItemsEqual(c.Items, items)) return;
-                c.Items.Clear();
-                foreach (var item in items) c.Items.Add(item);
-            })
         .HandCodedControlled<ListBoxEventPayload, int, WinUI.SelectionChangedEventHandler>(
             get:         static e => e.SelectedIndex,
             set:         static (c, v) => c.SelectedIndex = v,
@@ -81,17 +84,4 @@ e.OnSelectedIndexChanged is not null
             trampoline:  SelectionChangedTrampoline,
             slotIsNull:  static p => p.SelectionChangedTrampoline is null,
             setSlot:     static (p, h) => p.SelectionChangedTrampoline = h);
-
-    private static bool ListBoxItemsEqual(
-        global::Microsoft.UI.Xaml.Controls.ItemCollection existing, string[] incoming)
-    {
-        if (existing.Count != incoming.Length) return false;
-        for (int i = 0; i < incoming.Length; i++)
-        {
-            if (!ReferenceEquals(existing[i], incoming[i])
-                && existing[i] as string != incoming[i])
-                return false;
-        }
-        return true;
-    }
 }

src/Reactor/Core/V1Protocol/Descriptor/Descriptors/RadioButtonsDescriptor.cs

@@ -18,12 +18,14 @@ namespace Microsoft.UI.Reactor.Core.V1Protocol.Descriptor.Descriptors;
 ///   gates on <c>ChangeEchoSuppressor.ShouldSuppress(c)</c> so programmatic
 ///   index writes don't echo through <c>OnSelectedIndexChanged</c>.</item>
 ///   <item><c>Header</c> — one-way conditional per the legacy guard.</item>
-///   <item><c>Items</c> — escape-hatched via a transparent <c>OneWay</c> entry
-///   that runs a Clear + Add cycle when the new array differs by reference
-///   OR by content. This matches the legacy <c>StringArrayEquals</c> guard
-///   but does NOT do keyed reconciliation — every item-change replaces the
-///   full list (acceptable for a RadioButtons control whose typical use is
-///   3–7 fixed options).</item>
+///   <item><c>Items</c> — declared via the
+///   <see cref="ItemsHost{TElement,TControl}"/> child strategy (Phase 3-final
+///   batch G1). The engine populates the items collection BEFORE the prop
+///   loop runs, so <c>SelectedIndex</c>'s initial write lands against a
+///   populated list (WinUI clamps SelectedIndex against an empty Items
+///   collection). Reconciliation is positional (clear + add on structural
+///   delta) — acceptable for a RadioButtons control whose typical use is
+///   3–7 fixed options.</item>
 /// </list></para>
 ///
 /// <para><b>Known gaps vs. hand-coded handler:</b>
@@ -48,30 +50,17 @@ internal static class RadioButtonsDescriptor
     public static readonly ControlDescriptor<RadioButtonsElement, WinUI.RadioButtons> Descriptor =
         new ControlDescriptor<RadioButtonsElement, WinUI.RadioButtons>
         {
-            Children = new None<RadioButtonsElement, WinUI.RadioButtons>(),
+            // §14 Phase 3-final batch G1: items declared as a child strategy.
+            // The engine dispatches ItemsHost BEFORE the prop loop so the
+            // initial SelectedIndex write lands against a populated list
+            // (WinUI clamps SelectedIndex against Items.Count). string[] ->
+            // IReadOnlyList<object> is valid via array reference covariance
+            // (reference element types only).
+            Children = new ItemsHost<RadioButtonsElement, WinUI.RadioButtons>(
+                GetItems:      static e => (global::System.Collections.Generic.IReadOnlyList<object>)e.Items,
+                GetCollection: static c => c.Items),
             GetSetters = static e => e.Setters,
         }
-        // Items BEFORE SelectedIndex so the index is honored against the
-        // populated list (WinUI clamps SelectedIndex against Items.Count).
-        // We pull the string array, populate eagerly each pass, and rely on
-        // .HandCodedControlled to gate the index write.
-        .OneWay<string[]>(
-            get: static e => e.Items,
-            set: static (c, items) =>
-            {
-                // Idempotent in steady state: if the existing items match
-                // by sequence we skip the rebuild. This mirrors the legacy
-                // StringArrayEquals guard without round-tripping through a
-                // separate compare in the descriptor framework.
-                if (RadioButtonsItemsEqual(c.Items, items)) return;
-                // RadioButtons.Items.Clear / Add raises SelectionChanged
-                // (template-driven SelectedIndex coercion) — both the
-                // descriptor and the legacy arm let this echo through to
-                // OnSelectedIndexChanged. Documented gap; the fixture
-                // bounds the count rather than asserting zero.
-                c.Items.Clear();
-                foreach (var item in items) c.Items.Add(item);
-            })
         .HandCodedControlled<RadioButtonsEventPayload, int, WinUI.SelectionChangedEventHandler>(
             get:         static e => e.SelectedIndex,
             set:         static (c, v) => c.SelectedIndex = v,
@@ -85,17 +74,4 @@ internal static class RadioButtonsDescriptor
             get:         static e => e.Header,
             set:         static (c, v) => c.Header = v,
             shouldWrite: static e => e.Header is not null);
-
-    private static bool RadioButtonsItemsEqual(
-        global::System.Collections.Generic.IList<object> existing, string[] incoming)
-    {
-        if (existing.Count != incoming.Length) return false;
-        for (int i = 0; i < incoming.Length; i++)
-        {
-            if (!ReferenceEquals(existing[i], incoming[i])
-                && existing[i] as string != incoming[i])
-                return false;
-        }
-        return true;
-    }
 }