spec(047): Phase 3-final — §14 progress note + tracker close-out

Documents the eight Phase 3-final batches (A engine shapes; B Frame /
RichTextBlock / NumberBox; C CalendarView via CollectionDiffControlled;
D Button-family Flyout via OneWayBridged + CreateFlyoutForDescriptor;
E Panel per-child attached props + WrapGrid; F Image events / Path.Data
/ InfoBar.ActionButton; G-prep ItemsHost IList<object> typing +
descriptor-side ordering fix; G1 flat ItemsHost ports for ListBox /
ComboBox / RadioButtons) and the deliberate carve-outs to Phase 4
(Expander.HeaderTemplate, RelativePanel per-child attached,
TeachingTip.Target, Path.PathDataString, NumberBox coercion, and the
G2/G3 templated lists which need a new TemplatedItems strategy +
spec-042 keyed-reconcile integration). Tracker marks the Batch
3-followup line as addressed via Phase 3-final Batches B and C.

ARM64 stable-AC re-capture on LAPTOP-4MEP83VI remains deferred for the
§14 ratification gate (unchanged from Phase 3 advisory state).

Author: codemonkeychris

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

@@ -1376,6 +1376,28 @@ See §13 Q1 for the full capture lineage and matrix application. Raw data under
 - Phase 3 follow-ups (need new builder/entry shapes — separate spec-reviewed PR): `NumberBox` (Immediate-mode keystroke + `NumberFormatter` ref-equality), `RichTextBlock` (incremental Paragraphs/Inlines diff), `FrameElement` (mount-only entry shape), `CalendarViewElement` (collection-diff with per-element echo). Within-control partial-port gaps (Flyout children, items collections, per-child attached props, IconSource, Path.Data) tracked in `docs/specs/tasks/047-extensible-control-model-implementation.md`. Templated lists (`ListView`, `GridView`, `TreeView`, `FlipView`, `TabView`, `Pivot`, `ItemsRepeater`) require spec-042 keyed reconciliation integrated into `ItemsHost`.
 - Phase 3 advisory perf — final x64 capture under `docs/specs/047/phase3-results/CPC-ander-YTZ3O-x64-advisory/2026-05-27-phase3-final-3x5/` (50 controls registered, 3×5 launches). V1 ON (descriptors) vs V1 OFF (today) headline: M1 +14.9%, M7 +7.4%, M8 +25.5%, M10 +8.7%, M11 +8.5%, M12 +20.9% — descriptor-interpreter Mount/Update overhead amortized over the larger registration table. M4 −21.2% / M5 −24.3% — dispatch wins from a fatter handler table (fewer fallthroughs to the legacy switch arm). Cloud-PC advisory only; ARM64 stable-AC re-capture on `LAPTOP-4MEP83VI` is deferred for the §14 ratification gate.
 
