Investigate and implement spec 023: Performance Insight Tools

Nobody has claimed this yet.

Track investigation and implementation of spec 023.

**Spec:** [docs/specs/023-perf-insight-tools.md](https://github.com/microsoft/microsoft-ui-reactor/tree/main/docs/specs/023-perf-insight-tools.md)

## Problem (short)

A WinUI/XAML developer asking "why is my app slow?" has powerful but disjoint tools (VS Diagnostic Tools, PerfView, WPR+WPA, the 24H2 WPA XAML Frame Analysis plugin, GPUView, `EnableFrameRateCounter`, Live Visual Tree). None of them speak the developer's language: they report threads, stacks, GC generations, DX queues, and DWM frames, while developers think in XAML elements, bindings, templates, and components. Bridging that gap is left entirely to the human, so most teams ship something that feels slow and depend on one expert who can read an ETL.

Design-time cost is invisible until runtime; runtime cost is unattributable back to design. ETW already gives us a shared clock across kernel/user/native/managed — what is missing is a coherent **schema, correlation, and framework-aware attribution** on top of it, plus a surface an AI agent can query without parsing `.etl` files.

## High-level options to explore

1. **Convention layer over ETW (spec's core bet).** A universal interval primitive (`System.Diagnostics.Signpost`, §9.1), a universal correlation field (`IntentId`, §7.2), compile-time stable element identity (`PerfTag`, §9.2), and a compile-time perf report from the XAML compiler (`PerfReport.json`, §9.3). Bulk of value ships in WinUI / XAML compiler / .NET BCL; Reactor contributes a narrow set of component-layer extensions (§10).
2. **Attribution mechanism (§11) — pick one or blend.**
- **A. `AsyncLocal`** — cheap, managed-only, breaks at native/threadpool boundaries.
- **B. Correlation Vector field on events** — crosses managed/native/process boundaries; requires framework cooperation.
- **C. Out-of-band sampling + post-hoc attribution** — zero framework changes, lossy for short work.
- Spec recommendation: ship A for v1, migrate to B as WinUI formalizes the schema, use C opportunistically.
3. **Design-time estimator.** v1 lookup table keyed on element-kind × effect-count × repeater-size, seeded by a synthetic workload catalog (§12). v2 real-device telemetry, MetricKit-style (§12.3).
4. **Agent-first surface.** `xamlperf` CLI with canonical JSON trace export (§13.1/§13.2) plus optional MCP server (§13.3). Designed for agent consumption from day one, not retrofit.
5. **Responsibility split (§8).** Decide which capabilities belong in `microsoft/microsoft-ui-xaml`, the XAML compiler, the .NET BCL, vs. Reactor. Default is "WinUI-native unless it provably cannot live there."

## Next steps (per spec §17, Phase 0 — 2 weeks)

- Decide attribution mechanism A/B/C via prototype.
- Prototype Signpost API (§9.1) and `PerfTag` synthesis (§9.2) in user-space.
- Fix or replace the `EnableFrameRateCounter` AV on WinUI 3 Desktop.
- Inventory `Microsoft.UI.Xaml.Controls.Perf` events; coordinate with WinUI team on formalizing a subset.
- Working minimal overlay against StressPerf grid.

Start with docs/specs/023-perf-insight-tools.md, especially sections 7–13 and Phase 0 in §17. Prototype attribution mechanisms A/B/C and the Signpost API and PerfTag synthesis, then investigate the EnableFrameRateCounter AV, existing Microsoft.UI.Xaml.Controls.Perf events, and the StressPerf grid overlay. Done means Phase 0 findings, a chosen attribution direction, and documented coordination or implementation results.

Written by the indexing model from the issue text.