maui-labs copilot-instructions.md

Copilot Instructions for maui-labs

These instructions guide GitHub Copilot and other AI code generation tools when working with the maui-labs repository.

Platform-Specific Code

DevFlow targets multiple platforms via multi-targeting. The pattern:

• Microsoft.Maui.DevFlow.Agent.Abstractions targets net10.0 — all platform-agnostic code lives here (HTTP server, routing, DevFlowAgentService base class). No MAUI dependency.
• Microsoft.Maui.DevFlow.Agent.Core targets net10.0 — MAUI UI backend (MauiDevFlowAgentService, VisualTreeWalker). Depends on Agent.Abstractions.
• Microsoft.Maui.DevFlow.Agent targets net10.0-android, net10.0-ios, net10.0-maccatalyst, net10.0-macos, net10.0-windows10.0.19041.0 — platform-specific overrides.
• Microsoft.Maui.DevFlow.Agent.Gtk targets net10.0 — Linux/GTK-specific code.

Use #if directives for platform code in multi-targeting projects:

#if IOS || MACCATALYST
    // iOS and Mac Catalyst share UIKit
    return uiWindow.Screen.Scale;
#elif ANDROID
    return activity.Resources?.DisplayMetrics?.Density ?? 1.0;
#elif WINDOWS
    return xamlRoot.RasterizationScale;
#elif MACOS
    return nsWindow.BackingScaleFactor;
#endif

Important: Both .ios.cs and .maccatalyst.cs files compile for Mac Catalyst. Use #if IOS || MACCATALYST when code applies to both.

Agent Architecture (Abstractions/Core/Platform Pattern)

When adding new features to the DevFlow agent:

1. Add the virtual method in Agent.Abstractions/DevFlowAgentService.cs — this is the platform-agnostic base
2. Override in Agent.Core/MauiDevFlowAgentService.cs for MAUI-specific behavior
3. Override in Agent/DevFlowAgentService.cs with #if directives for platform-specific behavior
4. Override in Agent.Gtk/GtkAgentService.cs for Linux/GTK if needed

Example:

// In Agent.Abstractions/DevFlowAgentService.cs
protected virtual Task<byte[]?> CaptureFullScreenAsync() => Task.FromResult<byte[]?>(null);

// In Agent/DevFlowAgentService.cs
#if IOS || MACCATALYST
protected override Task<byte[]?> CaptureFullScreenAsync()
    => DispatchAsync(() => CaptureAllWindowsComposited());
#elif MACOS
protected override async Task<byte[]?> CaptureFullScreenAsync() { /* AppKit capture */ }
#endif