docs: under-the-hood guide to the V1 Protocol + extension cookbook

[codemonkeychris]

Summary

• Two new comprehensive-tier pages in the Under-the-hood track:
  • docs/_pipeline/templates/v1-protocol.md.dt (order 33.5) — reference for the V1 handler protocol: dispatch model, IElementHandler contract, ref-struct contexts + ReactorBinding, mount-then-subscribe ordering invariant, full ChildrenStrategy survey (11 shapes), pool integration, echo suppression, element-identity tag pattern, descriptors as declarative sugar, the complete PropEntry builder vocabulary, registration variants.
  • docs/_pipeline/templates/extending-reactor-controls.md.dt (order 33.7) — cookbook. End-to-end walkthrough of porting WinUI RatingControl as a StarMeterElement descriptor: element record → descriptor-vs-handler choice → prop wiring → events → children strategy → registration. Locks in the perf bar (pool reuse, echo suppression, callback-gated subscription) external authors should hit.
• Two compilable doc apps under docs/_pipeline/apps/ with working custom-control extensions (LedIndicatorElement, StarMeterElement).
• Five small <snippet:...> markers added in src/Reactor/Core/V1Protocol/ so the reference page can cite the authoritative source for the handler contract, MountContext, ChildrenStrategy, the adapter's Mount body, and the descriptor interpreter. Framework rebuilds clean.
• Generated outputs included so the docset is publishable from this PR (docs/guide/v1-protocol.md, docs/guide/extending-reactor-controls.md, docs/guide/images/{v1-protocol,extending-reactor-controls}/*.png).

Audience and framing

The intended reader is anyone extending Reactor with a new native control (third-party WinUI control, custom Control subclass, or built-in not yet in the catalog), or anyone debugging why an existing element does not update the way it should. Prose is written to reflect the post-cleanup state the user asked for — V1 is the only protocol, RegisterHandler is GA, no [Experimental] surface, no UseV1Protocol flag mentioned, no Path-B-delegate handlers as a stable shape. The doc apps still call AppContext.SetSwitch(\"Reactor.UseV1Protocol\", true) today because that switch is still required at the codebase's current state; that line goes away with the cleanup.

Validation

• mur docs compile --validate-only --topic v1-protocol — passes (one non-fatal warning about winui-ref not being declared, which is correct — these are Reactor-original concept pages, not transparent wrappers).
• mur docs compile --validate-only --topic extending-reactor-controls — passes (same non-fatal warning).
• mur docs compile --topic <each> — both topics emit their .md + screenshot; no other topics rebuilt.
• Both screenshots show the custom V1 controls actually rendering: 4 LEDs (2 on, 2 dimmed) at level=2, and a RatingControl at 3.5 stars with the configured caption.
• Both doc apps build clean (Release/x64).
• src/Reactor/Reactor.csproj rebuilds clean with the source markers in place.

Comprehensive-tier checklist (per ai-author-skill.md §6)

• ≥80-word mental-model lead paragraph ✓ (both pages)
• ≥3 resolved snippet refs ✓ (v1-protocol: 7, extending: 4)
• ≥1 screenshot ✓ (one each)
• Reference table ✓ (multiple per page)
• ## Patterns ✓
• ## Common Mistakes ✓
• ## Tips ✓
• ## Next Steps with ≥3 links ✓ (5 each)
• ≥1 ai:caveat block ✓ (one each)
• ≥5 inline cross-links ✓ (v1-protocol: 9, extending: 14)

Test plan

• CI green on this branch
• Reviewer skim of docs/guide/v1-protocol.md and docs/guide/extending-reactor-controls.md to sanity-check the prose against the implementation
• (Optional) reviewer runs mur docs compile --topic v1-protocol / --topic extending-reactor-controls locally and diffs the output against the committed docs/guide/* artifacts

🤖 Generated with Claude Code