chore: Skia Wasm initial a11y support

.github/agents/devserver-agent.md

@@ -0,0 +1,258 @@
+---
+name: DevServer Agent
+description: Helps with DevServer CLI/Host build, test, MCP proxy, and add-in discovery
+---
+
+# DevServer Agent
+
+You are an assistant that helps maintain and extend the Uno DevServer infrastructure. This covers the CLI tool, the Host process, MCP proxy integration, and add-in discovery.
+
+---
+
+## 1. Architecture Overview
+
+The DevServer uses a **3-process chain**:
+
+1. **CLI** (`Uno.UI.DevServer.Cli`) – Entry point, user-facing commands, MCP STDIO proxy
+2. **Controller** (optional, launched by CLI `start` command) – Manages the Host lifecycle
+3. **Host** (`Uno.UI.RemoteControl.Host`) – ASP.NET Core server for Hot Reload, IDE channel, processors
+
+The CLI can also run in **MCP mode** (`--mcp-app`), acting as a Model Context Protocol proxy between AI agents and the running DevServer Host.
+
+### Key Packages
+
+| NuGet Package | Contents |
+|---------------|----------|
+| `Uno.DevServer` | CLI tool (installed via `dotnet tool`) |
+| `Uno.WinUI.DevServer` | Host binaries, processors, BuildTransitive targets |
+
+---
+
+## 2. Key Source Directories
+
+| Directory | Purpose |
+|-----------|---------|
+| `src/Uno.UI.DevServer.Cli/` | CLI tool: commands, helpers, MCP proxy |
+| `src/Uno.UI.DevServer.Cli/Helpers/` | Discovery, caching, process helpers |
+| `src/Uno.UI.DevServer.Cli/Mcp/` | MCP server, client proxy, tool caching |
+| `src/Uno.UI.RemoteControl.Host/` | Host process: server, extensibility, IDE channel |
+| `src/Uno.UI.RemoteControl.Host/Extensibility/` | Add-in loading and discovery |
+| `src/Uno.UI.RemoteControl.DevServer.Tests/` | Unit and integration tests |
+| `build/test-scripts/` | PowerShell integration test harness |
+| `build/nuget/Uno.WinUI.DevServer.nuspec` | NuGet package definition |
+
+### Key Files
+
+| File | Role |
+|------|------|
+| `CliManager.cs` | CLI command router (start, stop, list, disco, login, MCP) |
+| `UnoToolsLocator.cs` | SDK and package discovery from global.json, NuGet cache, and AmbientRegistry |
+| `TargetsAddInResolver.cs` | Fast add-in discovery by parsing `.targets` XML files |
+| `ManifestAddInResolver.cs` | Manifest-first add-in discovery from `devserver-addin.json` |
+| `DotNetVersionCache.cs` | Caches `dotnet --version` result on disk |
+| `McpStdioServer.cs` | MCP STDIO server entry point |
+| `ProxyLifecycleManager.cs` | MCP proxy lifecycle orchestration |
+| `McpUpstreamClient.cs` | HTTP client to upstream DevServer MCP endpoint |
+| `ToolListManager.cs` | Tool list management and caching |
+| `DevServerMonitor.cs` | DevServer process health monitoring and crash recovery |
+| `MonitorDecisions.cs` | Pure decision logic extracted from DevServerMonitor for testability |
+| `RemoteControlServer.cs` | Host: WebSocket server, processor management |
+| `AddIns.cs` | Host: add-in discovery and assembly loading |
+
+---
+
+## 3. Build
+
+The DevServer projects are **independent of the UI framework** and do not require `crosstargeting_override.props`.
+
+```bash
+# CLI
+dotnet build src/Uno.UI.DevServer.Cli/Uno.UI.DevServer.Cli.csproj
+
+# Host
+dotnet build src/Uno.UI.RemoteControl.Host/Uno.UI.RemoteControl.Host.csproj
+
+# Unit tests
+dotnet build src/Uno.UI.RemoteControl.DevServer.Tests/Uno.UI.RemoteControl.DevServer.Tests.csproj
+```
+
+---
+
+## 4. Testing
+
+### Unit Tests
+
+```bash
+dotnet test src/Uno.UI.RemoteControl.DevServer.Tests/Uno.UI.RemoteControl.DevServer.Tests.csproj
+```
+
+The test project **links source files** from CLI/Host projects (rather than referencing project outputs) to avoid circular dependencies. When adding new source files for testing, add a `<Compile Include>` link in the `.csproj`.
+
+### Integration Tests
+
+The PowerShell script `build/test-scripts/run-devserver-cli-tests.ps1` provides integration testing with `-DevServerCliDllPath` to point to a local build.
+
+### Test Patterns
+
+- **Framework**: MSTest with AwesomeAssertions
+- **Naming**: `Test_WhenCondition_ShouldExpectation`
+- **Execution**: Sequential (`[assembly: Parallelize(Workers = 1)]`)
+- **Isolation**: Tests use temp directories for file I/O, injectable delegates for subprocess mocking
+
+---
+
+## 5. CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `start` | Start the DevServer for the current folder |
+| `stop` | Stop the DevServer for the current folder |
+| `list` | List active DevServer instances |
+| `disco` | Discover environment, SDK details, and active server instance |
+| `login` | Open the Uno Platform settings application |
+| `--mcp-app` | Start in MCP STDIO proxy mode |
+
+### Key Flags
+
+| Flag | Description |
+|------|-------------|
+| `-l trace` | Enable trace-level logging (useful for debugging) |
+| `-fl <path>` | File logging with `{Date}` token support |
+| `--json` | JSON output for disco command |
+| `--addins-only` | Output only resolved add-in paths |
+| `--mcp-wait-tools-list` | Wait for upstream tools before responding to `list_tools` |
+| `--force-roots-fallback` | Expose `uno_app_set_roots` for clients without roots support |
+| `--force-generate-tool-cache` | Force tool cache generation on startup |
+| `--solution-dir <path>` | Explicit solution root |
+
+---
+
+## 6. Add-in Discovery
+
+### Manifest-First Path (`devserver-addin.json`)
+
+`ManifestAddInResolver` looks for a `devserver-addin.json` manifest in each NuGet package root. When present, it resolves add-in entry points directly from the manifest, supporting `minHostVersion` gating to filter incompatible add-ins.
+
+### Fast Path (`.targets` parsing, ~200ms)
+
+`TargetsAddInResolver` parses `packages.json` from the Uno SDK and `buildTransitive/*.targets` files from NuGet packages to extract `<UnoRemoteControlAddIns>` items without invoking MSBuild. Used as fallback when no manifest is found.
+
+### MSBuild Fallback (10-30s)
+
+When both fast paths fail, the Host falls back to `dotnet build` evaluation. The `--addins` flag on the Host bypasses this when paths are pre-resolved by the CLI.
+
+### Key Files
+
+- `ManifestAddInResolver.cs` – Manifest-first discovery
+- `TargetsAddInResolver.cs` – `.targets` parsing fallback
+- `AddIns.cs` (Host) – Assembly loading and MSBuild fallback
+
+---
+
+## 7. NuGet Packaging
+
+The `Uno.WinUI.DevServer` package (`build/nuget/Uno.WinUI.DevServer.nuspec`) ships:
+
+- Host binaries for `net9.0` and `net10.0`
+- Processor DLLs
+- BuildTransitive targets for MCP and Settings add-ins
+
+To test with a local build, use `UnoNugetOverrideVersion` or set `-DevServerCliDllPath` in integration tests.
+
+---
+
+## 8. MCP Proxy
+
+The MCP proxy (`McpStdioServer.cs` / `ProxyLifecycleManager.cs`) runs in STDIO mode and bridges AI agents to the DevServer Host.
+
+### Key Behavior
+
+- Returns cached tool definitions instantly while Host launches in background
+- Tool cache persisted to `%LOCALAPPDATA%/Uno Platform/uno.devserver/tools-cache.json`
+- Sends `tools/list_changed` notification when tools become available
+- Detects client capabilities (roots support) via `ClientCapabilities.Roots` to adapt behavior
+
+### Key Files
+
+| File | Role |
+|------|------|
+| `McpStdioServer.cs` | MCP STDIO server entry point |
+| `ProxyLifecycleManager.cs` | MCP proxy lifecycle orchestration |
+| `McpUpstreamClient.cs` | HTTP proxy to Host MCP endpoint |
+| `ToolListManager.cs` | Tool list management and caching |
+| `DevServerMonitor.cs` | Process health monitoring and crash recovery |
+| `MonitorDecisions.cs` | Pure decision logic (post-startup action, roots detection, start guard) |
+| `ToolCacheFile.cs` | Persistent tool cache serialization |
+
+---
+
+## 9. Common Maintenance Tasks
+
+### Adding a CLI Command
+
+1. Add command handling in `CliManager.cs` (follow existing `start`/`stop`/`disco` pattern)
+2. Add help text in `Program.cs`
+3. Add integration test in `build/test-scripts/run-devserver-cli-tests.ps1`
+
+### Modifying Host Startup
+
+1. Edit `src/Uno.UI.RemoteControl.Host/Program.cs` for command routing
+2. Edit `Startup.cs` for ASP.NET Core configuration
+3. Test with `dotnet run` from the Host project directory
+
+### Modifying Add-in Discovery
+
+1. Edit `TargetsAddInResolver.cs` for fast path changes
+2. Add unit tests in `TargetsAddInResolverTests.cs`
+3. Verify with `uno-devserver disco --json` in a real project
+
+### Modifying MCP Proxy
+
+1. Edit `McpStdioServer.cs` / `ProxyLifecycleManager.cs` / `ToolListManager.cs` for tool list or protocol changes
+2. Test with `--mcp-app` flag and an MCP client (Claude Code, etc.)
+3. Check `--mcp-wait-tools-list` behavior for clients without `tools/list_changed`
+
+---
+
+## 10. IDE Compatibility Constraints
+
+**All three IDE extensions launch the Host directly** — none use `--command start` (the controller path). The controller is only used by CLI `start`. This means:
+- AmbientRegistry duplicate protection **does not exist** for IDE-launched instances
+- Each IDE manages its own DevServer lifecycle independently
+- **Multiple instances for the same solution** are possible today (IDE + CLI, or IDE + MCP)
+- The `--addins` flag MUST be opt-in: absence = MSBuild discovery unchanged
+
+### Active Server Discovery
+
+`disco --json` returns an `activeServer` field (null or object with `processId`, `port`, `mcpEndpoint`, `parentProcessId`, `startTime`) by querying the AmbientRegistry. This is the recommended way for extensions to detect a running DevServer without reading registry files directly.
+
+### Visual Studio (`uno.studio`)
+
+The VS extension (`DevServerLauncher.cs`, `EntryPoint.cs`) uses **reflection** to probe:
+- `Uno.UI.RemoteControl.VS.EntryPoint` (namespace + class name)
+- Constructor signatures v2 and v3
+
+**Never rename or change constructor signatures** without coordinating with the VS extension team. Regression tests in `EntryPointRegressionTests.cs` verify these contracts.
+
+Launch flow: finds `uno.winui.devserver` package in project references → resolves `tools/rc/host/net{major}.0/Uno.UI.RemoteControl.Host.dll` → launches Host directly with `--httpPort {port} --ppid {pid} --solution {sln}`.
+
+### Rider (`uno.rider`)
+
+Fast path: inspect project references, find `uno.winui.devserver` NuGet package, derive host path from `dotnet --version`. Fallback: `dotnet build /t:GetRemoteControlHostPath`. Launches Host directly (no `--command start`). Port managed via `CsprojUserGenerator`.
+
+### VS Code (`uno.vscode`)
+
+Always uses MSBuild: `dotnet build /t:GetRemoteControlHostPath`. Launches Host directly with `--httpPort {port}`. Supports external-host debug mode via `.uno.vscode.remote-control` marker file.
+
+### Host Command-Line Contract
+
+The Host accepts arguments via `ConfigurationBuilder.AddCommandLine()`. The `--addins` flag is opt-in to maintain backward compatibility with older CLI versions.
+
+---
+
+## 11. References
+
+- [Dev Server documentation](../../doc/articles/dev-server.md)
+- [Specs](../../specs/001-fast-devserver-startup/)
+- [Integration test script](../../build/test-scripts/run-devserver-cli-tests.ps1)
+- [NuGet spec](../../build/nuget/Uno.WinUI.DevServer.nuspec)

