Fully Extensible Control Model — Implementation Tasks

Derived from: docs/specs/047-extensible-control-model.md

Status: Phase 0 complete (PR #414 — greenlight). Phase 1 code-complete in PR #414 — see 047-extensible-control-model-phase1-implementation.md for the per-section tracker and ../047/phase1-results/ for the Phase 1 deliverables, exit-gate deferrals (1.17 AOT publish, 1.18 macro catch-up, 1.19 final perf validation — all gated on baseline-machine runs), and the Q14 dispatcher-affinity note.

Phase 2 complete (2026-05-26). §13 Q1 resolved — descriptors are the primary first-party surface; hand-coded IElementHandler<,> is the escape hatch. Stable-AC capture landed the worst gating bench (M2) at +9.6%, inside the 5-15% judgment-call band; LOC (~24% saving at Phase 3 scope) and §6.1 readability resolved the call to descriptors. Three captures documented under ../047/phase2-results/LAPTOP-4MEP83VI/; the 2026-05-26-q1-fastpath-3x5-stableac/ capture is authoritative. See "Phase 2 wrap-up" and "Phase 3 prerequisites" sections below.

Phase 3 complete (PR #440); Phase 4 code-complete — V1 is the unconditional production path; migration closed. The full close-out is tracked in 047-extensible-control-model-phase4-implementation.md. Landed: 100% V1 registration + the production flip (§4.0/§4.1); legacy MountXxx/UpdateXxx switch + all A|B/UseV1Protocol dead code deleted (§4.5/§4.6); the public author surface graduated out of [Experimental] + locked, KD-4 closed (§4.7); the §8 echo path migrated to a value-diff/counter hybrid (ChangeEchoSuppressor intentionally retained, spec §8.3); the §9 EventHandlerState split into ModifierEventHandlerState + per-control ControlEventStateBox (§4.3); the §11.7 bucketed Element base (ElementExtras) + the §11.6 byte-gate target constants (§4.4); and the final author docs (§4.8). Outstanding (baseline-machine-only, partially landed): the ARM64 stable-AC perf ratification (§4.9) and the §11.6 hard byte-gate measurement/enforcement (§4.4). An indicative ARM64 capture landed on LAPTOP-4MEP83VI (PR #465, 047/phase4-results/.../2026-05-29-arm64/): the deterministic allocation axis is now measured — M2/M3 meet the §15.6 "≤ Today" budget, but M1 regressed +20% (and M1/M2 miss the absolute 407/1,520 B gates; M3 passes); M12 +17% also regressed. The timing axis and the macro suite (L1–L14) are still unratified (no §15.5 isolation; macro projects deleted in Phase 4), so a full sign-off + the M1/M12 alloc fix remain open. Full x64 correctness validation green throughout (build / xunit 9128 / selftests).

Phase 0 below is spec-process work — audits, suite infrastructure, baseline measurements, and decision criteria. It cleared its exit gate (PR #414) and Phase 1 (v1 protocol behind a feature flag, 5 ported controls + external assembly proof, Roslyn analyzer, public author surface) shipped on top. See spec §14 for the phase boundaries and §15 for the perf suite this phase stood up.

This file converts spec 047's Phase 0 deliverables (spec §14) into ship-ready, pause/resume-able tasks. Each top-level deliverable maps to one section below. Tasks are intentionally narrow so the work can be checkpointed between sessions without losing context.

Conventions:

Audit outputs land under docs/specs/047/audits/ (new folder — create as part of 0.1).
Baseline measurement outputs land under docs/specs/047/baseline-results/ (per spec §14 Phase 0 exit gate).
Perf suite scaffolding follows the existing tests/stress_perf/, tests/startup_perf/, and tests/perf_bench/ patterns. New variants are added alongside (not replacing) existing ones — see spec §15.2.
Phase 0 produces no production code changes to Reactor.dll other than what is needed for the ReactorV2 skeleton (which is initially a copy of Reactor so the V2 numbers ≈ Today numbers at the start of Phase 1).
A task is "done" only when its output (CSV, markdown audit doc, scaffolded project that builds, baseline JSON-Lines file, etc.) is committed under the paths above. Audit decisions referenced by later phases must be unambiguous in writing — Phase 1+ should not need to re-derive them.

Phase 0 exit gate (from spec §14):

All seven deliverables below complete.
Baseline numbers committed to docs/specs/047/baseline-results/.
Spec §11 / §12 updated with measured numbers replacing estimates.
Factoring recommendation (0.7) reviewed and either ratified or executed.

Until that gate clears, the proposal does not move to greenlight.

0.1 `BeginSuppress` audit

Spec §14 deliverable 1. Drives the §8 / §8.1 decision and the controlled/uncontrolled/initial classification in §6.1. Output is a CSV the descriptor design in Phase 1 can consult directly.

Create docs/specs/047/audits/ (new folder).
Grep every BeginSuppress call site in the tree. Capture file + line + surrounding control name + property being written.
For each call site, classify into exactly one of:
- eliminable-tight-diff — already gated by oldEl.X != newEl.X (or trivially can be); suppression is redundant.
- coercion — control coerces the written value (e.g., Slider.Value against Maximum); the change event fires with a value the engine did not write.
- float-precision — engine writes 0.3, control stores 0.30000001.
- reference-equality — engine writes a reference whose Equals semantics don't match the control's internal storage.
- focus-prop — IsTabStop / FocusState / programmatic Focus().
- items-coercion — SelectedIndex etc. coerced by a shrunken items collection.
- animation-tick — interpolated intermediate values fire change events mid-storyboard.
- user-state-races-render — only resolvable by §8.1's mostRecentEventCount round-trip.
Write docs/specs/047/audits/begin-suppress-audit.csv with columns: file, line, control, property, category, notes.
Write a one-page summary (begin-suppress-audit.md) tallying counts per category and identifying any cases that don't fit the schema above (extend the schema if needed; don't force-fit). Added one category: defensive-redundant.
Cross-link from spec §8 (add a "see audit results" footnote referencing the CSV path).

0.2 `EventHandlerState` field audit

Spec §14 deliverable 2. Drives the §9.2 split between ModifierEventHandlerState (shared, routed-input) and per-control payloads inside ControlEventStateBox.

Inventory every Current<EventName> and <EventName>Trampoline field on EventHandlerState (Reconciler.cs:2787+ — line drifted +7 from §3 citation; covered by 0.5). Include the WinUI event each maps to.
For each field, classify into exactly one of routed-input-modifier, control-intrinsic, hybrid-or-ambiguous. Result: 42 routed-input, 9 control-intrinsic, 0 hybrid.
Write docs/specs/047/audits/event-handler-state-audit.csv with columns: field, winui-event, owning-control, category, target-location, notes.
Sketch the per-control payload structs that fall out of the audit. 7 structs (ToggleSwitch, Button, TextBox, Image, ScrollViewer, ScrollView, NumberBox) documented in event-handler-state-audit.md.
Confirm the §9.4 hypothesis is testable from the audit data alone — 7/7 controls have only control-intrinsic events. Frequency claim ("~90% of tree controls have no user modifiers") deferred to M11.

0.3 Perf validation suite — infrastructure

Spec §14 deliverable 3 + spec §15. Builds the scaffolding before any V2 implementation exists, so Phase 1 work shows up as the delta.

0.3.1 `StressPerf.ReactorV2` skeleton

Add tests/stress_perf/StressPerf.ReactorV2/ as a near-verbatim copy of tests/stress_perf/StressPerf.Reactor/. The point at Phase-0 freeze is "V2 numbers ≈ Today numbers" — the only intentional differences are the project name, output executable name, and any namespace renames needed to coexist with the original project in a side-by-side run.
Wire the new project into Reactor.slnx. Confirm it builds clean.
Confirm StressPerf.ReactorV2.exe launches and runs the same scenario surface as StressPerf.Reactor.exe. No correctness regression.

0.3.2 `BlankReactorV2` for startup perf

Add tests/startup_perf/BlankReactorV2/ alongside BlankReactor / BlankRNW / BlankWinUI3. Mirrors BlankReactor exactly at Phase 0.
Confirm it appears in whatever startup-perf orchestration script enumerates the blank apps (search for BlankReactor references).

0.3.3 `PerfBench.ControlModel` — micro suite harnesses

Spec §15.3 defines M1 through M13. Each test ships in three implementations (spec §15.2: Direct, ReactorToday, ReactorV2). At Phase 0 the ReactorV2 implementation is intentionally identical to ReactorToday.

0.3.4 Macro suite L1–L11

Spec §15.4. L12 (hot-reload) defers to Phase 2. L13 / L14 (split-library + AOT) defer to Phase 1 since they need a real external assembly. Each macro ships as a separate executable per the stress_perf shape.

Per-scenario status is consolidated in docs/specs/047/macro-suite-status.md. Phase 0 ships full L1 coverage (BlankWinUI3 + BlankReactor + BlankReactorV2), two-way coverage of L6 and L10 via the existing stress_perf shape, and written scenario contracts for L2 / L3 so Phase 1 implementations don't drift. L4/L5/L7–L9/L11 deferred to Phase 1 with explicit rationale captured in the status doc.

0.3.5 Reporting aggregator

Implement the JSON-Lines collector — one row per (scenario, variant, repetition). Ships as tools/spec047-aggregator.
Implement the comparison emitter producing the three §15.6 tables: (a) absolute comparison Direct / ReactorToday / ReactorV2, (b) Reactor delta (V2 vs Today % with CI), (c) WinUI gap (V2 vs Direct absolute).
Implement the per-PR trend output for CI (trend.csv). CI wiring itself is deferred to Phase 1 — Phase 0 ships the format and a local dotnet run --project tools/spec047-aggregator invocation.
Confirm result rows with mismatched environment metadata are flagged as non-comparable. Architecture is the load-bearing axis at Phase 0 (groups keyed by (BenchId, Variant, Architecture) so ARM64-native and x64-emulated runs cannot silently mix). LockedRefreshHz / PowerState / WindowOccluded rejection is deferred to Phase 1 per perf-suite-runbook.md.

0.3.6 Environment isolation runbook

Spec §15.5. Existing memory entries (reference_stress_perf_window_throttling.md, reference_stress_perf_drr_battery.md) capture invariants the suite must respect.

Write docs/specs/047/perf-suite-runbook.md capturing the operator-side requirements (foreground, AC, DRR off, no virtual-desktop switches, power plan, priority/affinity, warm-up policy).
Cross-reference the two existing memory entries in the runbook so future operators land at the same source of truth.

0.4 Baseline numbers — capture `Direct` and `ReactorToday`

Spec §14 deliverable 4. The gap between Direct and ReactorToday is the budget this spec proposes to close.

Identify two representative machines — Phase 0 captured LAPTOP-4MEP83VI (Snapdragon X laptop, x64-emulated). Workstation x64 + ARM64-native captures deferred to Phase 1 per baseline-results/machines.md.
Run the §15.3 micro suite (M1–M13) on LAPTOP-4MEP83VI capturing Direct, ReactorToday, ReactorV2. Three result files under docs/specs/047/baseline-results/LAPTOP-4MEP83VI/2026-05-25/.
Run the §15.4 macro suite (L1–L11) — deferred per macro-suite-status.md; only L1 ships at Phase 0 and its TTFF capture is deferred to Phase 1's first promotion PR.
Commit raw JSON-Lines outputs under docs/specs/047/baseline-results/LAPTOP-4MEP83VI/2026-05-25/.
Commit the comparison-table markdown — summary.md + aggregator output under aggregator-out/.
Update spec §11.6 — measured numbers now anchor the target table; original estimates preserved as a footnote.
Update spec §12 — opening paragraph footnotes the Phase 0 anchor; per-section measured numbers cross-link to baseline-results/.

0.5 Existing-API surface inventory

Spec §14 deliverable 5. Confirms Appendix A's mapping is current.

Walk the internal members named in spec §3 and Appendix A. Line-number drift cataloged in existing-api-surface.md; ApplyThemeBindings and ApplyResourceOverrides have drifted from internal (per spec) to private (current). Suggested §3 / App A edits captured in the audit.
Search the in-repo RegisterType callers — 8 sites enumerated. In-tree sites use SetElementTag only; the two samples (Monaco, regedit) use Tag directly and bypass the engine machinery. Two docking sites flagged for follow-up in the Phase 1 promotion PR.
Write docs/specs/047/audits/existing-api-surface.md with the promote-vs-stay-internal mapping.

0.6 Decision criteria for §13 open questions

Spec §14 deliverable 6. Each question that the suite can disambiguate gets a written success criterion before Phase 1, so decisions flow from data rather than re-litigation.

Write docs/specs/047/decision-criteria.md covering Q1, Q3, Q6, Q7, Q9, Q11, Q12, Q14, Q17, Q18, Q19. Q17/Q18/Q19 ratified from §13 recommendations (Q17 revised: no override mechanism in v1, throw on any duplicate registration). Q3 incorporates the audit findings (recommend ship "delete + tight diff" + per-control tolerance + ColorPicker shim; do NOT build §8.1). Q9 / Q12 / Q14 added during Phase 0 review: no override verb in v1 (Q9), void Update(...) forbidding substitution (Q12), UI-thread-only protocol (Q14).
For each criterion, link the relevant §15 test(s) and the spec section that absorbs the decision when made.

0.7 Spec factoring decision

Spec §14 deliverable 7. After Phase 0 produces audit results and baseline numbers, decide whether to keep spec 047 unified or split it.

Write docs/specs/047/factoring-recommendation.md with the recommendation. Outcome: keep spec 047 unified. The reviewer's proposed split was addressed bucket-by-bucket; only the §8.2 setter-echo fix is carved out (small standalone PR ahead of Phase 1).
Factor in the three signals — answers captured in the recommendation.
Recommendation is committed for review alongside the other Phase 0 deliverables. No split executed; nothing to rename in this task file.

Phase 0 exit checklist

When every item below is checked, the Phase 0 exit gate clears and the proposal can move to greenlight (spec §14).

0.1 BeginSuppress audit CSV + summary committed.
0.2 EventHandlerState field audit CSV + per-control struct sketches committed.
0.3 Perf suite scaffolding builds clean. M1–M13 ship with all three variants (Direct / ReactorToday / ReactorV2; V2 ≡ Today at Phase 0). L1 ships three-way; L6 / L10 ship two-way; the rest are contract-frozen and deferred to Phase 1 per macro-suite-status.md. Aggregator produces the §15.6 (a)/(b)/(c) tables locally.
0.4 Baseline JSON-Lines + summary committed under docs/specs/047/baseline-results/; spec §11 and §12 cite measured numbers. Phase 0 captures ARM64-native on LAPTOP-4MEP83VI; workstation x64 deferred to Phase 1 per machines.md.
0.5 Existing-API surface inventory committed.
0.6 Decision criteria committed for Q1, Q3, Q6, Q7, Q9, Q11, Q12, Q14, Q17, Q18, Q19. Q2 / Q4 / Q5 / Q10 / Q13 / Q15 / Q16 are either suite-deferred (Q15 → L12), strategically deferred (Q2 AOT, Q10 compile-time validation, Q13 modifier precedence), or already documented in the spec (Q16 in §16, Q4 / Q5 design questions for Phase 2). Q8 is implicitly captured via the §8.2 carve-out in factoring-recommendation.md.
0.7 Factoring recommendation committed and reviewed. Outcome: keep spec 047 unified; only the §8.2 setter-suppression fix is carved out as a standalone PR ahead of Phase 1. (Carve-out landed: ApplySetters now runs inside a scope-based suppression scope on the control's ReactorState. M13 flipped from OnIsOnChangedFireCount = 1 to 0.)

Phase 2 wrap-up — §13 Q1 measurement gate

Phase 2 is the descriptor-vs-handler head-to-head per spec §14. Exit gate: the §13 Q1 decision matrix produces an answer.

2.1 Build ControlDescriptor<TElement, TControl> interpreter under src/Reactor/Core/V1Protocol/Descriptor/ (fluent builder, PropEntry types, DescriptorHandler<,>). Internal-access fast path via Reconciler.GetOrCreateControlEventPayload<DescriptorControlledPayload<…>>.
2.2 Implement the three Q1 controls as descriptors against the same v1 protocol surface as the hand-coded ports: ToggleSwitchDescriptor (1 controlled event), SliderDescriptor (1 controlled + 2 coercing one-way), BorderDescriptor (zero events). Behavior parity verified by 23/23 Desc_* AppTests.Host self-test assertions; Phase 1 V1_* fixtures still 20/20.
2.3 Run §15.3 micro suite (M1, M2, M5, M7, M10) across all three variants (ReactorToday / ReactorV2 / ReactorDescriptors). Three captures committed under docs/specs/047/phase2-results/LAPTOP-4MEP83VI/: - 2026-05-26-q1-spike-5x5/ — pre-fast-path baseline (5×5). Public OnCustomEvent path. Verdict at the time: ship hand-coded (M2 +19.1%, M10 +31.5%). - 2026-05-26-q1-fastpath-3x5/ — internal typed-payload fast path (3×5). Capture noisy (M1 +23.5% on a TextBlock that doesn't engage the descriptor path — flagged as suspect at the time). - 2026-05-26-q1-fastpath-3x5-stableac/ — authoritative. Same code as the noisy capture, stable AC + foreground, 3×5. M2 +9.6%, no gating bench exceeds 15%.
2.4 Apply the §13 Q1 decision matrix to the authoritative capture. Worst gating bench M2 at +9.6% — judgment-call band. LOC + readability inputs resolved to descriptors (~24% LOC saving at Phase 3 scope; §6.1 classifications visible at call sites).
2.5 Spec edits committed: §13 Q1 status flipped to "Resolved"; §6.1 extended with .HandCodedControlled / .HandCodedEvent classifications (§6.1.1); §9.2 extended with per-descriptor TPayload composition (§9.2.1); §14 Phase 2 marked complete and Phase 3 prerequisites added; decision-criteria.md Q1 marked Resolved.

Phase 2 exit gate met. Descriptors are the primary first-party surface going forward (§6.1). Hand-coded IElementHandler<,> stays as escape hatch for irregular controls, perf-critical mount paths, and multi-event composition (§6.1.1).

Phase 3 prerequisites — multi-event composition + author guidance

Before Phase 3 bulk-ports the ~60 remaining controls (spec §14 Phase 3 order), these prerequisites must land. They follow from the Phase 2 verdict + the single-slot ControlEventStateBox constraint identified during the Phase 2 spec discussion (see §9.2.1).

3.0.1 Shipped .HandCodedControlled / .HandCodedEvent builders and the HandCodedControlledPropEntry / HandCodedEventPropEntry classes (PR #424). Author supplies the static trampoline + typed slot accessors per §6.1.1.
3.0.2 Ported TextBox as the 2-event proof point (TextChanged + SelectionChanged) using the shared TextBoxEventPayload (PR #424). AppTests.Host self-test fixtures (Desc_TextBox_*) cover both events independently and together.
3.0.3 Re-benched M2 / M10 against the TextBox descriptor port (PR #424, x64 advisory capture under docs/specs/047/phase3-results/CPC-ander-YTZ3O-x64-advisory/2026-05-27-textbox-proof-3x5/). ARM64 stable-AC ratification on LAPTOP-4MEP83VI deferred — protocol captured in the same dir's README.
3.0.4 Phase 3 author onboarding doc: lift the §6.1.1 classification table verbatim, plus a worked example (TextBox descriptor walk-through) and the "when to fall through to IElementHandler<,>" guidance. Land under docs/guide/ once the path is committed. Deferred — not gating the bulk-port; can land any later session.

Phase 3 bulk-port progress

Tracks per-family descriptor ports against the §14 migration order. Each batch is a single PR landing the descriptors + self-test fixtures + bench factory registration. Legacy MountXxx / UpdateXxx arms stay in place while V1 is flag-gated (V1-OFF authors still hit the legacy path); shrink lands after V1 ships ON by default.

Value-bearing family

Phase 3-final descriptor scale-out (delivers the Phase 3 follow-ups plus within-control partial-port gaps from PR #435 batches 3–11):

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.
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.
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.
Batch D — DropDownButton/SplitButton/ToggleSplitButton Flyout child via .OneWayBridged + Reconciler.CreateFlyoutForDescriptor. Closes the Batch 4 Flyout escape-hatch.
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).
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).
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.
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 close-out (spec/047-phase3-close-out branch, off PR #436 HEAD) — engine shapes + ports that close the largest Phase 3-final carve-outs:

Engine (1) — Panel<>.PerChildAttachedAfterAll. Two-pass shape: optional Action<TControl, IReadOnlyList<(UIElement,Element)>>? callback fired once after every child has been mounted (Mount path) or reconciled (Update path) with the full ordered pair list. Distinct from PerChildAttached (which fires per-child mid-pass and cannot see siblings that haven't mounted yet). Pair list allocated lazily — null consumers pay no overhead. Existing Grid/Canvas/FlexPanel/WrapGrid unchanged.
Engine (2) — TemplatedItems<> strategy + Reconciler.BindKeyedItemsSource. New record TemplatedItems<TItem, TElement, TControl> (open in TItem; descriptor authors of new typed templated lists declare items, key selector, view builder). Engine binder BindKeyedItemsSource<TItem> wires ReactorListState + shared ContainerContentChanging + spec-042 KeyedListDiff.Apply against a new IItemViewSource stash on ReactorState. MVP supports WinUI.ListViewBase; ItemsRepeater / Lazy*Stack surface a descriptive InvalidOperationException at the dispatch switch (purely additive to add).
Port (4) — RelativePanel via PerChildAttachedAfterAll. Closes the Phase-4 carve-out documented on RelativePanelDescriptor. The descriptor's after-all callback builds a name → control map across mounted children, assigns FrameworkElement.Name, then writes RelativePanel.SetRightOf / SetBelow / SetAlignLeftWith / etc. against sibling references. Body lifted from legacy MountRelativePanel. Fixture: Desc_RelativePanel_MountUpdate (now includes 5 sibling-named two-pass assertions).
Port (5) G2 — TemplatedListView<T> / TemplatedGridView<T> via base-derived registration + TemplatedItemsErased<>. The handoff prompt assumed each closed T would need its own registration. The realistic shape mirrors what the legacy Reconciler.Mount switch does: T-erasure at a non-generic abstract base. Engine extensions: - V1HandlerRegistry.AddForDerivedTypes + cached base-walk in TryGet. Exact-type registrations always win; base-derived entries catch every closed-T variant via the runtime type's base chain. - Reconciler.RegisterHandlerForDerivedTypes<TBase,TControl> surfaces the registry capability on the public v1 API. - New empty intermediate bases TemplatedListViewElementBase, TemplatedGridViewElementBase, TemplatedFlipViewElementBase under TemplatedListElementBase. No fields, seal ControlKind; leaf record equality unchanged because the leaf type still owns its EqualityContract. - TemplatedItemsErased<TElement,TControl> strategy + non-generic IErasedTemplatedItemsStrategy dispatch marker. Strategy is non-generic in TItem; items + keys read through the element's IKeyedItemSource implementation. - Reconciler.BindErasedKeyedItemsSource — companion to the TItem-carrying binder. Same realization pipeline; selection + click event wiring inlined so the descriptor needs no new ControlEventState payload box. - Two descriptors register on the intermediate bases; the registry walk routes every closed-T variant to the same descriptor. TemplatedFlipView<T> intentionally not ported (FlipView pre-mounts items; no ContainerContentChanging, no OC delta channel). Fixtures: Desc_TemplatedListView_MountUpdate, Desc_TemplatedGridView_MountUpdate (17 assertions covering Mount, keyed insert/remove diff, same-ref idempotency).
Selftest baselines (Cloud PC x64, post close-out). V1 ON Desc_: 556 ok / 0 failures. V1 OFF Desc_: 556 ok / 0 failures (parity preserved). Legacy KLR_ keyed-list fixtures: 73 ok / 0 failures (engine refactor of RefreshRealizedContainers + the shared CCC handler is behavior-neutral for the legacy path).

Phase 3 close-out carve-outs — status after Phase 3 finish:

Expander.HeaderTemplate — closed by Phase 3 finish via Engine (2) .ImperativeBridged; two-strategy composition resolved at the property level (Children stays as SingleContent).
TeachingTip.Target — closed by Engine (3) audit. Legacy doesn't set Target either; setter escape is the contract in both paths. Declarative deferred-resolution shape is future polish, not a Phase 3 gate.
Path.PathDataString — closed by Phase 3 finish via Engine (4) .Imperative. Single entry drives all three legacy strategies (XamlReader.Load → pre-built Geometry → PathDataParser.Parse) end-to-end with the same multi-source ArgumentException rethrow path.
NumberBox coercion — closed by Engine (5) audit; existing .CoercingOneWay already matched UpdateNumberBox's suppression pattern line-for-line. NumberBoxDescriptor.Min/Max ported through.
Lazy*Stack<T> G2 port — closed by Phase 3 finish (Port (6)). BindErasedKeyedItemsSource gained a case WinUI.ItemsRepeater arm; LazyStackElementBase implements both IKeyedItemSource and a new internal IItemsRepeaterFactorySource. Single base-derived descriptor catches every closed-T variant. Behavior diff: descriptor's TControl is WinUI.ItemsRepeater directly (no auto-ScrollViewer wrapping).
ItemsRepeater<T> G2 port — closed by Phase 3 finish. New ItemsRepeaterElementBase + ItemsRepeaterElement<T> records (Element.cs) model on LazyStackElementBase and implement IKeyedItemSource + IItemsRepeaterFactorySource, so dispatch flows through Engine (1)'s ItemsRepeater arm with no new engine work. Legacy MountItemsRepeater / UpdateItemsRepeater arms added (the element type is new — there was no legacy arm before). DSL surface: ItemsRepeater<T> factory in Dsl.cs. Single base-derived ItemsRepeaterDescriptor catches every closed-T variant. 11 new fixtures (Desc_ItemsRepeater_*). Every typed-items host family scoped in Phase 3 now has a V1 descriptor (the precise close-out claim — the broader "every Element type" audit is captured under the "Phase 3 deferred / not-attempted" section below).
G3 typed lists — TreeView, FlipView, TabView, Pivot — closed by Phase 3 finish. Note: "FlipView" here is the simple non-templated FlipViewElement (Element[] items). The typed TemplatedFlipViewElement<T> peer was ported in Phase 3 completion via the new PreMountedItems<> strategy + base-derived TemplatedFlipViewDescriptor registered on TemplatedFlipViewElementBase — see the Phase 3 completion entry below. - TreeView via new TreeChildren<TElement, TControl> strategy (hierarchical, positional rebuild on Update, recursive ContentElement mount). - FlipView reuses existing ItemsHost<> (alternative (b) — no new strategy needed). - TabView + Pivot share a new TabItemsHost<TElement, TControl, TItem> strategy with a per-descriptor CreateContainer lambda (TabViewItem / PivotItem). - TabView's TabStripHeader / TabStripFooter and spec 045 §2.4 docking drag pipeline + §2.2 pinnable headers stay on the legacy arm; documented in the descriptor xmldoc. - 29 new fixtures across the four descriptors (Desc_TreeView_, Desc_FlipView_, Desc_TabView_, Desc_Pivot_). Total Desc_ baseline: 602 ok / 0 failures both V1 ON and V1 OFF. (Total grows to 613 after Port (7) ItemsRepeater above.)

Phase 3 deferred / not-attempted (element types in the legacy Reconciler.Mount switch that have neither a Phase 1 V1 handler nor a Phase 3 descriptor — out of scope for the Phase 3 batch list, recorded here for a future Phase 3.5 / Phase 4 prelude). Cross-referenced from the audit at the end of spec/047-phase3-finish:

Genuine engine gap (CLOSED — Phase 3 completion): TemplatedFlipViewElement<T> — ported via the new PreMountedItems<TElement, TControl> ChildrenStrategy and TemplatedFlipViewDescriptor, registered base-derived against TemplatedFlipViewElementBase. The strategy pre-mounts every item up-front into FlipView.Items (no ContainerContentChanging to drive realization) and positionally reconciles via Reconciler.ReconcileV1Child on Update.
Untyped items hosts (CLOSED — Phase 3 completion, partial): ItemsViewElementBase, ItemContainerElement — ported as standard descriptors and registered in RegisterV1BuiltInHandlers. GridViewElement (plain Element[]) — descriptor authored (GridViewDescriptor) but carved during PR #440 CR: the descriptor's ItemsHost<> strategy pre-mounts every item into GridView.Items (one container per item, no virtualization), while the legacy MountGridView arm uses ItemsSource = Range(0..N) + ItemTemplate + ContainerContentChanging to realize containers lazily (matches Phase 1 ListViewHandler). Closing this needs either a hand-coded GridViewHandler or a new ChildrenStrategy variant wrapping CCC. Tracked alongside TabView / overlays / NavigationHost gap-closure.
Heavy / specialized controls (CLOSED — Phase 3 completion): WebView2Element, NavigationViewElement, TitleBarElement, MediaPlayerElementElement, AnimatedVisualPlayerElement, MapControlElement, SemanticZoomElement, AnnotatedScrollBarElement, RefreshContainerElement, SwipeControlElement, ParallaxViewElement — all descriptors authored and registered. (NavigationHostElement stays deferred — see below.)
Polymorphic / a11y (CLOSED — Phase 3 completion): IconElement (decorator-style handler via the IDecoratorElementHandler engine extension landed this phase), SemanticElement, AnnounceRegionElement — all registered.

Phase 3 completion — still deferred to the next PR (not regressions; scoped carve list documented inline in RegisterV1BuiltInHandlers):

Dialog / overlay family: ContentDialogElement, FlyoutElement, PopupElement, MenuBarElement, MenuFlyoutElement, CommandBarElement, CommandBarFlyoutElement. Modal lifecycle (control-side-mounted, not parent-tree-mounted) requires decorator-style ports beyond the IDecoratorElementHandler shape used for IconElement.
Stateful host: NavigationHostElement. Per-instance route/cache/transition state is intercepted in Reconciler.UnmountRecursive BEFORE the V1 dispatch arm; needs a small refactor to internal-expose MountNavigationHost / UpdateNavigationHost and duplicate cleanup logic in the V1 handler before it can route through V1.
TabViewDescriptor (descriptor exists, registration carved): Bisect (3× clean V1 ON full selftest with only TabViewDescriptor carved, vs. 1–4 random docking-text-find failures per run when registered: DockHooks / PixDoc / RoleAware / Composition / FloatRoot) ratifies the descriptor's documented gaps as hot in the docking suite — missing spec 045 §2.4 drag pipeline (OnTabDragStarting / OnTabDragCompleted), §2.2 pinnable headers (BuildTabHeader / BuildPinButton / in-place TryUpdatePinHeaderInPlace), in-place CanUpdate for tab content (preserves focus/state on re-renders), conditional SelectedIndex write, and TabStripHeader / TabStripFooter Element slots. Closing them requires engine work (post-children mount-hook so SelectionChanged subscribes after children-add + an ImperativeBridged shape for the named tab strip slots).
GridViewDescriptor (descriptor exists, registration carved during PR #440 CR): The descriptor's ItemsHost<> ChildrenStrategy pre-mounts every item into GridView.Items (one container per item, no virtualization). The legacy MountGridView arm uses ItemsSource = Range(0..N) + ItemTemplate + ContainerContentChanging to realize containers lazily — matching Phase 1 ListViewHandler. A|B tests pass either way (no fixture stresses GridView scale), but production memory/lifecycle would silently regress. Closing this needs either a hand-coded GridViewHandler mirroring ListViewHandler's CCC virtualization, or a new ChildrenStrategy variant (e.g. RecyclingItemsHost<>) that wraps the ItemsSource + ContainerContentChanging realization contract.
Interop bridges: XamlHostElement, XamlPageElement. V1 descriptors exist (XamlHostDescriptor, XamlPageDescriptor) but stay unregistered because XamlInterop.Register(reconciler) populates the external _typeRegistry at app startup; auto- registering V1 would clash via EnsureRegistrableElementType. Unification is Phase 4 follow-up.

Reactor composition primitives (intentionally above the V1 protocol — Phase 4 cleanup keeps their legacy arms):

ComponentElement, FuncElement, MemoElement, ErrorBoundaryElement, CommandHostElement, Validation.FormFieldElement / ValidationVisualizerElement / ValidationRuleElement. These orchestrate child reconciliation rather than wrap a single WinUI control, so the V1 handler protocol does not apply. (ModifiedElement is intentionally NOT in this list — it's unwrapped to its wrapped element BEFORE dispatch at the top of Reconciler.Mount, so it never reaches the switch and does not count as a carved arm.)

Phase 3 completion status (PR #440 — landed-pending-merge): Every element type in the production codebase either (a) routes through V1 dispatch (Phase 1 hand-coded handler OR Phase 3 descriptor registered in RegisterV1BuiltInHandlers), (b) is a Reactor composition primitive intentionally kept above the V1 protocol, or (c) is in the explicit deferred carve list above with a documented gap-closure path. The A|B parity bar — V1 ON ≡ V1 OFF across the full xunit + selftest matrix — is met for every registered element: 9134 xunit + 4410 selftest, 0 failures both flags. Phase 4 cleanup can delete every legacy MountXxx / UpdateXxx method that backs an element that has been registered through V1; the legacy switch arms for the composition primitives

the deferred carve list must remain until their respective follow-up PRs land.

Quantified V1 dispatch coverage (post-PR #440):

Bucket	Arms	% of total
Routed through V1 (75 = 5 Phase 1 + 6 base-derived + 63 standard descriptors + 1 decorator)	75	79%
Reachable-but-deferred (overlays 7, NavigationHost 1, TabView 1, GridView 1, XamlHost/Page 2)	12	12.6%
Intentionally above V1 (composition primitives — permanent carve)	8	8.4%
Total `Reconciler.Mount.cs` switch arms	95	100%

Coverage of V1-reachable surface (excludes 8 composition primitives): 75 / 87 ≈ 86%.
Coverage of all switch arms: 75 / 95 ≈ 79%.
Path to 100% reachable: the follow-up PR closes the 12 deferred:
1. Port the 7 overlay descriptors (ContentDialog, Flyout, Popup, MenuBar, MenuFlyout, CommandBar, CommandBarFlyout) — needs a decorator strategy variant for modal lifecycle beyond IDecoratorElementHandler.
2. Refactor NavigationHostElement cleanup path so V1 can own it (internal-expose MountNavigationHost / UpdateNavigationHost, duplicate cleanup logic in the V1 handler, remove the UnmountRecursive intercept).
3. Close TabViewDescriptor gaps (engine post-children mount-hook + ImperativeBridged for named slots + port BuildTabHeader / BuildPinButton / TryUpdatePinHeaderInPlace + drag pipeline trampolines + conditional SelectedIndex write + in-place CanUpdate).
4. Close GridViewDescriptor lifecycle gap — either author a Phase 1 hand-coded GridViewHandler mirroring ListViewHandler's CCC virtualization, or introduce a RecyclingItemsHost<> ChildrenStrategy variant.
5. Unify XamlInterop.Register with V1 auto-registration so XamlHostElement / XamlPageElement descriptors can register without EnsureRegistrableElementType clash.

Phase 4 cleanup (deletion of legacy switch arms + UseV1Protocol flag) is unblocked for the 75 routed arms today; the remaining 12 arms unblock as the follow-up PR lands each closure.

Carry-forward known defects (from Phase 1):

KD-3 — dispatch fast-path for ported built-ins (M4 +88.9% V1 vs Today). Intersects with descriptor shape; address as part of Phase 3 migration.
KD-4 — public typed-event surface for external descriptor authors. Scope narrowed by Phase 2 to external-author-only (in-tree fast path is shipped via DescriptorControlledPayload<T> + the new .HandCodedControlled / .HandCodedEvent per-descriptor TPayload pattern).

Phase 3 exit reopen condition for Q1: none from the in-tree work. The only Q1 reopen trigger is source-gen (§7) landing.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fully Extensible Control Model — Implementation Tasks

0.1 `BeginSuppress` audit

0.2 `EventHandlerState` field audit

0.3 Perf validation suite — infrastructure

0.3.1 `StressPerf.ReactorV2` skeleton

0.3.2 `BlankReactorV2` for startup perf

0.3.3 `PerfBench.ControlModel` — micro suite harnesses

0.3.4 Macro suite L1–L11

0.3.5 Reporting aggregator

0.3.6 Environment isolation runbook

0.4 Baseline numbers — capture `Direct` and `ReactorToday`

0.5 Existing-API surface inventory

0.6 Decision criteria for §13 open questions

0.7 Spec factoring decision

Phase 0 exit checklist

Phase 2 wrap-up — §13 Q1 measurement gate

Phase 3 prerequisites — multi-event composition + author guidance

Phase 3 bulk-port progress

Value-bearing family

FilesExpand file tree

047-extensible-control-model-implementation.md

Latest commit

History

047-extensible-control-model-implementation.md

File metadata and controls

Fully Extensible Control Model — Implementation Tasks

0.1 BeginSuppress audit

0.2 EventHandlerState field audit

0.3 Perf validation suite — infrastructure

0.3.1 StressPerf.ReactorV2 skeleton

0.3.2 BlankReactorV2 for startup perf

0.3.3 PerfBench.ControlModel — micro suite harnesses

0.3.4 Macro suite L1–L11

0.3.5 Reporting aggregator

0.3.6 Environment isolation runbook

0.4 Baseline numbers — capture Direct and ReactorToday

0.5 Existing-API surface inventory

0.6 Decision criteria for §13 open questions

0.7 Spec factoring decision

Phase 0 exit checklist

Phase 2 wrap-up — §13 Q1 measurement gate

Phase 3 prerequisites — multi-event composition + author guidance

Phase 3 bulk-port progress

Value-bearing family

0.1 `BeginSuppress` audit

0.2 `EventHandlerState` field audit

0.3.1 `StressPerf.ReactorV2` skeleton

0.3.2 `BlankReactorV2` for startup perf

0.3.3 `PerfBench.ControlModel` — micro suite harnesses

0.4 Baseline numbers — capture `Direct` and `ReactorToday`