{"owner":"unoplatform","repo":"uno","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nFollow instructions in @AGENTS.md\n\n<!-- SPECKIT START -->\nFor additional context about technologies to be used, project structure,\nshell commands, and other important information, read the current plan:\n`specs/003-wasm-a11y-remediation/plan.md`\n<!-- SPECKIT END -->\n","AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI Agents when working with code in this repository.\n\n## Project Overview\n\nUno Platform is an open-source .NET UI cross-platform framework for building .NET applications from a single codebase using the WinUI 3 API. It targets Web (WebAssembly), Desktop (Windows, macOS, Linux via Skia), and Mobile (iOS, tvOS, Android).\n\n**Reference these instructions first**, then lean on skills (workflows) and the path-scoped rules below.\n\n#### Claude Code Skills (invoke via `/skill-name`)\n\n| Skill | Command | Use For |\n|-------|---------|---------|\n| Add Sample | `/add-sample` | Creating SamplesApp sample pages with correct registration |\n| Runtime Tests | `/runtime-tests` | Building and running Uno runtime tests (Skia Desktop/WASM) |\n| WinUI Runtime Tests | `/winui-runtime-tests` | Running runtime tests against native WinUI on Windows |\n| WinUI Porting | `/winui-port` | Porting WinUI C++ code to Uno Platform C# (full deep reference) |\n| DevServer | `/devserver` | DevServer CLI/Host build, test, MCP proxy, add-in discovery |\n| Docs Build | `/docs-build` | Building, previewing & validating the docs website (DocFX), incl. external-doc commit bumps in `import_external_docs.ps1` |\n\n#### Pre-commit review (invoke via `/review-panel`)\n\n`/review-panel [scope]` runs an eight-lens reviewer panel (architect, contract, skeptic, performance, operability, quality, security, jerome) in parallel and synthesizes one report with a `ship` / `fix-first` / `block-merge` verdict. Run it before you commit or open a PR — pass a scope (`master..HEAD`, a `#PR`, `HEAD~1`) or omit it to auto-detect uncommitted changes / branch-vs-`master`. The panel learns from corrections recorded in `specs/lessons.md`. Lenses, scopes, and loop recipes: `.claude/review-panel-cheatsheet.md`.\n\n#### Path-scoped rules (`.claude/rules/`)\n\nThese load **automatically** when you touch matching files — you don't invoke them. They hold the non-obvious, subsystem-specific conventions so this always-loaded file stays lean:\n\n| Rule | Applies to | Covers |\n|------|-----------|--------|\n| `code-style.md` | `src/**/*.cs` | nullable, file headers (MUX/MIT), logging, `[Uno.NotImplemented]` |\n| `platform-targeting.md` | `src/**/*.cs` | file-suffix vs `#if` vs `OperatingSystem.IsX()` vs `ApiExtensibility` |\n| `debugging-discipline.md` | `src/**/*.cs` | full root-cause/validation/diagnosis-bias protocols |\n| `dependency-properties.md` | `src/Uno.UI/**` | `[GeneratedDependencyProperty]`, metadata, callbacks |\n| `runtime-tests.md` | `src/Uno.UI.RuntimeTests/**` | `[RunsOnUIThread]`, `[PlatformCondition]`, `UITestHelper` |\n| `unit-tests.md` | `src/Uno.UI.UnitTests/**` | MSTest, no-visual-tree logic tests |\n| `source-generators.md` | `src/SourceGenerators/**` | incremental gens, LOH/perf, cancellation |\n| `samples.md` | `src/SamplesApp/**` | `[Sample]`, theming, XamlStyler |\n| `build-system.md` | `src/**/*.{csproj,props,targets}` | TFMs, output paths, package versions |\n\n**Which to reach for:** the relevant `.claude/rules/*.md` is already in context (path-scoped) — use it as the checklist. Use a `/skill` for the actual build/run/scaffold/port workflow (and its deep reference).\n\n---\n\n## Quick Reference\n\n### Technology Stack\n\n| Technology | Purpose |\n|------------|---------|\n| .NET 10.0/9.0 | Multi-target framework |\n| C# & XAML | Primary languages |\n| TypeScript | WebAssembly/Web APIs only |\n| Skia | Cross-platform rendering |\n| MSBuild | Build orchestration |\n| Roslyn | Source generators |\n\n### Platform File Suffixes\n\n| Suffix | Platform |\n|--------|----------|\n| `.Android.cs` | Android |\n| `.iOS.cs` | iOS |\n| `.UIKit.cs` | iOS & tvOS |\n| `.wasm.cs` | WebAssembly |\n| `.skia.cs` | Skia |\n| `.reference.cs` | Reference implementation |\n| `.crossruntime.cs` | Skia + WebAssembly + Reference (shared) |\n\n### Key Source Directories\n\n- `src/Uno.UI/` - Core UI framework (WinUI controls, layout, XAML runtime)\n- `src/Uno.UWP/` - Non-UI WinRT APIs (platform-specific assemblies)\n- `src/Uno.Foundation/` - Foundation APIs (platform-specific assemblies)\n- `src/Uno.UI.Runtime.Skia.*/` - Skia platform runtimes\n- `src/SourceGenerators/` - XAML parser, DependencyProperty generator\n- `src/SamplesApp/` - Sample app for validation and tests\n- `src/Uno.UI.RuntimeTests/` - Platform runtime tests\n- `src/Uno.UI.DevServer.Cli/` - DevServer CLI tool\n- `src/Uno.UI.RemoteControl.Host/` - DevServer Host process\n\n### Build Setup (Required)\n\n**1. Setup cross-targeting override:**\n```bash\ncd src\ncp crosstargeting_override.props.sample crosstargeting_override.props\n```\n\n**2. Edit `crosstargeting_override.props`** (recommended fast-iteration config):\n```xml\n<Project>\n  <PropertyGroup>\n    <!-- Choose ONE target: -->\n    <UnoTargetFrameworkOverride>net10.0</UnoTargetFrameworkOverride>              <!-- WebAssembly/Skia -->\n    <!-- <UnoTargetFrameworkOverride>net10.0-android</UnoTargetFrameworkOverride>  Android -->\n    <!-- <UnoTargetFrameworkOverride>net10.0-ios</UnoTargetFrameworkOverride>      iOS -->\n    <!-- <UnoTargetFrameworkOverride>net10.0-windows10.0.19041.0</UnoTargetFrameworkOverride> Windows -->\n\n    <!-- Disables analyzers + code-style enforcement for local builds. No effect on CI. -->\n    <UnoFastDevBuild>true</UnoFastDevBuild>\n  </PropertyGroup>\n</Project>\n```\n\nOr pass the same flags per-build instead of committing them:\n\n```bash\ndotnet build … -p:UnoTargetFrameworkOverride=net10.0 -p:UnoFastDevBuild=true\n```\n\n**Why these flags:**\n- `UnoTargetFrameworkOverride` — restricts cross-targeted projects to a single TFM, skipping the redundant net9.0 outputs while you iterate on net10.0 (or vice versa).\n- `UnoFastDevBuild` — disables `RunAnalyzersDuringBuild`, `EnforceCodeStyleInBuild`, and the `Microsoft.CodeAnalysis.NetAnalyzers` package for local builds. **Guarded by `ContinuousIntegrationBuild`, so CI is never affected** — analyzer-strict checks still run on every PR. Set persistently via the `UNO_FAST_DEV_BUILD=true` environment variable if you'd rather not edit the file.\n\nCombined impact on `SamplesApp.Skia.Generic` (Windows, 32-core, warm NuGet cache): clean build ~3:23 → ~1:59, incremental rebuild after a Uno.UI edit ~2:23 → ~0:58. The `/runtime-tests` skill passes both flags by default (use `strict` to opt out for CI-equivalent coverage).\n\n**Do not commit `crosstargeting_override.props`** — it is per-developer config and is intentionally `.gitignore`d.\n\n**3. Use matching solution filter:**\n\n| Platform | Solution Filter |\n|----------|-----------------|\n| WebAssembly | `Uno.UI-Wasm-only.slnf` |\n| Skia (Desktop) | `Uno.UI-Skia-only.slnf` |\n| Mobile (Android/iOS) | `Uno.UI-netcore-mobile-only.slnf` |\n| Windows | `Uno.UI-Windows-only.slnf` |\n| Unit Tests | `Uno.UI-UnitTests-only.slnf` |\n\n**4. Build commands:**\n```bash\ncd src\ndotnet restore Uno.UI-Skia-only.slnf                    # Restore (50-60s)\ndotnet build Uno.UI-Skia-only.slnf --no-restore         # Build (3-5min)\ndotnet test Uno.UI.UnitTests/Uno.UI.UnitTests.csproj    # Unit tests (40-60s)\n```\n\n**CRITICAL**: **NEVER CANCEL** builds. Set timeouts to 15+ minutes. Favor Skia desktop for faster builds.\n\n---\n\n## Architecture Overview\n\n### Platform Abstraction\n\nSingle C#/XAML codebase → WinUI 3 API → Platform-specific runtimes (Skia, WebAssembly, Native)\n\n### Rendering Engines\n\n- **Skia**: Cross-platform (Desktop Win32, macOS, Linux, Skia Android/iOS)\n- **Native**: Platform controls (UIKit, Android Views, DOM elements)\n\n### Development scope: Skia-first (IMPORTANT)\n\n**Unless a task explicitly states otherwise, new features and enhancements target the Skia targets only** (Desktop Win32/macOS/Linux and Skia-on-Android/iOS/WASM). The **native targets** — native Android Views, native iOS/UIKit, WASM DOM — are **maintenance-only**: don't build new features for them, but **don't break them either** (keep them compiling and behaving as-is).\n\nThis applies to the **UI rendering layer** (`Uno.UI` native views), *not* to platform APIs. **Platform-specific non-UI WinRT APIs (in `Uno.UWP`/`Uno.Foundation`) are still actively enhanced**, because the Skia targets compile and consume those same per-platform implementations (e.g. Skia-on-Android uses the Android implementation of a file picker, sensor, contacts, etc.).\n\n### Platform Base Classes\n\n| Platform | Inheritance |\n|----------|-------------|\n| Android native | `ViewGroup` → `UnoViewGroup` (Java) → `BindableView` → `UIElement` |\n| iOS native | `UIView` → `BindableUIView` → `UIElement` |\n| WebAssembly native | UIElements map to DOM elements (default: \"div\") |\n| Skia | `IRenderer` interface for rendering pipeline |\n\n### XAML Compilation\n\nXAML files are parsed to C# via source generators (`XamlFileGenerator` in `Uno.UI.SourceGenerators`), not .xbf like WinUI. Generates `InitializeComponent()`, named fields, and x:Bind expressions.\n\n### DependencyObject on Mobile\n\nOn Android/iOS, `DependencyObject` is an **interface** (not base class) since `UIElement` must inherit from native view classes. Source generators provide the implementation via `DependencyObjectGenerator`.\n\n### Project Organization\n\nMost libraries have 5 variants: Reference, Skia, WebAssembly, NetCoreMobile, Tests.\n\n### Runtime Target Selection\n\nFor Skia, `RuntimeAssetsSelectorTask` ensures `Uno.UI` uses `netX` (generic) target for all Skia platforms. `Uno.UWP` and `Uno.Foundation` use platform-specific assemblies. Use runtime checks like `OperatingSystem.IsAndroid()` for platform-specific behavior on Skia for libraries above and including `Uno.UI`, or use `ApiExtensibility` with platform-specific implementations in `Runtime.Skia` projects.\n\n### NotImplemented Stubs\n\nAuto-generated stubs marked with `[Uno.NotImplemented]` allow compilation but warn if used. Located in `Generated` folders - never edit these files.\n\n---\n\n## Development Workflow\n\n### Public Documentation and Spec References (MANDATORY)\n\nWhen editing specifications, documentation, or other repo-tracked design artifacts intended to be shareable:\n\n1. **Do not reference private artifacts** from the document.\n   - Do not link to private issues, private pull requests, private boards, private docs, or private repositories.\n   - If related work is tracked privately, mention it only in generic terms.\n\n2. **Public specs are source-of-truth documents**.\n   - Public or repo-local specs may be referenced by private trackers.\n   - Private trackers must not be required to understand the public spec.\n\n3. **Keep the dependency direction one-way**.\n   - Allowed: private issues/PRs referencing a public spec in this repo.\n   - Not allowed: a public spec in this repo referencing a private issue/PR/doc as normative context.\n\n4. **If implementation follow-up exists in private repos**, describe it as alignment or downstream tracking work without identifiers or URLs.\n\n### Debugging & Validation (MANDATORY — summary)\n\nWhen fixing crashes, rendering, or selection/indexing bugs: **reproduce first → name the broken invariant → fix the root cause (and the mutation point) before adding guards → prove it with a test that fails-before/passes-after → validate at runtime, not compile-only.** Label every proposed change `root-cause fix` or `defensive hardening`; a guard-only change is never a complete resolution. Report validation evidence with explicit labels — **Code review** (by inspection) vs **Compile** (which project built) vs **Runtime** (which test/app ran) — and never present compile-only as runtime validation.\n\nThe full protocol (root-cause steps, diagnosis-bias checks, evidence rules) auto-loads from `.claude/rules/debugging-discipline.md` when editing `src/**/*.cs`.\n\n### Validation Checklist\n\nRun these after making changes:\n\n1. **Build**: `dotnet build Uno.UI-UnitTests-only.slnf --no-restore`\n2. **Unit tests**: `dotnet test Uno.UI.UnitTests/Uno.UI.UnitTests.csproj --no-build`\n3. **Runtime tests** (UI changes): Use `/runtime-tests` skill (Skia Desktop default, pass test class/method name as argument)\n4. **WinUI parity** (validate against native WinUI): Use `/winui-runtime-tests` skill\n5. **Sample app** (visual changes): `cd src/SamplesApp/SamplesApp.Wasm && dotnet run`\n6. **XAML formatting** (SamplesApp changes): `dotnet xstyler -d src/SamplesApp -r`\n\n### SamplesApp: Add XAML files\n\nWhen adding XAML samples to the `SamplesApp`, drop the files anywhere under `src/SamplesApp/SamplesApp.Samples/` — they are auto-discovered by glob (no manual registration required).\n\nSample creation checklist:\n1. Create your sample XAML and code-behind under an appropriate folder in `src/SamplesApp/SamplesApp.Samples/`.\n2. Add the `[Uno.UI.Samples.Controls.Sample]` attribute to the code-behind class.\n3. Format XAML: `dotnet xstyler -f src/SamplesApp/SamplesApp.Samples/YourFolder/YourSample.xaml`\n4. Build and run `SamplesApp` to verify the sample appears.\n\nTheming guideline (brief): prefer `{ThemeResource}` for backgrounds/foregrounds so samples work in light and dark themes.\n\n### Runtime Tests (Preferred for UI)\n\nAdd tests to `Uno.UI.RuntimeTests`. Key helpers:\n- `WindowHelper.WindowContent` - Add elements to visual tree\n- `await WindowHelper.WaitForLoaded(element)` - Wait for load\n- `await WindowHelper.WaitForIdle()` - Wait for UI to settle\n\n**To build and run tests, use the `/runtime-tests` skill.** It handles build, filter encoding, execution, and result parsing for both Skia Desktop and WASM. Test-authoring conventions auto-load from `.claude/rules/runtime-tests.md`.\n\n### Common Build Issues\n\n| Issue | Solution |\n|-------|----------|\n| \"Assets file doesn't have a target\" | Delete `obj/`, `bin/`, restore |\n| \"Windows XAML targets not found\" | Use Skia/Wasm on Linux/macOS |\n| Solution filter fails | Ensure `crosstargeting_override.props` matches filter |\n| Persistent issues | Close VS, delete `src/.vs`, rebuild |\n| Last resort | `git clean -fdx` (close VS first) |\n\n### Key Build Properties\n\n| Property | Purpose |\n|----------|---------|\n| `UnoTargetFrameworkOverride` | Single platform target |\n| `UnoNugetOverrideVersion` | Debug with NuGet override |\n| `UnoUISourceGeneratorDebuggerBreak` | Attach debugger to generators |\n| `XamlSourceGeneratorTracingFolder` | Dump generator diagnostics |\n\n---\n\n## Code Conventions\n\n### Partial Classes\n\nExtensive use for:\n- Platform-specific code: `MyControl.Android.cs`, `MyControl.iOS.cs`\n- Generated code: `MyPage.xaml.g.cs`\n- Logical separation: `MyControl.Properties.cs` for DependencyProperties\n\n### DependencyProperty Pattern\n\nPrefer `[GeneratedDependencyProperty]` for new properties. Conventions auto-load from `.claude/rules/dependency-properties.md`; for full templates copy from existing controls (`Canvas`, `RangeBase`, `Button`).\n\n### Code Style\n\nTabs, Allman braces (always), expression-bodied members for one-liners, `internal` extension methods in `[Type]Extensions.cs`, `#nullable enable` per-file, MUX/MIT headers on ported code. Comments only when they add value — short (a line or two, never a wall of text), explaining the non-obvious *why*, never narrating code removal/history; longer is OK only when explicitly requested, actually needed for code understanding, or carried verbatim from a WinUI port. Details auto-load from `.claude/rules/code-style.md`. Style is analyzer-enforced on CI even when `UnoFastDevBuild=true` skips it locally.\n\n### Events\n\n🚫 **NEVER declare `event Action` or `event Action<T>`**. Always use `EventHandler` or\n`EventHandler<TEventArgs>`. Raw `Action`/`Func` delegates as event fields bypass the\nstandard `add`/`remove` contract and cannot be reliably subscribed across assembly\nboundaries.\n\n✅ Correct:\n```csharp\npublic event EventHandler<MyEventArgs>? SomethingHappened;\n```\n\n🚫 Wrong — every agent must reject this:\n```csharp\npublic event Action<MyData>? SomethingHappened; // NEVER\n```\n\n### XAML Formatting (SamplesApp)\n\nXAML files under `src/SamplesApp/` are formatted using [XamlStyler](https://github.com/Xavalon/XamlStyler).\nConfiguration is in `src/SamplesApp/Settings.XamlStyler`.\n\n```bash\n# One-time setup (restore tools after cloning)\ndotnet tool restore\n\n# Format all SamplesApp XAML files\ndotnet xstyler -d src/SamplesApp -r\n\n# Format a single file\ndotnet xstyler -f src/SamplesApp/SamplesApp.Samples/MyFile.xaml\n\n# Check without modifying (CI mode)\ndotnet xstyler -d src/SamplesApp -r -p\n```\n\nA GitHub Actions workflow enforces formatting on PRs that touch SamplesApp XAML files.\n\n### Implementing New WinUI Features\n\n1. Find generated stub: `src/Uno.UWP/Generated/3.0.0.0/Windows.*/ClassName.cs`\n2. Copy to non-generated location\n3. Remove implemented platforms from `[NotImplemented]` attribute\n4. Use platform suffix for platform-specific files\n\n---\n\n## Common Pitfalls\n\n1. **DependencyObject is an interface** on Android/iOS - don't inherit, implement\n2. **Generated files are regenerated** - never edit `Generated/` folders\n3. **Visual tree differs by platform** - Android/iOS use native hierarchy; WebAssembly uses DOM; Skia uses rendering tree\n4. **Partial methods** used for extensibility: `OnLoaded()`, `OnUnloaded()`\n5. **NuGet cache corruption** - delete `%USERPROFILE%\\.nuget\\packages\\uno.ui` if debugging fails\n6. **Long paths on Windows** - enable via registry if needed\n\n---\n\n## Commit Guidelines\n\n**MANDATORY**: All commits MUST follow [Conventional Commits](https://www.conventionalcommits.org/).\n\n### Format\n```\n<type>[optional scope]: <description>\n```\n\n### Common Types\n\n| Type | Purpose | Version Impact |\n|------|---------|----------------|\n| `fix` | Bug fixes | PATCH |\n| `feat` | New features | MINOR |\n| `docs` | Documentation | - |\n| `test` | Tests | - |\n| `chore` | Maintenance | - |\n| `feat!` | Breaking change | MAJOR |\n\n### Examples\n```bash\ngit commit -m \"chore: Initial work\"\ngit commit -m \"fix: Resolve null reference in TextBox\"\ngit commit -m \"feat(ios): Implement native picker control\"\ngit commit -m \"feat!: Remove deprecated API methods\"\n```\n\nGuidelines:\n- Keep description under 50 characters\n- Use imperative mood (\"Add\" not \"Added\")\n- Reference issues: `fix: Resolve layout issue (fixes #12345)`\n- **Commit cadence**: when the user asks, or when working autonomously on a larger feature, commit in **logical groups** — one focused, Conventional-Commit-formatted commit per coherent chunk that builds clean, rather than one batch at the end. On complex work, these incremental commits also let reviewers follow the progression of the change rather than facing one giant diff. For small one-off edits in an interactive session, leave changes uncommitted unless asked.\n\n### Pull Requests & Issues\n\nWhen asked to open a PR or file an issue, **base it on the repo's existing templates** (filled out accordingly) — don't free-form:\n- **PRs** → fill out every section of `.github/PULL_REQUEST_TEMPLATE.md` and submit it as the body (e.g. `gh pr create --body-file <filled>.md`).\n- **Issues** → pick the matching GitHub issue **form** under `.github/ISSUE_TEMPLATE/` (`bug-report`, `enhancement`, `documentation-issue`/`-request`, `samples-issue`/`-request`, `feedback`, `support-request`, `success-story`) and fill its required fields (`gh issue create --template <name>.yml`).\n- **Every PR must reference an associated issue** (unless it's a pure-documentation change). Before opening the PR, settle the issue: use the one identified in the conversation; else search for an existing match (`gh issue list --search \"<keywords>\"`); else create one from the forms above. Put its number on the template's first line — `**GitHub Issue:** closes #XYZ` — so merging the PR auto-closes the issue.\n\n---\n\n## References\n\n### Documentation\n- [Building Uno](https://platform.uno/docs/articles/uno-development/building-uno-ui.html)\n- [Contributing Guide](https://platform.uno/docs/articles/uno-development/contributing-intro.html)\n- [Creating Tests](https://platform.uno/docs/articles/contributing/guidelines/creating-tests.html)\n\n### In-Repo Docs\n- Build guide: `doc/articles/uno-development/building-uno-ui.md`\n- Samples guide: `doc/articles/uno-development/working-with-the-samples-apps.md`\n\n### Subsystem deep dives\n- `/winui-port` skill - WinUI C++ → C# porting\n- `/devserver` skill - DevServer CLI/Host maintenance\n- `/runtime-tests` skill + `.claude/rules/runtime-tests.md` - runtime test execution & authoring\n- `.claude/rules/dependency-properties.md` - DependencyProperty patterns\n- `.claude/rules/source-generators.md` - XAML/DependencyObject generators\n\n### Community\n- [Discord](https://platform.uno/discord)\n- [Samples App](https://aka.platform.uno/wasm-samples-app)\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nFollow instructions in @AGENTS.md\n\n<!-- SPECKIT START -->\nFor additional context about technologies to be used, project structure,\nshell commands, and other important information, read the current plan:\n`specs/003-wasm-a11y-remediation/plan.md`\n<!-- SPECKIT END -->\n","AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI Agents when working with code in this repository.\n\n## Project Overview\n\nUno Platform is an open-source .NET UI cross-platform framework for building .NET applications from a single codebase using the WinUI 3 API. It targets Web (WebAssembly), Desktop (Windows, macOS, Linux via Skia), and Mobile (iOS, tvOS, Android).\n\n**Reference these instructions first**, then lean on skills (workflows) and the path-scoped rules below.\n\n#### Claude Code Skills (invoke via `/skill-name`)\n\n| Skill | Command | Use For |\n|-------|---------|---------|\n| Add Sample | `/add-sample` | Creating SamplesApp sample pages with correct registration |\n| Runtime Tests | `/runtime-tests` | Building and running Uno runtime tests (Skia Desktop/WASM) |\n| WinUI Runtime Tests | `/winui-runtime-tests` | Running runtime tests against native WinUI on Windows |\n| WinUI Porting | `/winui-port` | Porting WinUI C++ code to Uno Platform C# (full deep reference) |\n| DevServer | `/devserver` | DevServer CLI/Host build, test, MCP proxy, add-in discovery |\n| Docs Build | `/docs-build` | Building, previewing & validating the docs website (DocFX), incl. external-doc commit bumps in `import_external_docs.ps1` |\n\n#### Pre-commit review (invoke via `/review-panel`)\n\n`/review-panel [scope]` runs an eight-lens reviewer panel (architect, contract, skeptic, performance, operability, quality, security, jerome) in parallel and synthesizes one report with a `ship` / `fix-first` / `block-merge` verdict. Run it before you commit or open a PR — pass a scope (`master..HEAD`, a `#PR`, `HEAD~1`) or omit it to auto-detect uncommitted changes / branch-vs-`master`. The panel learns from corrections recorded in `specs/lessons.md`. Lenses, scopes, and loop recipes: `.claude/review-panel-cheatsheet.md`.\n\n#### Path-scoped rules (`.claude/rules/`)\n\nThese load **automatically** when you touch matching files — you don't invoke them. They hold the non-obvious, subsystem-specific conventions so this always-loaded file stays lean:\n\n| Rule | Applies to | Covers |\n|------|-----------|--------|\n| `code-style.md` | `src/**/*.cs` | nullable, file headers (MUX/MIT), logging, `[Uno.NotImplemented]` |\n| `platform-targeting.md` | `src/**/*.cs` | file-suffix vs `#if` vs `OperatingSystem.IsX()` vs `ApiExtensibility` |\n| `debugging-discipline.md` | `src/**/*.cs` | full root-cause/validation/diagnosis-bias protocols |\n| `dependency-properties.md` | `src/Uno.UI/**` | `[GeneratedDependencyProperty]`, metadata, callbacks |\n| `runtime-tests.md` | `src/Uno.UI.RuntimeTests/**` | `[RunsOnUIThread]`, `[PlatformCondition]`, `UITestHelper` |\n| `unit-tests.md` | `src/Uno.UI.UnitTests/**` | MSTest, no-visual-tree logic tests |\n| `source-generators.md` | `src/SourceGenerators/**` | incremental gens, LOH/perf, cancellation |\n| `samples.md` | `src/SamplesApp/**` | `[Sample]`, theming, XamlStyler |\n| `build-system.md` | `src/**/*.{csproj,props,targets}` | TFMs, output paths, package versions |\n\n**Which to reach for:** the relevant `.claude/rules/*.md` is already in context (path-scoped) — use it as the checklist. Use a `/skill` for the actual build/run/scaffold/port workflow (and its deep reference).\n\n---\n\n## Quick Reference\n\n### Technology Stack\n\n| Technology | Purpose |\n|------------|---------|\n| .NET 10.0/9.0 | Multi-target framework |\n| C# & XAML | Primary languages |\n| TypeScript | WebAssembly/Web APIs only |\n| Skia | Cross-platform rendering |\n| MSBuild | Build orchestration |\n| Roslyn | Source generators |\n\n### Platform File Suffixes\n\n| Suffix | Platform |\n|--------|----------|\n| `.Android.cs` | Android |\n| `.iOS.cs` | iOS |\n| `.UIKit.cs` | iOS & tvOS |\n| `.wasm.cs` | WebAssembly |\n| `.skia.cs` | Skia |\n| `.reference.cs` | Reference implementation |\n| `.crossruntime.cs` | Skia + WebAssembly + Reference (shared) |\n\n### Key Source Directories\n\n- `src/Uno.UI/` - Core UI framework (WinUI controls, layout, XAML runtime)\n- `src/Uno.UWP/` - Non-UI WinRT APIs (platform-specific assemblies)\n- `src/Uno.Foundation/` - Foundation APIs (platform-specific assemblies)\n- `src/Uno.UI.Runtime.Skia.*/` - Skia platform runtimes\n- `src/SourceGenerators/` - XAML parser, DependencyProperty generator\n- `src/SamplesApp/` - Sample app for validation and tests\n- `src/Uno.UI.RuntimeTests/` - Platform runtime tests\n- `src/Uno.UI.DevServer.Cli/` - DevServer CLI tool\n- `src/Uno.UI.RemoteControl.Host/` - DevServer Host process\n\n### Build Setup (Required)\n\n**1. Setup cross-targeting override:**\n```bash\ncd src\ncp crosstargeting_override.props.sample crosstargeting_override.props\n```\n\n**2. Edit `crosstargeting_override.props`** (recommended fast-iteration config):\n```xml\n<Project>\n  <PropertyGroup>\n    <!-- Choose ONE target: -->\n    <UnoTargetFrameworkOverride>net10.0</UnoTargetFrameworkOverride>              <!-- WebAssembly/Skia -->\n    <!-- <UnoTargetFrameworkOverride>net10.0-android</UnoTargetFrameworkOverride>  Android -->\n    <!-- <UnoTargetFrameworkOverride>net10.0-ios</UnoTargetFrameworkOverride>      iOS -->\n    <!-- <UnoTargetFrameworkOverride>net10.0-windows10.0.19041.0</UnoTargetFrameworkOverride> Windows -->\n\n    <!-- Disables analyzers + code-style enforcement for local builds. No effect on CI. -->\n    <UnoFastDevBuild>true</UnoFastDevBuild>\n  </PropertyGroup>\n</Project>\n```\n\nOr pass the same flags per-build instead of committing them:\n\n```bash\ndotnet build … -p:UnoTargetFrameworkOverride=net10.0 -p:UnoFastDevBuild=true\n```\n\n**Why these flags:**\n- `UnoTargetFrameworkOverride` — restricts cross-targeted projects to a single TFM, skipping the redundant net9.0 outputs while you iterate on net10.0 (or vice versa).\n- `UnoFastDevBuild` — disables `RunAnalyzersDuringBuild`, `EnforceCodeStyleInBuild`, and the `Microsoft.CodeAnalysis.NetAnalyzers` package for local builds. **Guarded by `ContinuousIntegrationBuild`, so CI is never affected** — analyzer-strict checks still run on every PR. Set persistently via the `UNO_FAST_DEV_BUILD=true` environment variable if you'd rather not edit the file.\n\nCombined impact on `SamplesApp.Skia.Generic` (Windows, 32-core, warm NuGet cache): clean build ~3:23 → ~1:59, incremental rebuild after a Uno.UI edit ~2:23 → ~0:58. The `/runtime-tests` skill passes both flags by default (use `strict` to opt out for CI-equivalent coverage).\n\n**Do not commit `crosstargeting_override.props`** — it is per-developer config and is intentionally `.gitignore`d.\n\n**3. Use matching solution filter:**\n\n| Platform | Solution Filter |\n|----------|-----------------|\n| WebAssembly | `Uno.UI-Wasm-only.slnf` |\n| Skia (Desktop) | `Uno.UI-Skia-only.slnf` |\n| Mobile (Android/iOS) | `Uno.UI-netcore-mobile-only.slnf` |\n| Windows | `Uno.UI-Windows-only.slnf` |\n| Unit Tests | `Uno.UI-UnitTests-only.slnf` |\n\n**4. Build commands:**\n```bash\ncd src\ndotnet restore Uno.UI-Skia-only.slnf                    # Restore (50-60s)\ndotnet build Uno.UI-Skia-only.slnf --no-restore         # Build (3-5min)\ndotnet test Uno.UI.UnitTests/Uno.UI.UnitTests.csproj    # Unit tests (40-60s)\n```\n\n**CRITICAL**: **NEVER CANCEL** builds. Set timeouts to 15+ minutes. Favor Skia desktop for faster builds.\n\n---\n\n## Architecture Overview\n\n### Platform Abstraction\n\nSingle C#/XAML codebase → WinUI 3 API → Platform-specific runtimes (Skia, WebAssembly, Native)\n\n### Rendering Engines\n\n- **Skia**: Cross-platform (Desktop Win32, macOS, Linux, Skia Android/iOS)\n- **Native**: Platform controls (UIKit, Android Views, DOM elements)\n\n### Development scope: Skia-first (IMPORTANT)\n\n**Unless a task explicitly states otherwise, new features and enhancements target the Skia targets only** (Desktop Win32/macOS/Linux and Skia-on-Android/iOS/WASM). The **native targets** — native Android Views, native iOS/UIKit, WASM DOM — are **maintenance-only**: don't build new features for them, but **don't break them either** (keep them compiling and behaving as-is).\n\nThis applies to the **UI rendering layer** (`Uno.UI` native views), *not* to platform APIs. **Platform-specific non-UI WinRT APIs (in `Uno.UWP`/`Uno.Foundation`) are still actively enhanced**, because the Skia targets compile and consume those same per-platform implementations (e.g. Skia-on-Android uses the Android implementation of a file picker, sensor, contacts, etc.).\n\n### Platform Base Classes\n\n| Platform | Inheritance |\n|----------|-------------|\n| Android native | `ViewGroup` → `UnoViewGroup` (Java) → `BindableView` → `UIElement` |\n| iOS native | `UIView` → `BindableUIView` → `UIElement` |\n| WebAssembly native | UIElements map to DOM elements (default: \"div\") |\n| Skia | `IRenderer` interface for rendering pipeline |\n\n### XAML Compilation\n\nXAML files are parsed to C# via source generators (`XamlFileGenerator` in `Uno.UI.SourceGenerators`), not .xbf like WinUI. Generates `InitializeComponent()`, named fields, and x:Bind expressions.\n\n### DependencyObject on Mobile\n\nOn Android/iOS, `DependencyObject` is an **interface** (not base class) since `UIElement` must inherit from native view classes. Source generators provide the implementation via `DependencyObjectGenerator`.\n\n### Project Organization\n\nMost libraries have 5 variants: Reference, Skia, WebAssembly, NetCoreMobile, Tests.\n\n### Runtime Target Selection\n\nFor Skia, `RuntimeAssetsSelectorTask` ensures `Uno.UI` uses `netX` (generic) target for all Skia platforms. `Uno.UWP` and `Uno.Foundation` use platform-specific assemblies. Use runtime checks like `OperatingSystem.IsAndroid()` for platform-specific behavior on Skia for libraries above and including `Uno.UI`, or use `ApiExtensibility` with platform-specific implementations in `Runtime.Skia` projects.\n\n### NotImplemented Stubs\n\nAuto-generated stubs marked with `[Uno.NotImplemented]` allow compilation but warn if used. Located in `Generated` folders - never edit these files.\n\n---\n\n## Development Workflow\n\n### Public Documentation and Spec References (MANDATORY)\n\nWhen editing specifications, documentation, or other repo-tracked design artifacts intended to be shareable:\n\n1. **Do not reference private artifacts** from the document.\n   - Do not link to private issues, private pull requests, private boards, private docs, or private repositories.\n   - If related work is tracked privately, mention it only in generic terms.\n\n2. **Public specs are source-of-truth documents**.\n   - Public or repo-local specs may be referenced by private trackers.\n   - Private trackers must not be required to understand the public spec.\n\n3. **Keep the dependency direction one-way**.\n   - Allowed: private issues/PRs referencing a public spec in this repo.\n   - Not allowed: a public spec in this repo referencing a private issue/PR/doc as normative context.\n\n4. **If implementation follow-up exists in private repos**, describe it as alignment or downstream tracking work without identifiers or URLs.\n\n### Debugging & Validation (MANDATORY — summary)\n\nWhen fixing crashes, rendering, or selection/indexing bugs: **reproduce first → name the broken invariant → fix the root cause (and the mutation point) before adding guards → prove it with a test that fails-before/passes-after → validate at runtime, not compile-only.** Label every proposed change `root-cause fix` or `defensive hardening`; a guard-only change is never a complete resolution. Report validation evidence with explicit labels — **Code review** (by inspection) vs **Compile** (which project built) vs **Runtime** (which test/app ran) — and never present compile-only as runtime validation.\n\nThe full protocol (root-cause steps, diagnosis-bias checks, evidence rules) auto-loads from `.claude/rules/debugging-discipline.md` when editing `src/**/*.cs`.\n\n### Validation Checklist\n\nRun these after making changes:\n\n1. **Build**: `dotnet build Uno.UI-UnitTests-only.slnf --no-restore`\n2. **Unit tests**: `dotnet test Uno.UI.UnitTests/Uno.UI.UnitTests.csproj --no-build`\n3. **Runtime tests** (UI changes): Use `/runtime-tests` skill (Skia Desktop default, pass test class/method name as argument)\n4. **WinUI parity** (validate against native WinUI): Use `/winui-runtime-tests` skill\n5. **Sample app** (visual changes): `cd src/SamplesApp/SamplesApp.Wasm && dotnet run`\n6. **XAML formatting** (SamplesApp changes): `dotnet xstyler -d src/SamplesApp -r`\n\n### SamplesApp: Add XAML files\n\nWhen adding XAML samples to the `SamplesApp`, drop the files anywhere under `src/SamplesApp/SamplesApp.Samples/` — they are auto-discovered by glob (no manual registration required).\n\nSample creation checklist:\n1. Create your sample XAML and code-behind under an appropriate folder in `src/SamplesApp/SamplesApp.Samples/`.\n2. Add the `[Uno.UI.Samples.Controls.Sample]` attribute to the code-behind class.\n3. Format XAML: `dotnet xstyler -f src/SamplesApp/SamplesApp.Samples/YourFolder/YourSample.xaml`\n4. Build and run `SamplesApp` to verify the sample appears.\n\nTheming guideline (brief): prefer `{ThemeResource}` for backgrounds/foregrounds so samples work in light and dark themes.\n\n### Runtime Tests (Preferred for UI)\n\nAdd tests to `Uno.UI.RuntimeTests`. Key helpers:\n- `WindowHelper.WindowContent` - Add elements to visual tree\n- `await WindowHelper.WaitForLoaded(element)` - Wait for load\n- `await WindowHelper.WaitForIdle()` - Wait for UI to settle\n\n**To build and run tests, use the `/runtime-tests` skill.** It handles build, filter encoding, execution, and result parsing for both Skia Desktop and WASM. Test-authoring conventions auto-load from `.claude/rules/runtime-tests.md`.\n\n### Common Build Issues\n\n| Issue | Solution |\n|-------|----------|\n| \"Assets file doesn't have a target\" | Delete `obj/`, `bin/`, restore |\n| \"Windows XAML targets not found\" | Use Skia/Wasm on Linux/macOS |\n| Solution filter fails | Ensure `crosstargeting_override.props` matches filter |\n| Persistent issues | Close VS, delete `src/.vs`, rebuild |\n| Last resort | `git clean -fdx` (close VS first) |\n\n### Key Build Properties\n\n| Property | Purpose |\n|----------|---------|\n| `UnoTargetFrameworkOverride` | Single platform target |\n| `UnoNugetOverrideVersion` | Debug with NuGet override |\n| `UnoUISourceGeneratorDebuggerBreak` | Attach debugger to generators |\n| `XamlSourceGeneratorTracingFolder` | Dump generator diagnostics |\n\n---\n\n## Code Conventions\n\n### Partial Classes\n\nExtensive use for:\n- Platform-specific code: `MyControl.Android.cs`, `MyControl.iOS.cs`\n- Generated code: `MyPage.xaml.g.cs`\n- Logical separation: `MyControl.Properties.cs` for DependencyProperties\n\n### DependencyProperty Pattern\n\nPrefer `[GeneratedDependencyProperty]` for new properties. Conventions auto-load from `.claude/rules/dependency-properties.md`; for full templates copy from existing controls (`Canvas`, `RangeBase`, `Button`).\n\n### Code Style\n\nTabs, Allman braces (always), expression-bodied members for one-liners, `internal` extension methods in `[Type]Extensions.cs`, `#nullable enable` per-file, MUX/MIT headers on ported code. Comments only when they add value — short (a line or two, never a wall of text), explaining the non-obvious *why*, never narrating code removal/history; longer is OK only when explicitly requested, actually needed for code understanding, or carried verbatim from a WinUI port. Details auto-load from `.claude/rules/code-style.md`. Style is analyzer-enforced on CI even when `UnoFastDevBuild=true` skips it locally.\n\n### Events\n\n🚫 **NEVER declare `event Action` or `event Action<T>`**. Always use `EventHandler` or\n`EventHandler<TEventArgs>`. Raw `Action`/`Func` delegates as event fields bypass the\nstandard `add`/`remove` contract and cannot be reliably subscribed across assembly\nboundaries.\n\n✅ Correct:\n```csharp\npublic event EventHandler<MyEventArgs>? SomethingHappened;\n```\n\n🚫 Wrong — every agent must reject this:\n```csharp\npublic event Action<MyData>? SomethingHappened; // NEVER\n```\n\n### XAML Formatting (SamplesApp)\n\nXAML files under `src/SamplesApp/` are formatted using [XamlStyler](https://github.com/Xavalon/XamlStyler).\nConfiguration is in `src/SamplesApp/Settings.XamlStyler`.\n\n```bash\n# One-time setup (restore tools after cloning)\ndotnet tool restore\n\n# Format all SamplesApp XAML files\ndotnet xstyler -d src/SamplesApp -r\n\n# Format a single file\ndotnet xstyler -f src/SamplesApp/SamplesApp.Samples/MyFile.xaml\n\n# Check without modifying (CI mode)\ndotnet xstyler -d src/SamplesApp -r -p\n```\n\nA GitHub Actions workflow enforces formatting on PRs that touch SamplesApp XAML files.\n\n### Implementing New WinUI Features\n\n1. Find generated stub: `src/Uno.UWP/Generated/3.0.0.0/Windows.*/ClassName.cs`\n2. Copy to non-generated location\n3. Remove implemented platforms from `[NotImplemented]` attribute\n4. Use platform suffix for platform-specific files\n\n---\n\n## Common Pitfalls\n\n1. **DependencyObject is an interface** on Android/iOS - don't inherit, implement\n2. **Generated files are regenerated** - never edit `Generated/` folders\n3. **Visual tree differs by platform** - Android/iOS use native hierarchy; WebAssembly uses DOM; Skia uses rendering tree\n4. **Partial methods** used for extensibility: `OnLoaded()`, `OnUnloaded()`\n5. **NuGet cache corruption** - delete `%USERPROFILE%\\.nuget\\packages\\uno.ui` if debugging fails\n6. **Long paths on Windows** - enable via registry if needed\n\n---\n\n## Commit Guidelines\n\n**MANDATORY**: All commits MUST follow [Conventional Commits](https://www.conventionalcommits.org/).\n\n### Format\n```\n<type>[optional scope]: <description>\n```\n\n### Common Types\n\n| Type | Purpose | Version Impact |\n|------|---------|----------------|\n| `fix` | Bug fixes | PATCH |\n| `feat` | New features | MINOR |\n| `docs` | Documentation | - |\n| `test` | Tests | - |\n| `chore` | Maintenance | - |\n| `feat!` | Breaking change | MAJOR |\n\n### Examples\n```bash\ngit commit -m \"chore: Initial work\"\ngit commit -m \"fix: Resolve null reference in TextBox\"\ngit commit -m \"feat(ios): Implement native picker control\"\ngit commit -m \"feat!: Remove deprecated API methods\"\n```\n\nGuidelines:\n- Keep description under 50 characters\n- Use imperative mood (\"Add\" not \"Added\")\n- Reference issues: `fix: Resolve layout issue (fixes #12345)`\n- **Commit cadence**: when the user asks, or when working autonomously on a larger feature, commit in **logical groups** — one focused, Conventional-Commit-formatted commit per coherent chunk that builds clean, rather than one batch at the end. On complex work, these incremental commits also let reviewers follow the progression of the change rather than facing one giant diff. For small one-off edits in an interactive session, leave changes uncommitted unless asked.\n\n### Pull Requests & Issues\n\nWhen asked to open a PR or file an issue, **base it on the repo's existing templates** (filled out accordingly) — don't free-form:\n- **PRs** → fill out every section of `.github/PULL_REQUEST_TEMPLATE.md` and submit it as the body (e.g. `gh pr create --body-file <filled>.md`).\n- **Issues** → pick the matching GitHub issue **form** under `.github/ISSUE_TEMPLATE/` (`bug-report`, `enhancement`, `documentation-issue`/`-request`, `samples-issue`/`-request`, `feedback`, `support-request`, `success-story`) and fill its required fields (`gh issue create --template <name>.yml`).\n- **Every PR must reference an associated issue** (unless it's a pure-documentation change). Before opening the PR, settle the issue: use the one identified in the conversation; else search for an existing match (`gh issue list --search \"<keywords>\"`); else create one from the forms above. Put its number on the template's first line — `**GitHub Issue:** closes #XYZ` — so merging the PR auto-closes the issue.\n\n---\n\n## References\n\n### Documentation\n- [Building Uno](https://platform.uno/docs/articles/uno-development/building-uno-ui.html)\n- [Contributing Guide](https://platform.uno/docs/articles/uno-development/contributing-intro.html)\n- [Creating Tests](https://platform.uno/docs/articles/contributing/guidelines/creating-tests.html)\n\n### In-Repo Docs\n- Build guide: `doc/articles/uno-development/building-uno-ui.md`\n- Samples guide: `doc/articles/uno-development/working-with-the-samples-apps.md`\n\n### Subsystem deep dives\n- `/winui-port` skill - WinUI C++ → C# porting\n- `/devserver` skill - DevServer CLI/Host maintenance\n- `/runtime-tests` skill + `.claude/rules/runtime-tests.md` - runtime test execution & authoring\n- `.claude/rules/dependency-properties.md` - DependencyProperty patterns\n- `.claude/rules/source-generators.md` - XAML/DependencyObject generators\n\n### Community\n- [Discord](https://platform.uno/discord)\n- [Samples App](https://aka.platform.uno/wasm-samples-app)\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nFollow instructions in @AGENTS.md\n\n<!-- SPECKIT START -->\nFor additional context about technologies to be used, project structure,\nshell commands, and other important information, read the current plan:\n`specs/003-wasm-a11y-remediation/plan.md`\n<!-- SPECKIT END -->\n","category":"root","tokens":70},{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nThis file provides guidance to AI Agents when working with code in this repository.\n\n## Project Overview\n\nUno Platform is an open-source .NET UI cross-platform framework for building .NET applications from a single codebase using the WinUI 3 API. It targets Web (WebAssembly), Desktop (Windows, macOS, Linux via Skia), and Mobile (iOS, tvOS, Android).\n\n**Reference these instructions first**, then lean on skills (workflows) and the path-scoped rules below.\n\n#### Claude Code Skills (invoke via `/skill-name`)\n\n| Skill | Command | Use For |\n|-------|---------|---------|\n| Add Sample | `/add-sample` | Creating SamplesApp sample pages with correct registration |\n| Runtime Tests | `/runtime-tests` | Building and running Uno runtime tests (Skia Desktop/WASM) |\n| WinUI Runtime Tests | `/winui-runtime-tests` | Running runtime tests against native WinUI on Windows |\n| WinUI Porting | `/winui-port` | Porting WinUI C++ code to Uno Platform C# (full deep reference) |\n| DevServer | `/devserver` | DevServer CLI/Host build, test, MCP proxy, add-in discovery |\n| Docs Build | `/docs-build` | Building, previewing & validating the docs website (DocFX), incl. external-doc commit bumps in `import_external_docs.ps1` |\n\n#### Pre-commit review (invoke via `/review-panel`)\n\n`/review-panel [scope]` runs an eight-lens reviewer panel (architect, contract, skeptic, performance, operability, quality, security, jerome) in parallel and synthesizes one report with a `ship` / `fix-first` / `block-merge` verdict. Run it before you commit or open a PR — pass a scope (`master..HEAD`, a `#PR`, `HEAD~1`) or omit it to auto-detect uncommitted changes / branch-vs-`master`. The panel learns from corrections recorded in `specs/lessons.md`. Lenses, scopes, and loop recipes: `.claude/review-panel-cheatsheet.md`.\n\n#### Path-scoped rules (`.claude/rules/`)\n\nThese load **automatically** when you touch matching files — you don't invoke them. They hold the non-obvious, subsystem-specific conventions so this always-loaded file stays lean:\n\n| Rule | Applies to | Covers |\n|------|-----------|--------|\n| `code-style.md` | `src/**/*.cs` | nullable, file headers (MUX/MIT), logging, `[Uno.NotImplemented]` |\n| `platform-targeting.md` | `src/**/*.cs` | file-suffix vs `#if` vs `OperatingSystem.IsX()` vs `ApiExtensibility` |\n| `debugging-discipline.md` | `src/**/*.cs` | full root-cause/validation/diagnosis-bias protocols |\n| `dependency-properties.md` | `src/Uno.UI/**` | `[GeneratedDependencyProperty]`, metadata, callbacks |\n| `runtime-tests.md` | `src/Uno.UI.RuntimeTests/**` | `[RunsOnUIThread]`, `[PlatformCondition]`, `UITestHelper` |\n| `unit-tests.md` | `src/Uno.UI.UnitTests/**` | MSTest, no-visual-tree logic tests |\n| `source-generators.md` | `src/SourceGenerators/**` | incremental gens, LOH/perf, cancellation |\n| `samples.md` | `src/SamplesApp/**` | `[Sample]`, theming, XamlStyler |\n| `build-system.md` | `src/**/*.{csproj,props,targets}` | TFMs, output paths, package versions |\n\n**Which to reach for:** the relevant `.claude/rules/*.md` is already in context (path-scoped) — use it as the checklist. Use a `/skill` for the actual build/run/scaffold/port workflow (and its deep reference).\n\n---\n\n## Quick Reference\n\n### Technology Stack\n\n| Technology | Purpose |\n|------------|---------|\n| .NET 10.0/9.0 | Multi-target framework |\n| C# & XAML | Primary languages |\n| TypeScript | WebAssembly/Web APIs only |\n| Skia | Cross-platform rendering |\n| MSBuild | Build orchestration |\n| Roslyn | Source generators |\n\n### Platform File Suffixes\n\n| Suffix | Platform |\n|--------|----------|\n| `.Android.cs` | Android |\n| `.iOS.cs` | iOS |\n| `.UIKit.cs` | iOS & tvOS |\n| `.wasm.cs` | WebAssembly |\n| `.skia.cs` | Skia |\n| `.reference.cs` | Reference implementation |\n| `.crossruntime.cs` | Skia + WebAssembly + Reference (shared) |\n\n### Key Source Directories\n\n- `src/Uno.UI/` - Core UI framework (WinUI controls, layout, XAML runtime)\n- `src/Uno.UWP/` - Non-UI WinRT APIs (platform-specific assemblies)\n- `src/Uno.Foundation/` - Foundation APIs (platform-specific assemblies)\n- `src/Uno.UI.Runtime.Skia.*/` - Skia platform runtimes\n- `src/SourceGenerators/` - XAML parser, DependencyProperty generator\n- `src/SamplesApp/` - Sample app for validation and tests\n- `src/Uno.UI.RuntimeTests/` - Platform runtime tests\n- `src/Uno.UI.DevServer.Cli/` - DevServer CLI tool\n- `src/Uno.UI.RemoteControl.Host/` - DevServer Host process\n\n### Build Setup (Required)\n\n**1. Setup cross-targeting override:**\n```bash\ncd src\ncp crosstargeting_override.props.sample crosstargeting_override.props\n```\n\n**2. Edit `crosstargeting_override.props`** (recommended fast-iteration config):\n```xml\n<Project>\n  <PropertyGroup>\n    <!-- Choose ONE target: -->\n    <UnoTargetFrameworkOverride>net10.0</UnoTargetFrameworkOverride>              <!-- WebAssembly/Skia -->\n    <!-- <UnoTargetFrameworkOverride>net10.0-android</UnoTargetFrameworkOverride>  Android -->\n    <!-- <UnoTargetFrameworkOverride>net10.0-ios</UnoTargetFrameworkOverride>      iOS -->\n    <!-- <UnoTargetFrameworkOverride>net10.0-windows10.0.19041.0</UnoTargetFrameworkOverride> Windows -->\n\n    <!-- Disables analyzers + code-style enforcement for local builds. No effect on CI. -->\n    <UnoFastDevBuild>true</UnoFastDevBuild>\n  </PropertyGroup>\n</Project>\n```\n\nOr pass the same flags per-build instead of committing them:\n\n```bash\ndotnet build … -p:UnoTargetFrameworkOverride=net10.0 -p:UnoFastDevBuild=true\n```\n\n**Why these flags:**\n- `UnoTargetFrameworkOverride` — restricts cross-targeted projects to a single TFM, skipping the redundant net9.0 outputs while you iterate on net10.0 (or vice versa).\n- `UnoFastDevBuild` — disables `RunAnalyzersDuringBuild`, `EnforceCodeStyleInBuild`, and the `Microsoft.CodeAnalysis.NetAnalyzers` package for local builds. **Guarded by `ContinuousIntegrationBuild`, so CI is never affected** — analyzer-strict checks still run on every PR. Set persistently via the `UNO_FAST_DEV_BUILD=true` environment variable if you'd rather not edit the file.\n\nCombined impact on `SamplesApp.Skia.Generic` (Windows, 32-core, warm NuGet cache): clean build ~3:23 → ~1:59, incremental rebuild after a Uno.UI edit ~2:23 → ~0:58. The `/runtime-tests` skill passes both flags by default (use `strict` to opt out for CI-equivalent coverage).\n\n**Do not commit `crosstargeting_override.props`** — it is per-developer config and is intentionally `.gitignore`d.\n\n**3. Use matching solution filter:**\n\n| Platform | Solution Filter |\n|----------|-----------------|\n| WebAssembly | `Uno.UI-Wasm-only.slnf` |\n| Skia (Desktop) | `Uno.UI-Skia-only.slnf` |\n| Mobile (Android/iOS) | `Uno.UI-netcore-mobile-only.slnf` |\n| Windows | `Uno.UI-Windows-only.slnf` |\n| Unit Tests | `Uno.UI-UnitTests-only.slnf` |\n\n**4. Build commands:**\n```bash\ncd src\ndotnet restore Uno.UI-Skia-only.slnf                    # Restore (50-60s)\ndotnet build Uno.UI-Skia-only.slnf --no-restore         # Build (3-5min)\ndotnet test Uno.UI.UnitTests/Uno.UI.UnitTests.csproj    # Unit tests (40-60s)\n```\n\n**CRITICAL**: **NEVER CANCEL** builds. Set timeouts to 15+ minutes. Favor Skia desktop for faster builds.\n\n---\n\n## Architecture Overview\n\n### Platform Abstraction\n\nSingle C#/XAML codebase → WinUI 3 API → Platform-specific runtimes (Skia, WebAssembly, Native)\n\n### Rendering Engines\n\n- **Skia**: Cross-platform (Desktop Win32, macOS, Linux, Skia Android/iOS)\n- **Native**: Platform controls (UIKit, Android Views, DOM elements)\n\n### Development scope: Skia-first (IMPORTANT)\n\n**Unless a task explicitly states otherwise, new features and enhancements target the Skia targets only** (Desktop Win32/macOS/Linux and Skia-on-Android/iOS/WASM). The **native targets** — native Android Views, native iOS/UIKit, WASM DOM — are **maintenance-only**: don't build new features for them, but **don't break them either** (keep them compiling and behaving as-is).\n\nThis applies to the **UI rendering layer** (`Uno.UI` native views), *not* to platform APIs. **Platform-specific non-UI WinRT APIs (in `Uno.UWP`/`Uno.Foundation`) are still actively enhanced**, because the Skia targets compile and consume those same per-platform implementations (e.g. Skia-on-Android uses the Android implementation of a file picker, sensor, contacts, etc.).\n\n### Platform Base Classes\n\n| Platform | Inheritance |\n|----------|-------------|\n| Android native | `ViewGroup` → `UnoViewGroup` (Java) → `BindableView` → `UIElement` |\n| iOS native | `UIView` → `BindableUIView` → `UIElement` |\n| WebAssembly native | UIElements map to DOM elements (default: \"div\") |\n| Skia | `IRenderer` interface for rendering pipeline |\n\n### XAML Compilation\n\nXAML files are parsed to C# via source generators (`XamlFileGenerator` in `Uno.UI.SourceGenerators`), not .xbf like WinUI. Generates `InitializeComponent()`, named fields, and x:Bind expressions.\n\n### DependencyObject on Mobile\n\nOn Android/iOS, `DependencyObject` is an **interface** (not base class) since `UIElement` must inherit from native view classes. Source generators provide the implementation via `DependencyObjectGenerator`.\n\n### Project Organization\n\nMost libraries have 5 variants: Reference, Skia, WebAssembly, NetCoreMobile, Tests.\n\n### Runtime Target Selection\n\nFor Skia, `RuntimeAssetsSelectorTask` ensures `Uno.UI` uses `netX` (generic) target for all Skia platforms. `Uno.UWP` and `Uno.Foundation` use platform-specific assemblies. Use runtime checks like `OperatingSystem.IsAndroid()` for platform-specific behavior on Skia for libraries above and including `Uno.UI`, or use `ApiExtensibility` with platform-specific implementations in `Runtime.Skia` projects.\n\n### NotImplemented Stubs\n\nAuto-generated stubs marked with `[Uno.NotImplemented]` allow compilation but warn if used. Located in `Generated` folders - never edit these files.\n\n---\n\n## Development Workflow\n\n### Public Documentation and Spec References (MANDATORY)\n\nWhen editing specifications, documentation, or other repo-tracked design artifacts intended to be shareable:\n\n1. **Do not reference private artifacts** from the document.\n   - Do not link to private issues, private pull requests, private boards, private docs, or private repositories.\n   - If related work is tracked privately, mention it only in generic terms.\n\n2. **Public specs are source-of-truth documents**.\n   - Public or repo-local specs may be referenced by private trackers.\n   - Private trackers must not be required to understand the public spec.\n\n3. **Keep the dependency direction one-way**.\n   - Allowed: private issues/PRs referencing a public spec in this repo.\n   - Not allowed: a public spec in this repo referencing a private issue/PR/doc as normative context.\n\n4. **If implementation follow-up exists in private repos**, describe it as alignment or downstream tracking work without identifiers or URLs.\n\n### Debugging & Validation (MANDATORY — summary)\n\nWhen fixing crashes, rendering, or selection/indexing bugs: **reproduce first → name the broken invariant → fix the root cause (and the mutation point) before adding guards → prove it with a test that fails-before/passes-after → validate at runtime, not compile-only.** Label every proposed change `root-cause fix` or `defensive hardening`; a guard-only change is never a complete resolution. Report validation evidence with explicit labels — **Code review** (by inspection) vs **Compile** (which project built) vs **Runtime** (which test/app ran) — and never present compile-only as runtime validation.\n\nThe full protocol (root-cause steps, diagnosis-bias checks, evidence rules) auto-loads from `.claude/rules/debugging-discipline.md` when editing `src/**/*.cs`.\n\n### Validation Checklist\n\nRun these after making changes:\n\n1. **Build**: `dotnet build Uno.UI-UnitTests-only.slnf --no-restore`\n2. **Unit tests**: `dotnet test Uno.UI.UnitTests/Uno.UI.UnitTests.csproj --no-build`\n3. **Runtime tests** (UI changes): Use `/runtime-tests` skill (Skia Desktop default, pass test class/method name as argument)\n4. **WinUI parity** (validate against native WinUI): Use `/winui-runtime-tests` skill\n5. **Sample app** (visual changes): `cd src/SamplesApp/SamplesApp.Wasm && dotnet run`\n6. **XAML formatting** (SamplesApp changes): `dotnet xstyler -d src/SamplesApp -r`\n\n### SamplesApp: Add XAML files\n\nWhen adding XAML samples to the `SamplesApp`, drop the files anywhere under `src/SamplesApp/SamplesApp.Samples/` — they are auto-discovered by glob (no manual registration required).\n\nSample creation checklist:\n1. Create your sample XAML and code-behind under an appropriate folder in `src/SamplesApp/SamplesApp.Samples/`.\n2. Add the `[Uno.UI.Samples.Controls.Sample]` attribute to the code-behind class.\n3. Format XAML: `dotnet xstyler -f src/SamplesApp/SamplesApp.Samples/YourFolder/YourSample.xaml`\n4. Build and run `SamplesApp` to verify the sample appears.\n\nTheming guideline (brief): prefer `{ThemeResource}` for backgrounds/foregrounds so samples work in light and dark themes.\n\n### Runtime Tests (Preferred for UI)\n\nAdd tests to `Uno.UI.RuntimeTests`. Key helpers:\n- `WindowHelper.WindowContent` - Add elements to visual tree\n- `await WindowHelper.WaitForLoaded(element)` - Wait for load\n- `await WindowHelper.WaitForIdle()` - Wait for UI to settle\n\n**To build and run tests, use the `/runtime-tests` skill.** It handles build, filter encoding, execution, and result parsing for both Skia Desktop and WASM. Test-authoring conventions auto-load from `.claude/rules/runtime-tests.md`.\n\n### Common Build Issues\n\n| Issue | Solution |\n|-------|----------|\n| \"Assets file doesn't have a target\" | Delete `obj/`, `bin/`, restore |\n| \"Windows XAML targets not found\" | Use Skia/Wasm on Linux/macOS |\n| Solution filter fails | Ensure `crosstargeting_override.props` matches filter |\n| Persistent issues | Close VS, delete `src/.vs`, rebuild |\n| Last resort | `git clean -fdx` (close VS first) |\n\n### Key Build Properties\n\n| Property | Purpose |\n|----------|---------|\n| `UnoTargetFrameworkOverride` | Single platform target |\n| `UnoNugetOverrideVersion` | Debug with NuGet override |\n| `UnoUISourceGeneratorDebuggerBreak` | Attach debugger to generators |\n| `XamlSourceGeneratorTracingFolder` | Dump generator diagnostics |\n\n---\n\n## Code Conventions\n\n### Partial Classes\n\nExtensive use for:\n- Platform-specific code: `MyControl.Android.cs`, `MyControl.iOS.cs`\n- Generated code: `MyPage.xaml.g.cs`\n- Logical separation: `MyControl.Properties.cs` for DependencyProperties\n\n### DependencyProperty Pattern\n\nPrefer `[GeneratedDependencyProperty]` for new properties. Conventions auto-load from `.claude/rules/dependency-properties.md`; for full templates copy from existing controls (`Canvas`, `RangeBase`, `Button`).\n\n### Code Style\n\nTabs, Allman braces (always), expression-bodied members for one-liners, `internal` extension methods in `[Type]Extensions.cs`, `#nullable enable` per-file, MUX/MIT headers on ported code. Comments only when they add value — short (a line or two, never a wall of text), explaining the non-obvious *why*, never narrating code removal/history; longer is OK only when explicitly requested, actually needed for code understanding, or carried verbatim from a WinUI port. Details auto-load from `.claude/rules/code-style.md`. Style is analyzer-enforced on CI even when `UnoFastDevBuild=true` skips it locally.\n\n### Events\n\n🚫 **NEVER declare `event Action` or `event Action<T>`**. Always use `EventHandler` or\n`EventHandler<TEventArgs>`. Raw `Action`/`Func` delegates as event fields bypass the\nstandard `add`/`remove` contract and cannot be reliably subscribed across assembly\nboundaries.\n\n✅ Correct:\n```csharp\npublic event EventHandler<MyEventArgs>? SomethingHappened;\n```\n\n🚫 Wrong — every agent must reject this:\n```csharp\npublic event Action<MyData>? SomethingHappened; // NEVER\n```\n\n### XAML Formatting (SamplesApp)\n\nXAML files under `src/SamplesApp/` are formatted using [XamlStyler](https://github.com/Xavalon/XamlStyler).\nConfiguration is in `src/SamplesApp/Settings.XamlStyler`.\n\n```bash\n# One-time setup (restore tools after cloning)\ndotnet tool restore\n\n# Format all SamplesApp XAML files\ndotnet xstyler -d src/SamplesApp -r\n\n# Format a single file\ndotnet xstyler -f src/SamplesApp/SamplesApp.Samples/MyFile.xaml\n\n# Check without modifying (CI mode)\ndotnet xstyler -d src/SamplesApp -r -p\n```\n\nA GitHub Actions workflow enforces formatting on PRs that touch SamplesApp XAML files.\n\n### Implementing New WinUI Features\n\n1. Find generated stub: `src/Uno.UWP/Generated/3.0.0.0/Windows.*/ClassName.cs`\n2. Copy to non-generated location\n3. Remove implemented platforms from `[NotImplemented]` attribute\n4. Use platform suffix for platform-specific files\n\n---\n\n## Common Pitfalls\n\n1. **DependencyObject is an interface** on Android/iOS - don't inherit, implement\n2. **Generated files are regenerated** - never edit `Generated/` folders\n3. **Visual tree differs by platform** - Android/iOS use native hierarchy; WebAssembly uses DOM; Skia uses rendering tree\n4. **Partial methods** used for extensibility: `OnLoaded()`, `OnUnloaded()`\n5. **NuGet cache corruption** - delete `%USERPROFILE%\\.nuget\\packages\\uno.ui` if debugging fails\n6. **Long paths on Windows** - enable via registry if needed\n\n---\n\n## Commit Guidelines\n\n**MANDATORY**: All commits MUST follow [Conventional Commits](https://www.conventionalcommits.org/).\n\n### Format\n```\n<type>[optional scope]: <description>\n```\n\n### Common Types\n\n| Type | Purpose | Version Impact |\n|------|---------|----------------|\n| `fix` | Bug fixes | PATCH |\n| `feat` | New features | MINOR |\n| `docs` | Documentation | - |\n| `test` | Tests | - |\n| `chore` | Maintenance | - |\n| `feat!` | Breaking change | MAJOR |\n\n### Examples\n```bash\ngit commit -m \"chore: Initial work\"\ngit commit -m \"fix: Resolve null reference in TextBox\"\ngit commit -m \"feat(ios): Implement native picker control\"\ngit commit -m \"feat!: Remove deprecated API methods\"\n```\n\nGuidelines:\n- Keep description under 50 characters\n- Use imperative mood (\"Add\" not \"Added\")\n- Reference issues: `fix: Resolve layout issue (fixes #12345)`\n- **Commit cadence**: when the user asks, or when working autonomously on a larger feature, commit in **logical groups** — one focused, Conventional-Commit-formatted commit per coherent chunk that builds clean, rather than one batch at the end. On complex work, these incremental commits also let reviewers follow the progression of the change rather than facing one giant diff. For small one-off edits in an interactive session, leave changes uncommitted unless asked.\n\n### Pull Requests & Issues\n\nWhen asked to open a PR or file an issue, **base it on the repo's existing templates** (filled out accordingly) — don't free-form:\n- **PRs** → fill out every section of `.github/PULL_REQUEST_TEMPLATE.md` and submit it as the body (e.g. `gh pr create --body-file <filled>.md`).\n- **Issues** → pick the matching GitHub issue **form** under `.github/ISSUE_TEMPLATE/` (`bug-report`, `enhancement`, `documentation-issue`/`-request`, `samples-issue`/`-request`, `feedback`, `support-request`, `success-story`) and fill its required fields (`gh issue create --template <name>.yml`).\n- **Every PR must reference an associated issue** (unless it's a pure-documentation change). Before opening the PR, settle the issue: use the one identified in the conversation; else search for an existing match (`gh issue list --search \"<keywords>\"`); else create one from the forms above. Put its number on the template's first line — `**GitHub Issue:** closes #XYZ` — so merging the PR auto-closes the issue.\n\n---\n\n## References\n\n### Documentation\n- [Building Uno](https://platform.uno/docs/articles/uno-development/building-uno-ui.html)\n- [Contributing Guide](https://platform.uno/docs/articles/uno-development/contributing-intro.html)\n- [Creating Tests](https://platform.uno/docs/articles/contributing/guidelines/creating-tests.html)\n\n### In-Repo Docs\n- Build guide: `doc/articles/uno-development/building-uno-ui.md`\n- Samples guide: `doc/articles/uno-development/working-with-the-samples-apps.md`\n\n### Subsystem deep dives\n- `/winui-port` skill - WinUI C++ → C# porting\n- `/devserver` skill - DevServer CLI/Host maintenance\n- `/runtime-tests` skill + `.claude/rules/runtime-tests.md` - runtime test execution & authoring\n- `.claude/rules/dependency-properties.md` - DependencyProperty patterns\n- `.claude/rules/source-generators.md` - XAML/DependencyObject generators\n\n### Community\n- [Discord](https://platform.uno/discord)\n- [Samples App](https://aka.platform.uno/wasm-samples-app)\n","category":"root","tokens":5120}]}