Copilot instructions

1---
2applyTo:
3  - "src/Controls/src/Core/Handlers/Items/Android/**"
4  - "src/Controls/src/Core/Handlers/Items/*.Android.cs"
5  - "src/Controls/src/Core/Handlers/Items/*.android.cs"
6---
7# CollectionView — Android (Items/ Handler)
8 
9> Items/ is the sole Android handler — see `collectionview-handler-detection.instructions.md` for the full platform→handler mapping.
10 
11## RecyclerView Adapter Patterns
12- Use range-specific notifications (`NotifyItemRangeInserted`, `NotifyItemRangeRemoved`, `NotifyItemRangeChanged`) when INCC semantics provide exact affected ranges — prefer these over `NotifyDataSetChanged` for preserving scroll position and animations
13- Full refresh via `NotifyDataSetChanged` is valid for `Reset` actions, ambiguous index cases, and header/footer template changes
14- Handle all `ObservableCollection` change actions: Add, Remove, Replace, Move, Reset
15- On `Reset`, recalculate adapter state from scratch — do not assume incremental consistency
16 
17## ViewHolder Recycling
18- `BindingContext` MUST be updated on every rebind — stale data from a previous holder is a common source of visual glitches
19- Do not store item-specific state in the ViewHolder outside of `BindViewHolder` — recycled holders carry state from previous items
20- Dispose and recreate platform views only when the template changes, not on every rebind
21 
22## Layout Manager
23- Select layout manager (Linear, Grid, custom) based on `ItemsLayout` specification — do not hardcode
24- `ItemsLayout` property changes require full layout manager replacement, not partial reconfiguration
25- Account for Android pixel rounding in item measurement — fractional dp values cause 1px gaps
26 
27## Memory and Lifecycle
28- Unsubscribe from `ScrollChange` and adapter observers in `DisconnectHandler` — do NOT call Dispose on platform objects
29- Scroll position restoration after adapter data changes must handle empty-collection edge case
30 
31## Regression Patterns
32- Test across empty collection, single item, many items, and with grouping — a fix for one layout scenario routinely breaks another
33