feat(ui-windows-winui): render-backend dispatch seam + startup probe (#4680 step 3)

[proggeramlug]

What

Implements the step-3 dispatch seam for #4680 (opt-in WinUI 3 / Fluent Windows target), building directly on the step-2 bootstrap probe merged in #4896.

Adds winui::backend — the single decision point the per-widget WinUI 3 mapping reads — plus a process-startup probe so --target windows-winui binaries resolve their render backend at launch.

How

• winui::backend::active() -> RenderBackend — returns RenderBackend::Fluent when the Windows App SDK bootstrap probe (bootstrap::initialize()) is Ready, else RenderBackend::Win32. Cheap and stable (memoized by the bootstrap cache). Each XAML widget lands behind this check: build a Microsoft.UI.Xaml control on Fluent, else delegate to the existing Win32 constructor.
• CRT static initializer (.CRT$XCU, anchored with #[used]) registered in the crate runs the probe at process start for any binary that links this staticlib — i.e. exactly the --target windows-winui builds, and never the default --target windows builds (which don't link the crate). So the first widget construction reads an already-resolved backend rather than probing lazily. It never panics (runs before main).
• PERRY_WINUI_DIAG prints the chosen backend at launch: [perry-winui] render backend: win32|fluent.

Testing

• cargo test -p perry-ui-windows-winui → green (active_backend_matches_bootstrap_verdict, initialize_is_total_and_idempotent). active() mirrors the bootstrap verdict and is stable; off Windows it is always Win32.
• Verified on this Windows host (no SDK installed):
  • The startup initializer fires in a linked binary — running the test exe with PERRY_WINUI_DIAG=1 emitted [perry-winui] render backend: win32.
  • The .CRT$XCU section (8 bytes — one initializer pointer) is present in the WHOLEARCHIVE'd perry_ui_windows_winui.lib (llvm-objdump --headers).

Scope / not in this PR

Real Microsoft.UI.Xaml controls need the WinAppSDK winmd projections + runtime (the stock windows crate at 0.58 ships only UWP Windows.UI.Xaml, not WinUI 3's Microsoft.UI.Xaml), so they're the next step. Today the seam always resolves to Win32. Win32 (--target windows) remains the default and is untouched.

Summary by CodeRabbit

Release Notes

• Chores

  • Version bumped to v0.5.1172

• New Features

  • Windows App SDK bootstrap diagnostics enhanced with comprehensive failure reporting including error codes
  • Environment variable support added for enabling diagnostic output during app initialization
  • Bootstrap failures now surface detailed error information and formatted status descriptions for improved troubleshooting

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a bootstrap outcome cache (LAST_DETAIL AtomicI32) and new API (last_init_detail, describe_init_detail, sentinel constants) to the WinUI crate. Records outcomes at each bootstrap failure/success branch and wires the formatted detail into the perry_winui_startup CRT diagnostic probe. Bumps the workspace to v0.5.1172 with matching changelog and doc updates.

Changes

WinUI Bootstrap Diagnostics and v0.5.1172 Release

Layer / File(s)	Summary
Bootstrap diagnostic API and outcome recording crates/perry-ui-windows-winui/src/winui.rs	Adds LAST_DETAIL AtomicI32, sentinel constants, last_init_detail(), describe_init_detail(), and records bootstrap outcomes (DLL missing, no entrypoint, success, raw HRESULT failure) at each branch. Wires formatted detail into perry_winui_startup when PERRY_WINUI_DIAG is set. Expands tests for backend stability, off-Windows fallback, and describe formatting.
Crate docs, changelog, and version bump crates/perry-ui-windows-winui/src/lib.rs, CHANGELOG.md, Cargo.toml, CLAUDE.md	Expands crate-level doc to describe the winui::backend::active dispatch seam. Adds v0.5.1172 changelog entry covering render-backend selection, startup probe, and HRESULT surfacing. Bumps workspace version in Cargo.toml and CLAUDE.md.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• Add opt-in WinUI 3 (Fluent) Windows target: --target windows-winui #4680: This PR implements WinUI bootstrap diagnostics and initialization tracking (last_init_detail, describe_init_detail, LAST_DETAIL cache) in the perry-ui-windows-winui crate, which directly addresses the diagnostic and tracking feature described in that issue.

Poem

🐇 Hop! The bootstrap now remembers its fate,
A cached little DETAIL that never runs late.
DLL missing? No entrypoint found?
The HRESULT hex makes a comforting sound.
PERRY_WINUI_DIAG prints it all with a flair—
Version 1172, and the rabbit's aware! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description violates the repository's explicit guidelines by including edits to CHANGELOG.md, CLAUDE.md, and Cargo.toml version bumping, which the template states the maintainer handles at merge time to prevent conflicts.	Remove the changes to CHANGELOG.md, CLAUDE.md, and Cargo.toml version bumps before merge—these are maintained by the project maintainer at release time per CONTRIBUTING.md.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(ui-windows-winui): render-backend dispatch seam + startup probe (#4680 step 3)' is clear, concise, and directly describes the main change: implementing the dispatch seam and startup probe for WinUI backend selection.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/4680-winui-seam

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

CHANGELOG.md (1)

1-19: ⚡ Quick win

Add explicit file paths and expand validation notes per guideline.

The changelog entry is well-written but falls short of the coding guideline requirement for "detailed long-form root-cause writeups, file paths, and validation notes." Specifically:

• File paths: missing explicit list of changed files (e.g., crates/perry-ui-windows-winui/src/winui.rs, crates/perry-ui-windows-winui/src/lib.rs)
• Validation notes: currently brief ("Verified on a Windows host without the SDK"); should detail the test cases, coverage, and edge cases actually validated (e.g., "Tests confirm: active() mirrors bootstrap verdict and is stable; startup initializer fires correctly on Windows without the SDK; .CRT$XCU section present in linked binary")

📝 Suggested expansion

Replace lines 16–19 with something like:

Verified on a Windows host without the SDK:
  - `active()` mirrors bootstrap verdict and remains stable across calls
  - CRT initializer fires at process start in linked binaries
  - `.CRT$XCU` section is present in `WHOLEARCHIVE`'d `perry_ui_windows_winui.lib`
  - Backend resolves to Win32 when SDK is absent
  - `describe_init_detail()` formats HRESULT diagnostics correctly

Files changed:
  - `crates/perry-ui-windows-winui/src/winui.rs`: outcome caching (`LAST_DETAIL` AtomicI32), sentinel constants, dispatch seam, CRT initializer
  - `crates/perry-ui-windows-winui/src/lib.rs`: crate-level docs for `winui::backend::active` seam

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CHANGELOG.md` around lines 1 - 19, The changelog entry lacks the required
explicit file paths and detailed validation notes per coding guidelines. Expand
the validation section by replacing the brief "Verified on a Windows host
without the SDK" statement with a detailed bulleted list documenting specific
test validations, such as confirming `active()` mirrors bootstrap verdict and
remains stable across calls, CRT initializer fires correctly at process start in
linked binaries, `.CRT$XCU` section presence in the linked library, Win32
fallback behavior when SDK is absent, and `HRESULT` diagnostic formatting.
Additionally, add a "Files changed" section explicitly listing all modified file
paths with descriptions of their specific changes, including the core changes to
`crates/perry-ui-windows-winui/src/winui.rs` (outcome caching via `LAST_DETAIL`
AtomicI32, sentinel constants, dispatch seam, and CRT initializer registration)
and `crates/perry-ui-windows-winui/src/lib.rs` (crate-level documentation for
the `winui::backend::active` seam).

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@CHANGELOG.md`:
- Around line 1-19: The changelog entry lacks the required explicit file paths
and detailed validation notes per coding guidelines. Expand the validation
section by replacing the brief "Verified on a Windows host without the SDK"
statement with a detailed bulleted list documenting specific test validations,
such as confirming `active()` mirrors bootstrap verdict and remains stable
across calls, CRT initializer fires correctly at process start in linked
binaries, `.CRT$XCU` section presence in the linked library, Win32 fallback
behavior when SDK is absent, and `HRESULT` diagnostic formatting. Additionally,
add a "Files changed" section explicitly listing all modified file paths with
descriptions of their specific changes, including the core changes to
`crates/perry-ui-windows-winui/src/winui.rs` (outcome caching via `LAST_DETAIL`
AtomicI32, sentinel constants, dispatch seam, and CRT initializer registration)
and `crates/perry-ui-windows-winui/src/lib.rs` (crate-level documentation for
the `winui::backend::active` seam).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3f1bdb93-5f6c-4911-bf2a-fa062d1e729c

📥 Commits

Reviewing files that changed from the base of the PR and between 08819f0 and d85578d.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (5)

• CHANGELOG.md
• CLAUDE.md
• Cargo.toml
• crates/perry-ui-windows-winui/src/lib.rs
• crates/perry-ui-windows-winui/src/winui.rs