spec(047): Phase 3 batch 11 — Long-tail descriptors

Long-tail triage ports: PipsPager, ListBox, SelectorBar, BreadcrumbBar.
Escape-hatched: FrameElement (imperative Navigate API is Mount-only and
descriptor builders have no mount-only entry shape), CalendarViewElement
(SelectedDates is an IObservableVector requiring per-element
ChangeEchoSuppressor tokens that the builders don't express).

Documented gaps:
- PipsPager fires SelectedIndexChanged as NumberOfPages widens past the
  default; the descriptor's HandCodedControlled suppression covers its
  own SelectedPageIndex write but not the prior OneWay NumberOfPages
  write. Fixture bounds the mount-fire count rather than asserting zero
  (legacy mount has the same window — it writes NumberOfPages before
  subscribing).
- ListBox / SelectorBar Items reconciliation is non-keyed (full Clear +
  Add cycle on any sequence delta). Acceptable for short lists; the
  legacy SelectorBar arm does an in-place prefix patch which the
  descriptor builders don't yet express.
- BreadcrumbBar mirrors the legacy mount + update: both unconditionally
  rebuild a label list and assign to ItemsSource.
- See `docs/specs/tasks/047-extensible-control-model-implementation.md`
  Batch 11 entry + the deferred follow-ups list for the two
  escape-hatched controls.

Self-test V1 ON/OFF: Desc_ 52/52 pass, 0 failures. Full suite under
both V1 ON and V1 OFF: 1002/1002 pass, 0 failures.

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

Author: codemonkeychris

docs/specs/tasks/047-extensible-control-model-implementation.md

@@ -700,12 +700,66 @@ shrink lands after V1 ships ON by default.
         every `Update*` write and the element's default zero values; the
         visible output is the same for callers who never set them. No
         behavior delta for non-zero callers.
+- [x] **Batch 11** — Long-tail triage: `PipsPager`, `ListBox`,
+      `SelectorBar`, `BreadcrumbBar` ported. `FrameElement` and
+      `CalendarViewElement` deferred (escape-hatched).
+      Fixtures: `Desc_PipsPager_MountUpdate`, `Desc_ListBox_MountUpdate`,
+      `Desc_SelectorBar_MountUpdate`, `Desc_BreadcrumbBar_MountUpdate` —
+      all pass under V1 ON and V1 OFF.
+      **Ported (4):**
+      - **PipsPager** — `SelectedPageIndex` round-trip via
+        `.HandCodedControlled` against the new `PipsPagerEventPayload`;
+        `NumberOfPages` / `WrapMode` / `MaxVisiblePips` /
+        `PreviousButtonVisibility` / `NextButtonVisibility` as
+        `.OneWay`. Trampoline gates on `ChangeEchoSuppressor`.
+      - **ListBox** — `Items` (non-keyed Clear+Add cycle on sequence
+        delta, mirroring `RadioButtonsDescriptor`) + `SelectedIndex`
+        round-trip. The single `SelectionChanged` trampoline fires
+        BOTH `OnSelectedIndexChanged` and the multi-select snapshot
+        `OnSelectionChanged` — matches the legacy arm's twin-invoke
+        shape, including the `IndexOf`-against-Items snapshot
+        reconstruction.
+      - **SelectorBar** — `Items` cycle (Text + Icon per item) +
+        `SelectedIndex` round-trip mapped through `SelectedItem` ref
+        (SelectorBar exposes `SelectedItem`, not `SelectedIndex`, as
+        the live property). Item icon resolution reuses
+        `Reconciler.ResolveIconForDescriptor` via a
+        `SymbolIconData` wrapper.
+      - **BreadcrumbBar** — `Items` → `ItemsSource` (label list) +
+        `ItemClicked` fire-only event. Trampoline maps
+        `args.Index` back to `el.Items[idx]` per the legacy arm.
+      **Escape-hatched (2) — documented gaps:**
+      - **FrameElement** — `Navigate(SourcePageType, NavigationParameter)`
+        is an imperative API call invoked only at Mount time (the
+        legacy `UpdateFrame` is just `SetElementTag` + `ApplySetters`,
+        no re-navigate). The descriptor builders don't distinguish
+        mount-only writes from update writes — a `.OneWay` for
+        `SourcePageType` would re-Navigate on every update pass.
+        The 3 events (`Navigated`, `Navigating`, `NavigationFailed`)
+        could be ported in isolation, but a descriptor that handles
+        only events while losing the Mount-time navigation would be
+        a regression vs. V1 OFF. Authors who need declarative `Frame`
+        stay on V1 OFF; future work is a mount-only entry shape.
+      - **CalendarViewElement** — `SelectedDates` is an
+        `IObservableVector<DateTimeOffset>` collection that the legacy
+        arm mutates element-by-element with per-mutation
+        `ChangeEchoSuppressor.BeginSuppress` tokens
+        (`UpdateCalendarView` → `SyncSelectedDates`: a hash-set diff
+        with one suppress per Add/Remove). The descriptor builders
+        don't express collection diffs with per-element suppression
+        — a single `.OneWay` write to `SelectedDates` would either
+        echo per element or require a custom collection-aware entry
+        shape. Authors who need declarative multi-date selection stay
+        on V1 OFF.
 - [ ] Batch 3-followup — `NumberBox` (needs Immediate-mode keystroke
       handling + `NumberFormatter` reference-equality semantics that the
       descriptor builders don't yet express — likely needs a new entry
       shape or a `HandCoded*` path). `RichTextBlock` (incremental
       paragraph/inline diffing — needs a child-strategy or new entry
-      shape).
+      shape). `FrameElement` (needs a Mount-only entry shape for
+      imperative `Navigate` calls — see Batch 11). `CalendarViewElement`
+      (needs a collection-diff entry shape with per-element echo
+      suppression — see Batch 11).
 
 **Carry-forward known defects** (from Phase 1):
 