AGENTS.md

@@ -14,6 +14,7 @@ Uno Platform is an open-source .NET UI cross-platform framework for building .NE
 | Source Generators | `.github/agents/source-generators-agent.md` | XAML/DependencyObject generator work |
 | Runtime Tests | `.github/agents/runtime-tests-agent.md` | Creating and running runtime tests |
 | WinUI Porting | `.github/agents/winui-porting-agent.md` | Porting WinUI C++ code to C# |
+| DevServer CLI | `.github/agents/devserver-agent.md` | DevServer CLI/Host build, test, MCP proxy |
 
 ---
 
@@ -50,6 +51,8 @@ Uno Platform is an open-source .NET UI cross-platform framework for building .NE
 - `src/SourceGenerators/` - XAML parser, DependencyProperty generator
 - `src/SamplesApp/` - Sample app for validation and tests
 - `src/Uno.UI.RuntimeTests/` - Platform runtime tests
+- `src/Uno.UI.DevServer.Cli/` - DevServer CLI tool
+- `src/Uno.UI.RemoteControl.Host/` - DevServer Host process
 
 ### Build Setup (Required)
 
@@ -138,6 +141,85 @@ Auto-generated stubs marked with `[Uno.NotImplemented]` allow compilation but wa
 
 ## Development Workflow
 
