Copilot instructions

1---
2applyTo:
3  - "**/PublicAPI.Unshipped.txt"
4  - "src/Core/src/**/*.cs"
5  - "src/Controls/src/**/*.cs"
6  - "src/Essentials/src/**/*.cs"
7---
8# Public API Surface Design
9 
10> **Activation guard**: only apply this guidance when the diff actually changes
11> public API surface — `public`/`protected` types or members, interface
12> definitions, builder/extension methods on public types, `[Obsolete]` markers,
13> or `PublicAPI.*.txt` entries. The broad `.cs` globs exist so this guidance
14> loads at the moment of API design (writing `public class Foo` in `Button.cs`),
15> not just when the analyzer-generated `Unshipped.txt` is updated afterward.
16> If the diff only changes internals or implementation details, ignore.
17 
18## API Addition Rules
19- New public APIs must have clear, demonstrated use cases — no speculative additions
20- API naming must follow .NET design guidelines and be consistent with existing MAUI patterns
21- Interfaces belong at `IView`/`IElement` level when behavior is cross-cutting — do not duplicate per-control
22 
23## PublicAPI.Unshipped.txt
24- Entries must exactly match the actual API shape (namespace, type, member signature)
25- A leading `~` is Microsoft.CodeAnalysis.PublicApiAnalyzers' nullable-oblivious marker. It is unrelated to whether an API is public, internal, static, or instance.
26- Do not manually add or remove `~` based on an entry's appearance or inferred API visibility. Preserve analyzer-generated markers and use `dotnet format analyzers` or the repository's documented PublicAPI generation workflow when correcting entries.
27- Removing a required `~` makes the recorded nullability shape differ from the source API and creates the analyzer mismatch that the marker prevents.
28 
29> For PublicAPI.Unshipped.txt file management workflow (never disable analyzers, `dotnet format analyzers`, revert-then-add pattern), see `copilot-instructions.md` § PublicAPI.Unshipped.txt File Management.
30 
31## Obsolescence and Removal
32- Deprecated APIs must go through `[Obsolete("message")]` with migration guidance before removal
33- Include the replacement API or pattern in the obsolete message
34- Breaking changes require explicit design justification documented in the PR
35 
36## Visibility Decisions
37- Default to `internal` — make `public` only when external consumers need access
38- `protected` members in unsealed types are part of the public API surface — treat with same rigor
39- Use `[EditorBrowsable(EditorBrowsableState.Never)]` for APIs that must be public for technical reasons but should not appear in IntelliSense
40