src/Reactor/Core/V1Protocol/ControlEventPayloads.cs

@@ -230,6 +230,48 @@ internal sealed class TeachingTipEventPayload
         object>? ActionButtonClickTrampoline;
 }
 
+/// <summary>Spec 047 §14 Phase 3 batch 11 — PipsPager SelectedPageIndex
+/// round-trip payload. Single slot: <c>SelectedIndexChanged</c> is the only
+/// event we surface; the descriptor uses <see cref="ChangeEchoSuppressor"/>
+/// to drain the programmatic write.</summary>
+internal sealed class PipsPagerEventPayload
+{
+    public global::Windows.Foundation.TypedEventHandler<
+        Microsoft.UI.Xaml.Controls.PipsPager,
+        Microsoft.UI.Xaml.Controls.PipsPagerSelectedIndexChangedEventArgs>? SelectedIndexChangedTrampoline;
+}
+
+/// <summary>Spec 047 §14 Phase 3 batch 11 — ListBox SelectedIndex round-trip
+/// payload. The single <c>SelectionChanged</c> trampoline fires BOTH the
+/// element's <c>OnSelectedIndexChanged</c> and (if present) the
+/// <c>OnSelectionChanged</c> snapshot callback — mirrors the legacy
+/// <c>MountListBox</c> arm's twin-invoke shape.</summary>
+internal sealed class ListBoxEventPayload
+{
+    public Microsoft.UI.Xaml.Controls.SelectionChangedEventHandler? SelectionChangedTrampoline;
+}
+
+/// <summary>Spec 047 §14 Phase 3 batch 11 — SelectorBar SelectedIndex
+/// round-trip payload. <c>SelectionChanged</c> trampoline reads the live
+/// SelectedItem reference and converts back to the index via
+/// <c>Items.IndexOf</c> to feed <c>OnSelectedIndexChanged</c>.</summary>
+internal sealed class SelectorBarEventPayload
+{
+    public global::Windows.Foundation.TypedEventHandler<
+        Microsoft.UI.Xaml.Controls.SelectorBar,
+        Microsoft.UI.Xaml.Controls.SelectorBarSelectionChangedEventArgs>? SelectionChangedTrampoline;
+}
+
+/// <summary>Spec 047 §14 Phase 3 batch 11 — BreadcrumbBar ItemClicked
+/// fire-only payload. Trampoline maps <c>args.Index</c> back to the live
+/// element's <c>Items[idx]</c> data — mirrors the legacy arm.</summary>
+internal sealed class BreadcrumbBarEventPayload
+{
+    public global::Windows.Foundation.TypedEventHandler<
+        Microsoft.UI.Xaml.Controls.BreadcrumbBar,
+        Microsoft.UI.Xaml.Controls.BreadcrumbBarItemClickedEventArgs>? ItemClickedTrampoline;
+}
+
 /// <summary>
 /// Spec 047 §9.2 — open-ended anchor for delegates registered via
 /// <see cref="ReactorBinding{TElement}.OnCustomEvent{TArgs}"/>. Holds a

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