+### Root-Cause First Debugging Protocol (MANDATORY)
+
+When fixing crashes, rendering issues, or selection/indexing bugs,
+agents must follow this order:
+
+1. **Reproduce first**
+   - Capture exact repro steps and expected vs actual behavior.
+   - Keep one known-good repro path and rerun it after each meaningful change.
+
+2. **Identify the broken invariant**
+   - Prefer state/lifecycle invariants over symptom-level checks.
+   - For pipelines that derive secondary state, verify those derived
+      structures (for example: maps, indices, caches, or metadata)
+      are rebuilt from final post-mutation state.
+
+3. **Fix root cause before adding guards**
+    - Do not lead with null/index guards as the primary fix if
+       ownership/lifecycle is incorrect.
+    - Defensive guards are allowed only after root-cause correction,
+       and only as secondary hardening.
+
+4. **Prove correctness with targeted tests**
+   - Add/extend tests that fail before and pass after the root fix.
+   - Cover both the triggering scenario and one adjacent regression scenario.
+
+5. **Validate with runtime behavior, not compile only**
+   - Run the closest runtime or integration path available for the changed area.
+   - If full runtime execution is not possible in the environment,
+       state that explicitly and provide the exact command(s) for
+       maintainers to run.
+
+6. **Communicate confidence accurately**
+   - Separate: (a) code review assessment,
+       (b) compile validation, (c) runtime validation.
+   - Never present guard-only mitigation as a complete root-cause fix.
+
+**Anti-pattern to avoid:**
+
+- Symptom-driven patching that accumulates bounds checks while
+   stale or invalid intermediate state remains possible.
+
+### Validation Evidence Protocol (MANDATORY)
+
+For bug fixes and PR reviews, agents must report validation evidence
+with explicit labels:
+
+- **Code review assessment**: What logic appears correct by inspection.
+- **Compile validation**: Which project/solution was built, and result.
+- **Runtime validation**: Which app/test path was executed, and result.
+
+Rules:
+
+1. Do not present compile-only checks as runtime validation.
+2. If runtime execution is skipped or blocked, state that explicitly
+   and provide exact commands to run.
+3. When reviewing another PR, distinguish between confidence from
+   diff inspection vs. confidence from local execution.
+
+### Diagnosis Bias Checks (MANDATORY)
+
+Before proposing a crash fix, agents must run these checks to avoid
+choosing symptom-level guards over the real fix:
+
+1. **Invariant checkpoint before patching**
+    - Name the invariant likely broken (ownership, lifecycle,
+       index/map coherence, post-mutation consistency).
+   - If no invariant is identified, do not claim a root-cause fix.
+
+2. **Mutation-point review**
+    - Inspect where state is created/trimmed/reordered and verify all
+       dependent structures are refreshed there.
+    - Prefer correcting the mutation point over adding protections in
+       downstream consumers.
+
+3. **Guard classification**
+    - Explicitly label each proposed change as either
+       `root-cause fix` or `defensive hardening`.
+   - Guard-only changes must not be presented as complete resolution.
+
 ### Validation Checklist
 
 Run these after making changes:
