Copilot instructions

1---
2applyTo:
3  - "src/Controls/src/Core/Handlers/Items2/**"
4  - "src/Controls/src/Core/Handlers/Items/iOS/**"
5  - "src/Controls/src/Core/Handlers/Items/*.iOS.cs"
6  - "src/Controls/src/Core/Handlers/Items/*.ios.cs"
7---
8# CollectionView — iOS/MacCatalyst (Items2/ Handler)
9 
10> New iOS/MacCatalyst work targets Items2/. Items/iOS/ is deprecated. See `collectionview-handler-detection.instructions.md` for the full platform→handler mapping.
11 
12## UICollectionView Cell Measurement
13- Scope cell layout invalidation to the affected cell — avoid `InvalidateLayout()` on the entire collection for single-cell changes
14- Custom `UICollectionViewCell` subclasses should handle `MeasureInvalidated` only when the hosted MAUI control actually needs remeasuring
15- Cell sizing must stay in sync between the measure pass and the layout pass — out-of-sync causes visual glitches
16 
17## UICollectionViewCompositionalLayout
18- Layout configuration must match the `ItemsLayout` specification (Linear, Grid, or custom)
19- `ItemsLayout` property changes require full layout reconfiguration — partial updates leave stale section configuration
20- Group header/footer template changes must invalidate the correct section scope, not the entire layout
21 
22## Memory Management
23- Use static callback patterns to avoid retain cycles between cells and their hosting handler
24- Remove `NSNotificationCenter` observers in `DisconnectHandler`
25- Weak references for long-lived observers of short-lived cells — cells are recycled and reused
26 
27## Regression Patterns
28- Test across empty collection, single item, many items, and with grouping — a fix for one layout scenario routinely breaks another
29 
30## Items/ iOS (Deprecated)
31- Files in `Handlers/Items/*.iOS.cs` are deprecated — prefer Items2/ for new work
32- Only modify Items/ iOS code for explicit legacy maintenance or backward-compatibility fixes
33 
34> **Platform file extension rules** (`.ios.cs` vs `.maccatalyst.cs` compilation targets) are defined in `copilot-instructions.md` § Platform-Specific File Extensions. See also `collectionview-handler-detection.instructions.md` for which handler directory to target per platform.
35