@@ -0,0 +1,53 @@
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using Microsoft.UI.Xaml;
+using Windows.Foundation;
+using WinUI = Microsoft.UI.Xaml.Controls;
+
+namespace Microsoft.UI.Reactor.Core.V1Protocol.Descriptor.Descriptors;
+
+/// <summary>
+/// Spec 047 §14 Phase 3 (batch 11) — descriptor variant of the hand-coded
+/// <c>MountBreadcrumbBar</c> / <c>UpdateBreadcrumbBar</c> arms in
+/// <see cref="Reconciler"/>.
+///
+/// <para><b>Coverage:</b>
+/// <list type="bullet">
+///   <item><c>Items</c> — one-way <c>ItemsSource</c> assignment of a label
+///   list. The descriptor rebuilds the label list on each pass and assigns
+///   it to <c>ItemsSource</c> (mirrors the legacy mount + update arms,
+///   which both unconditionally do the same).</item>
+///   <item><c>ItemClicked</c> — <see cref="ControlDescriptor{TElement,TControl}.HandCodedEvent{TPayload,TDelegate}"/>.
+///   The trampoline maps <c>args.Index</c> back to the live element's
+///   <c>Items[idx]</c> data — matches the legacy hand-coded mapping.</item>
+/// </list></para>
+/// </summary>
+[Experimental("REACTOR_V1_PREVIEW")]
+internal static class BreadcrumbBarDescriptor
+{
+    private static readonly TypedEventHandler<WinUI.BreadcrumbBar, WinUI.BreadcrumbBarItemClickedEventArgs>
+        ItemClickedTrampoline = (s, args) =>
+        {
+            var bar = (WinUI.BreadcrumbBar)s!;
+            if (Reconciler.GetElementTag(bar) is not BreadcrumbBarElement el) return;
+            if (args.Index >= 0 && args.Index < el.Items.Length)
+                el.OnItemClicked?.Invoke(el.Items[args.Index]);
+        };
+
+    public static readonly ControlDescriptor<BreadcrumbBarElement, WinUI.BreadcrumbBar> Descriptor =
+        new ControlDescriptor<BreadcrumbBarElement, WinUI.BreadcrumbBar>
+        {
+            Children = new None<BreadcrumbBarElement, WinUI.BreadcrumbBar>(),
+            GetSetters = static e => e.Setters,
+        }
+        .OneWay<BreadcrumbBarItemData[]>(
+            get: static e => e.Items,
+            set: static (c, items) => c.ItemsSource = items.Select(i => i.Label).ToList())
+        .HandCodedEvent<BreadcrumbBarEventPayload,
+            TypedEventHandler<WinUI.BreadcrumbBar, WinUI.BreadcrumbBarItemClickedEventArgs>>(
+            subscribe:        static (c, h) => c.ItemClicked += h,
+            callbackPresent:  static e => e.OnItemClicked,
+            trampoline:       ItemClickedTrampoline,
+            slotIsNull:       static p => p.ItemClickedTrampoline is null,
+            setSlot:          static (p, h) => p.ItemClickedTrampoline = h);
+}

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