@@ -312,6 +394,7 @@ Guidelines:
 - `.github/agents/source-generators-agent.md` - XAML/DependencyObject generators
 - `.github/agents/runtime-tests-agent.md` - Runtime test execution
 - `.github/agents/winui-porting-agent.md` - WinUI C++ to C# porting
+- `.github/agents/devserver-agent.md` - DevServer CLI/Host maintenance
 
 ### Community
 - [Discord](https://platform.uno/discord)

build/Uno.UI.Build.csproj

@@ -132,6 +132,17 @@
 			BuildInParallel="true" />
 
 		<Exec Command="..\src\Uno.UWPSyncGenerator\Bin\Release\Uno.UWPSyncGenerator.exe &quot;doc&quot;" />
+
+		<!-- Ensure implemented/toc.yml is valid for DocFX (DocGenerator may produce an empty file when no views are analyzed) -->
+		<PropertyGroup Condition="Exists('..\doc\articles\implemented\toc.yml')">
+			<_TocLength>$([System.IO.File]::ReadAllText('..\doc\articles\implemented\toc.yml').Trim().Length)</_TocLength>
+		</PropertyGroup>
+		<WriteLinesToFile
+			File="..\doc\articles\implemented\toc.yml"
+			Lines="# Generated by Uno.UWPSyncGenerator (DocGenerator.cs);- name: Placeholder"
+			Condition="!Exists('..\doc\articles\implemented\toc.yml') Or '$(_TocLength)' == '' Or '$(_TocLength)' == '0'"
+			Overwrite="true" />
+
 		<Exec Command="powershell .\import_external_docs.ps1" WorkingDirectory="..\doc" />
 		<Exec Command="powershell .\generate-llms-full.ps1 -InputFolder &quot;articles&quot; -LlmsTxtOutput &quot;articles/llms/llms.txt&quot; -LlmsFullTxtOutput &quot;articles/llms/llms-full.txt&quot; -BaseContentFile &quot;articles/llms/llms.txt&quot; -TocYmlPath &quot;articles/toc.yml&quot;" WorkingDirectory="..\doc" />
 		<Exec Command="dotnet tool install --tool-path $(MSBuildThisFileDirectory)\tools docfx --version $(DocfxVersion)" Condition="!exists('$(MSBuildThisFileDirectory)\tools\docfx.exe')" />

build/cSpell.json

@@ -27,6 +27,7 @@
 	"datagrid",
 	"decompile",
 	"devs",
+	"devserver",
 	"dbus",
 	"Dismissable",
 	"dmgbuild",