Copilot instructions

1---
2applyTo:
3  - "src/Core/src/Handlers/**"
4  - "src/Controls/src/Core/Handlers/**"
5---
6# Handler Mapper and Property Patterns
7 
8## Property Update Flow
9- Property updates MUST go through `Handler.UpdateValue(nameof(Property))` — never call mapper methods directly
10- Direct calls bypass user-registered `AppendToMapping`/`PrependToMapping` customizations
11- Map dependencies before dependents — if property B reads property A, A's mapper must run first
12- `CommandMapper` entries return void and use the `(handler, view, args)` signature
13 
14## Lifecycle Management
15- **ConnectHandler**: Register listeners, subscribe to events, capture native defaults BEFORE applying cross-platform properties
16- **DisconnectHandler**: Unsubscribe all events, dispose platform resources, null out references
17- Call `base.ConnectHandler`/`base.DisconnectHandler` — base class performs platform hookup/teardown (NOT mapper initialization, which happens in `SetVirtualView`)
18 
19## Null Safety in Callbacks
20- Null-check `VirtualView` before access in every mapper method and platform callback — it is null during disconnect
21- Validate `MauiContext` before use — throw `InvalidOperationException` with descriptive message if null
22- After async operations, verify the handler is still connected before applying results
23 
24## Native Defaults Preservation
25- Capture native default values (colors, fonts, styles) in `ConnectHandler` BEFORE any cross-platform property is applied
26- Clearing a cross-platform property (setting to null/default) must restore the captured native default, not a hardcoded fallback
27- On Windows, preserve WinUI XAML style-applied values; on Android, cache theme-inherited drawables; on iOS, capture UIAppearance defaults
28 
29## Mapper Extensibility
30- When extending existing mappers, ensure the base mapper chain is called — do not silently replace
31- Static mapper methods should be `public static` to enable platform-specific overrides
32- Use `nameof()` for property keys — avoid magic strings
33 
34## Fire-and-Forget Async
35- Use `.FireAndForget(handler)` for async operations in mapper methods — never use bare `async void`
36- The `FireAndForget` overload accepting a handler logs exceptions through the handler's service provider
37