+**Phase 3-final descriptor scale-out** (delivers the follow-ups listed above + within-control partial-port gaps from PR #435 batches 3–11):
+
+- **Batch A — engine shapes** (`.OneWayBridged`, `.Immediate`, `.CollectionDiffControlled`, `Panel.PerChildAttached`, `ItemsHost<TElement,TControl>` flat, `Reconciler.CreateFlyoutForDescriptor`). Carries no controls; enables the rest.
+- **Batch B** — `FrameElement` (.HandCodedEvent triple — gates on callback-at-mount; legacy unconditional subscription stays preferable for late-attached callbacks), `RichTextBlockElement` (reference-equality rebuild on Paragraphs; legacy incremental per-paragraph diff stays preferable for authors needing the incremental shape), `NumberBoxElement` (plain `.OneWay` Min/Max; `.CoercingOneWay` not threaded — see follow-up).
+- **Batch C** — `CalendarViewElement` via `.CollectionDiffControlled`. Null `SelectedDates` is treated as empty (descriptor clears the vector); legacy treats null as uncontrolled (preserves user picks) — call sites must pass a list whenever selection is controlled.
+- **Batch D** — `DropDownButton`/`SplitButton`/`ToggleSplitButton` Flyout child via `.OneWayBridged` + `Reconciler.CreateFlyoutForDescriptor`.
+- **Batch E** — `Grid`/`Canvas`/`FlexPanel` per-child attached props via `Panel.PerChildAttached`; `WrapGrid` via a tailored panel shape.
+- **Batch F** — `ImageElement` `ImageOpened`/`ImageFailed` via `.HandCodedEvent`; `PathElement` pre-built `Geometry Data` via `.OneWayConditional` (gated on `PathDataString` being null); `InfoBarElement.ActionButton` via `.OneWayBridged` with a Click trampoline.
+- **Batch G-prep — engine ordering fix.** `ItemsHost.GetCollection` retyped from `System.Collections.IList` to `IList<object>` (WinUI `ItemCollection` does not implement the non-generic projection under CsWinRT). `DescriptorHandler` now dispatches `ItemsHost` inline between `RentControl` and the prop loop on Mount, and before the prop loop on Update, so selection-tracking initial writes (`SelectedIndex`/`SelectedItem`) land against a populated collection. Strategy shape unchanged for hand-coded handlers (V1HandlerAdapter dispatch path kept).
+- **Batch G1 — flat `ItemsHost` ports.** `ListBoxElement`, `ComboBoxElement`, `RadioButtonsElement` migrate from `.OneWay<string[]>` items entries to `Children = new ItemsHost<...>(...)`. `ComboBoxElement.ItemElements` (`Element[]?`) supported alongside `Items` (`string[]`); the engine routes `Element` items through `MountChild`.
+
+**Phase 3-final carve-outs to Phase 4** (cannot be expressed inside the current engine shape; explicit reasons):
+
+- **Expander.HeaderTemplate** — needs `NamedSlots` but conflicts with the existing `SingleContent` strategy; one Children strategy per descriptor today.
+- **RelativePanel per-child attached** — sequential `PerChildAttached` callbacks can't resolve sibling name references that haven't been mounted yet. Needs a two-pass shape on `Panel<>` or a dedicated `NamedRelativePanel` strategy.
+- **TeachingTip.Target** — cross-element reference resolution to another element's mounted native control; descriptor framework cannot reference another element's resolved control.
+- **PathElement.PathDataString** — legacy `XamlReader`/`PathDataParser` strategy needs string-diff against the old element + multi-source error context the engine's per-prop comparer can't express.
+- **NumberBox coercion** — `Minimum`/`Maximum` ship as plain `.OneWay`; `.CoercingOneWay` could be wired later.
+- **Templated lists (G2/G3)** — `ListView<T>`, `GridView<T>`, `LazyVStack<T>`, `LazyHStack<T>`, `ItemsRepeater<T>`, `TreeView`, `FlipView`, `TabView`, `Pivot` need a new `TemplatedItems<T,TControl>` (or equivalent) strategy with spec-042 `ReactorListState` + `KeyedListDiff` integration plus a `Reconciler.BindKeyedItemsSource` helper lifting the legacy realization-hook setup. Substantial engine design work; deferred to a follow-up batch.
+
+ARM64 stable-AC re-capture on `LAPTOP-4MEP83VI` remains deferred for the §14 ratification gate.
+
 **Carry-forward known defects from Phase 1:**
 - **KD-3** — dispatch fast-path for the ported built-ins (M4 was +88.9% V1 vs Today at Phase 1; final advisory shows M4 −21.2% / M5 −24.3% at amortized scope — KD-3 has materially closed at the batch-11 registration set).
 - **KD-4** — public typed-event surface for external descriptor authors. Scope narrowed by Phase 2 to external-author-only; in-tree descriptors already use the internal fast path via `DescriptorControlledPayload<T>` or `.HandCodedControlled`/`.HandCodedEvent` per-descriptor payload pattern.

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

@@ -751,15 +751,93 @@ shrink lands after V1 ships ON by default.
         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). `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).
+- [x] Batch 3-followup — addressed by Phase 3-final Batch B (`Frame`,
+      `RichTextBlock`, `NumberBox`) and Batch C (`CalendarView`). Engine
+      shapes (`.Immediate`, `.OneWayBridged`, `.CollectionDiffControlled`)
+      added in Phase 3-final Batch A. Documented residual carve-outs
+      retained — see Phase 3-final batch entries below.
+
+**Phase 3-final descriptor scale-out** (delivers the Phase 3 follow-ups
+plus within-control partial-port gaps from PR #435 batches 3–11):
+
+- [x] **Batch A — engine shapes.** Added `.OneWayBridged<TValue>` (set
+      lambda gets `(TControl, TValue, Reconciler, Action requestRerender)`
+      — for dynamically-constructed child controls), `.Immediate<TPayload>`
+      (pure subscription wiring), `.CollectionDiffControlled` (`IList<T>`
+      two-way with hash-set diff under `BeginSuppress`),
+      `Panel<>.PerChildAttached`, `ItemsHost<TElement,TControl>` (flat),
+      and `Reconciler.CreateFlyoutForDescriptor`. Engine-only commit —
+      no controls.
+- [x] **Batch B** — `Frame`, `RichTextBlock`, `NumberBox`.
+      - **Frame** — three `.HandCodedEvent` subscriptions
+        (`Navigated`/`Navigating`/`NavigationFailed`) gate on
+        callback-at-mount. Legacy `MountFrame` subscribes unconditionally
+        so late-attached callbacks fire through. Common case covered;
+        authors who attach callbacks after Mount stay on V1 OFF.
+      - **RichTextBlock** — `Paragraphs` rebuild via reference-equality.
+        Legacy `UpdateRichTextBlock` does incremental per-paragraph diff;
+        authors needing the incremental shape stay on V1 OFF.
+      - **NumberBox** — plain `.OneWay` `Minimum`/`Maximum` (no coercion
+        suppression). `.CoercingOneWay` could be wired later.
+- [x] **Batch C** — `CalendarView` via `.CollectionDiffControlled`.
+      Null `SelectedDates` is treated as empty list (descriptor clears
+      the vector); legacy treats null as uncontrolled (preserves user
+      picks). Call sites must pass a list whenever selection is
+      controlled.
+- [x] **Batch D** — `DropDownButton`/`SplitButton`/`ToggleSplitButton`
+      Flyout child via `.OneWayBridged` + `Reconciler.CreateFlyoutForDescriptor`.
+      Closes the Batch 4 Flyout escape-hatch.
+- [x] **Batch E** — `Grid`/`Canvas`/`FlexPanel` per-child attached props
+      via `Panel.PerChildAttached`; `WrapGrid` ported with a tailored
+      panel shape. Closes the Batch 8 per-child attached gap (except
+      `RelativePanel` — see carve-outs).
+- [x] **Batch F** — `Image` events (`ImageOpened`/`ImageFailed` via
+      `.HandCodedEvent` over the existing `ImageEventPayload`),
+      `Path.Data` (pre-built `Geometry` via `.OneWayConditional` gated
+      on `PathDataString` being null), `InfoBar.ActionButton` (via
+      `.OneWayBridged` with a Click trampoline).
+- [x] **Batch G-prep — engine ordering fix.**
+      `ItemsHost.GetCollection` retyped from `System.Collections.IList`
+      to `IList<object>` (WinUI `ItemCollection` does not implement the
+      non-generic projection under CsWinRT). `DescriptorHandler` now
+      dispatches `ItemsHost` inline between `RentControl` and the prop
+      loop on Mount, and before the prop Update loop on Update, so
+      selection-tracking initial writes (`SelectedIndex`/`SelectedItem`)
+      land against a populated collection. Strategy shape unchanged for
+      hand-coded handlers — V1HandlerAdapter dispatch path is preserved.
+- [x] **Batch G1 — flat `ItemsHost` ports.** `ListBox`, `ComboBox`,
+      `RadioButtons` migrate from `.OneWay<string[]>` items entries to
+      `Children = new ItemsHost<...>(GetItems: e => (IReadOnlyList<object>)e.Items, GetCollection: c => c.Items)`.
+      `ComboBox.ItemElements` (`Element[]?`) supported alongside `Items`
+      (`string[]`); the engine routes `Element` items through
+      `MountChild`. Fixtures: `Desc_ListBox_Items`, `Desc_ComboBox_Items`,
+      `Desc_RadioButtons_Items`.
+
+**Phase 3-final carve-outs to Phase 4** (cannot be expressed inside the
+current engine shape; explicit reasons):
+
+- [ ] **Expander.HeaderTemplate** — needs `NamedSlots` but conflicts with
+      the existing `SingleContent` strategy; one Children strategy per
+      descriptor today.
+- [ ] **RelativePanel per-child attached** — sequential `PerChildAttached`
+      callbacks can't resolve sibling name references that haven't been
+      mounted yet. Needs a two-pass shape on `Panel<>` or a dedicated
+      `NamedRelativePanel` strategy.
+- [ ] **TeachingTip.Target** — cross-element reference resolution to
+      another element's mounted native control; descriptor framework
+      cannot reference another element's resolved control.
+- [ ] **Path.PathDataString** — legacy `XamlReader`/`PathDataParser`
+      strategy needs string-diff against the old element + multi-source
+      error context the engine's per-prop comparer can't express.
+- [ ] **NumberBox coercion** — `.CoercingOneWay` thread for `Minimum` /
+      `Maximum`.
+- [ ] **Templated lists (G2/G3)** — `ListView<T>`, `GridView<T>`,
+      `LazyVStack<T>`, `LazyHStack<T>`, `ItemsRepeater<T>`, `TreeView`,
+      `FlipView`, `TabView`, `Pivot` need a new `TemplatedItems<T,TControl>`
+      (or equivalent) strategy with spec-042 `ReactorListState` +
+      `KeyedListDiff` integration plus a `Reconciler.BindKeyedItemsSource`
+      helper lifting the legacy realization-hook setup. Substantial engine
+      design work; deferred to a follow-up batch.
 
 **Carry-forward known defects** (from Phase 1):