@@ -0,0 +1,93 @@
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.UI.Xaml;
+using WinUI = Microsoft.UI.Xaml.Controls;
+
+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"/>.
+///
+/// <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>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
+///   <c>OnSelectionChanged</c> — matches the legacy mount arm's twin-invoke
+///   shape.</item>
+/// </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
+/// ListBoxes (typical 3–15 options).</para>
+/// </summary>
+[Experimental("REACTOR_V1_PREVIEW")]
+internal static class ListBoxDescriptor
+{
+    private static readonly WinUI.SelectionChangedEventHandler SelectionChangedTrampoline = (s, _) =>
+    {
+        var lb = (WinUI.ListBox)s!;
+        if (ChangeEchoSuppressor.ShouldSuppress(lb)) return;
+        if (Reconciler.GetElementTag(lb) is not ListBoxElement el) return;
+        el.OnSelectedIndexChanged?.Invoke(lb.SelectedIndex);
+        if (el.OnSelectionChanged is { } h)
+        {
+            var snapshot = new global::System.Collections.Generic.List<int>(lb.SelectedItems.Count);
+            for (int i = 0; i < lb.SelectedItems.Count; i++)
+            {
+                var idx = lb.Items.IndexOf(lb.SelectedItems[i]);
+                if (idx >= 0) snapshot.Add(idx);
+            }
+            h(snapshot);
+        }
+    };
+
+    public static readonly ControlDescriptor<ListBoxElement, WinUI.ListBox> Descriptor =
+        new ControlDescriptor<ListBoxElement, WinUI.ListBox>
+        {
+            Children = new None<ListBoxElement, WinUI.ListBox>(),
+            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,
+            readBack:    static c => c.SelectedIndex,
+            subscribe:   static (c, h) => c.SelectionChanged += h,
+            // Gate is "either callback is present" — match the legacy
+            // mount arm's HasCallbacks semantics so a ListBox with only the
+            // snapshot subscriber still wires.
+            callback:    static e =>
+                e.OnSelectedIndexChanged is not null
+                    ? e.OnSelectedIndexChanged
+                    : (e.OnSelectionChanged is not null ? _ => { } : 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/PipsPagerDescriptor.cs

@@ -0,0 +1,71 @@
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.UI.Xaml;
+using Windows.Foundation;
+using WinUI = Microsoft.UI.Xaml.Controls;
+
+namespace Microsoft.UI.Reactor.Core.V1Protocol.Descriptor.Descriptors;
+
+/// <summary>
+/// Spec 047 §14 Phase 3 (batch 11) — descriptor variant of the hand-coded
+/// <c>MountPipsPager</c> / <c>UpdatePipsPager</c> arms in
+/// <see cref="Reconciler"/>. Single-event round-trip on
+/// <c>SelectedPageIndex</c>.
+///
+/// <para><b>Coverage:</b>
+/// <list type="bullet">
+///   <item><c>SelectedPageIndex</c> — <see cref="ControlDescriptor{TElement,TControl}.HandCodedControlled{TPayload,TValue,TDelegate}"/>
+///   with a typed <c>SelectedIndexChanged</c> trampoline gated on
+///   <see cref="ChangeEchoSuppressor"/>. Mirrors the legacy guard's
+///   programmatic-write semantics.</item>
+///   <item><c>NumberOfPages</c>, <c>WrapMode</c>, <c>MaxVisiblePips</c>,
+///   <c>PreviousButtonVisibility</c>, <c>NextButtonVisibility</c> — one-way
+///   per legacy.</item>
+/// </list></para>
+/// </summary>
+[Experimental("REACTOR_V1_PREVIEW")]
+internal static class PipsPagerDescriptor
+{
+    private static readonly TypedEventHandler<WinUI.PipsPager, WinUI.PipsPagerSelectedIndexChangedEventArgs>
+        SelectedIndexChangedTrampoline = (s, _) =>
+        {
+            var p = (WinUI.PipsPager)s!;
+            if (ChangeEchoSuppressor.ShouldSuppress(p)) return;
+            (Reconciler.GetElementTag(p) as PipsPagerElement)
+                ?.OnSelectedPageIndexChanged?.Invoke(p.SelectedPageIndex);
+        };
+
+    public static readonly ControlDescriptor<PipsPagerElement, WinUI.PipsPager> Descriptor =
+        new ControlDescriptor<PipsPagerElement, WinUI.PipsPager>
+        {
+            Children = new None<PipsPagerElement, WinUI.PipsPager>(),
+            GetSetters = static e => e.Setters,
+        }
+        // NumberOfPages BEFORE SelectedPageIndex so the index lands against
+        // the widened range (WinUI clamps SelectedPageIndex against
+        // NumberOfPages).
+        .OneWay(
+            get: static e => e.NumberOfPages,
+            set: static (c, v) => c.NumberOfPages = v)
+        .HandCodedControlled<PipsPagerEventPayload, int,
+            TypedEventHandler<WinUI.PipsPager, WinUI.PipsPagerSelectedIndexChangedEventArgs>>(
+            get:         static e => e.SelectedPageIndex,
+            set:         static (c, v) => c.SelectedPageIndex = v,
+            readBack:    static c => c.SelectedPageIndex,
+            subscribe:   static (c, h) => c.SelectedIndexChanged += h,
+            callback:    static e => e.OnSelectedPageIndexChanged,
+            trampoline:  SelectedIndexChangedTrampoline,
+            slotIsNull:  static p => p.SelectedIndexChangedTrampoline is null,
+            setSlot:     static (p, h) => p.SelectedIndexChangedTrampoline = h)
+        .OneWay(
+            get: static e => e.WrapMode,
+            set: static (c, v) => c.WrapMode = v)
+        .OneWay(
+            get: static e => e.MaxVisiblePips,
+            set: static (c, v) => c.MaxVisiblePips = v)
+        .OneWay(
+            get: static e => e.PreviousButtonVisibility,
+            set: static (c, v) => c.PreviousButtonVisibility = v)
+        .OneWay(
+            get: static e => e.NextButtonVisibility,
+            set: static (c, v) => c.NextButtonVisibility = v);
+}