Skip to content

aritchie/DigitalScoreboard / .claude/skills/maui-devflow-debug

maui-devflow-debug

Verified

Run build, deploy, inspect, and fix loops for .NET MAUI apps that already have MAUI DevFlow integrated. USE FOR: launching MAUI apps, selecting devices or emulators, waiting for or recovering agent connections, broker/port/adb connectivity issues, visual tree inspection, screenshots, UI interaction, Blazor WebView CDP debugging, reading DevFlow logs, and iterative app debugging. DO NOT USE FOR: first-time DevFlow package setup (use maui-devflow-onboard), or generic desktop automation unrelated to MAUI. INVOKES: maui devflow CLI, dotnet CLI, Android adb/android tools, and Apple simctl tools.

FileKindSize
SKILL.mdskill md4.6 KB
references/android.mdmarkdown7.5 KB
references/batch.mdmarkdown1.8 KB
references/connectivity.mdmarkdown3.6 KB
references/ios-and-mac.mdmarkdown11.9 KB
references/linux.mdmarkdown6.1 KB
references/macos.mdmarkdown6.8 KB
references/setup.mdmarkdown13.1 KB
references/troubleshooting.mdmarkdown4.4 KB

references/ios-and-mac.md

View on GitHub
# iOS & Mac Catalyst Reference

## Table of Contents
- [Simulator Management](#simulator-management)
- [Building and Deploying](#building-and-deploying)
- [Apple CLI Tool](#apple-cli-tool)
- [xcrun simctl Reference](#xcrun-simctl-reference)
- [Troubleshooting](#troubleshooting)

## Simulator Management

### Avoiding multi-project conflicts

When multiple projects (or AI agents) may deploy to iOS simulators simultaneously, each
project should use its own dedicated simulator. Two apps deployed to the same simulator
will replace each other — only the last-deployed app survives.

**Before creating or booting a simulator, check what's already in use:**
```bash
maui devflow list                             # shows agents with platform + port
xcrun simctl list devices booted              # shows all booted simulators
```

If a booted simulator is already running another project's agent, create a new one:
```bash
xcrun simctl create "ProjectName-iPhone17Pro" "iPhone 17 Pro" "iOS 26.2"
# Use the returned UDID in your build command
```

**Naming convention:** Use `<ProjectName>-<DeviceType>` (e.g. `TodoApp-iPhone17Pro`) so
it's clear which simulator belongs to which project.

### List simulators
```bash
xcrun simctl list devices                     # all devices by runtime
xcrun simctl list devices booted              # only booted
xcrun simctl list devices available            # only available
apple simulator list                          # formatted table
apple simulator list --booted                 # booted only
```

### Create simulator
```bash
# List available device types and runtimes first
xcrun simctl list devicetypes                 # e.g. "iPhone 16 Pro"
xcrun simctl list runtimes                    # e.g. "iOS 18.2"

xcrun simctl create "My iPhone" "iPhone 16 Pro" "iOS 18.2"
apple simulator create "My iPhone" --device-type "iPhone 16 Pro" --runtime "iOS 18.2"
```

### Boot / shutdown
```bash
xcrun simctl boot <UDID>
xcrun simctl shutdown <UDID>
apple simulator boot <UDID>
apple simulator shutdown <UDID>
```

### Install and launch app
```bash
xcrun simctl install booted /path/to/App.app
xcrun simctl launch booted com.company.appid
```

### Screenshots (iOS Simulator)
```bash
xcrun simctl io booted screenshot output.png
apple simulator screenshot <UDID> --output output.png
```

### Screenshots (Mac Catalyst)

**Use `maui devflow ui screenshot`** for Mac Catalyst apps — it captures the UI in-process
and does NOT require the app to be in the foreground. Never use `osascript` to bring the window
to the front or `screencapture` for Mac Catalyst screenshots; they are unnecessary and unreliable.

```bash
maui devflow ui screenshot --output screen.png
```

### Delete / erase
```bash
xcrun simctl erase <UDID>                     # factory reset
xcrun simctl delete <UDID>                    # permanently remove
xcrun simctl delete unavailable               # clean up old sims
```

## Building and Deploying

### Mac Catalyst

**⚠️ Entitlements required:** Mac Catalyst apps are sandboxed by default and need the
`com.apple.security.network.server` entitlement for MAUI DevFlow's in-app HTTP server.
Without it, the agent fails to bind its port and the app may crash silently.

**Quick fix (disable sandbox for Debug):** Create `Platforms/MacCatalyst/Entitlements.Debug.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>com.apple.security.app-sandbox</key>
    <false/>
    <key>com.apple.security.network.client</key>
    <true/>
  </dict>
</plist>
```

Then reference it in `.csproj` for Debug only:
```xml
<PropertyGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)'))
    == 'maccatalyst' and '$(Configuration)' == 'Debug'">
  <CodeSignEntitlements>Platforms/MacCatalyst/Entitlements.Debug.plist</CodeSignEntitlements>
</PropertyGroup>
```

If sandbox must stay enabled (e.g. testing App Store builds), add `network.server` explicitly.
See [setup.md Step 5](setup.md#5-mac-catalyst-entitlements) for the full sandbox-enabled plist.

```bash
dotnet build -f net10.0-maccatalyst                          # build only
dotnet build -f net10.0-maccatalyst -t:Run                   # build + run
open path/to/bin/Debug/net10.0-maccatalyst/maccatalyst-arm64/AppName.app  # run existing
```

### iOS Simulator
```bash
# Find UDID of booted simulator
UDID=$(xcrun simctl list devices booted -j | python3 -c "
import json,sys
d=json.load(sys.stdin)
for r in d['devices'].values():
  for dev in r:
    if dev['state']=='Booted': print(dev['udid']); break
" 2>/dev/null | head -1)

# Build and deploy
dotnet build -f net10.0-ios -t:Run -p:_DeviceName=:v2:udid=$UDID
```

The `-t:Run` target keeps the process alive while the app runs — it **blocks until the app exits**.
Always run in an async/background shell, then poll `maui devflow ui status` to detect when the
app is ready. Do NOT wait for the process to finish.

### Determining the correct TFM
Check the project file for `<TargetFrameworks>`:
```bash
grep -i TargetFramework *.csproj
```
Common values: `net9.0-ios`, `net9.0-maccatalyst`, `net10.0-ios`, `net10.0-maccatalyst`.

## Apple CLI Tool

The `apple` command (from `appledev.tools` NuGet) provides higher-level wrappers.

### Simulator commands
```
apple simulator list [--booted|--available|--unavailable|--name "..."]
apple simulator create <name> --device-type "..." [--runtime "..."]
apple simulator boot <target>
apple simulator shutdown <target>
apple simulator erase <target>
apple simulator delete <target>
apple simulator screenshot <target> [--output path.png]
apple simulator app install <target> <app-path>
apple simulator app launch <target> <bundle-id>
apple simulator app uninstall <target> <bundle-id>
apple simulator open [<target>]
apple simulator open-url <target> <url>
apple simulator logs <target> [--filter "..."]
apple simulator push <target> <bundle-id> [--payload "..."]
apple simulator location set <target> --lat <lat> --lon <lon>
apple simulator privacy grant <target> <service> <bundle-id>
```

### Device commands
```
apple device list
apple xcode list                                # installed Xcode versions
```

## xcrun simctl Reference

Key subcommands beyond the basics:

| Command | Use |
|---------|-----|
| `simctl addmedia <UDID> file.jpg` | Add photos/videos to sim |
| `simctl openurl <UDID> "url"` | Open URL / deep link |
| `simctl push <UDID> bundle payload.json` | Simulate push notification |
| `simctl privacy <UDID> grant location bundle` | Grant permissions |
| `simctl location <UDID> set 37.33,-122.03` | Set GPS location |
| `simctl pbcopy <UDID>` | Copy stdin to clipboard |
| `simctl pbpaste <UDID>` | Read clipboard |
| `simctl get_app_container <UDID> bundle` | App container path |
| `simctl listapps <UDID>` | Installed apps |

## Troubleshooting

- **Mac Catalyst blank/white screen after crash**: macOS shows a "reopen windows" dialog after
  a crash, blocking the app from rendering. All MAUI elements appear as `[hidden] [disabled]`
  with `-1x-1` sizes. Fix: clear saved state before launch:
  ```bash
  rm -rf ~/Library/Saved\ Application\ State/<bundle-id>.savedState
  ```
  If the "Reopen windows?" dialog is already on screen, ask the user to dismiss it manually,
  then relaunch. Do not use AppleScript here by default — it steals focus from the user's
  desktop session.
- **"Unable to lookup in current state: Shutdown"**: Simulator not booted. Run `xcrun simctl boot <UDID>`.
- **Build error NETSDK1005 "Assets file doesn't have a target"**: Wrong TFM. Check
  `<TargetFrameworks>` in .csproj and use matching version (e.g. `net10.0-ios` not `net9.0-ios`).
- **Agent not connecting after deploy**: The app may still be launching. Poll
  `maui devflow ui status` every few seconds. If it hasn't connected after ~60-90s, read the
  async shell output from `dotnet build -t:Run` for build/launch errors.
- **Mac Catalyst app name vs binary name**: The `.app` bundle name may differ from the project
  name (e.g. `MauiTodo.app` vs `SampleMauiApp`). Check the `ApplicationTitle` in .csproj.
  Find the bundle: `find bin/Debug/net10.0-maccatalyst -name "*.app" -maxdepth 3`

## Permission & Dialog Handling

### Pre-grant permissions (prevents dialogs from appearing)
```bash
# Grant specific permission before the app requests it
xcrun simctl privacy <UDID> grant location com.company.appid
xcrun simctl privacy <UDID> grant camera com.company.appid
xcrun simctl privacy <UDID> grant photos com.company.appid
xcrun simctl privacy <UDID> grant contacts com.company.appid
xcrun simctl privacy <UDID> grant microphone com.company.appid

# Grant all permissions at once
xcrun simctl privacy <UDID> grant all com.company.appid

# Revoke (deny) a permission
xcrun simctl privacy <UDID> revoke location com.company.appid

# Reset (next request will show dialog again)
xcrun simctl privacy <UDID> reset all com.company.appid

# Via apple CLI
apple simulator privacy grant <UDID> location com.company.appid
```

Available services: `all`, `calendar`, `contacts`, `contacts-limited`, `location`, `location-always`, `photos`, `photos-add`, `media-library`, `microphone`, `motion`, `reminders`, `siri`.

### Using MAUI DevFlow Driver for permissions
```csharp
var driver = new iOSSimulatorAppDriver();
driver.DeviceUdid = "<UDID>";
driver.BundleId = "com.company.appid";

// Pre-grant before running the app
await driver.GrantPermissionAsync(PermissionService.Location);
await driver.GrantPermissionAsync(PermissionService.Camera);

// Reset to test the dialog flow
await driver.ResetPermissionAsync(PermissionService.Location);
```

### Detecting and dismissing alerts (accessibility tree + HID tap)
When a dialog appears unexpectedly (permission prompt, app alert, action sheet), the driver can
detect it via the iOS accessibility tree and tap a button to dismiss it:

```csharp
// Check if an alert is currently showing
var alert = await driver.DetectAlertAsync();
if (alert is not null)
{
    Console.WriteLine($"Alert: {alert.Title}");
    foreach (var btn in alert.Buttons)
        Console.WriteLine($"  Button: {btn.Label} at ({btn.CenterX},{btn.CenterY})");
}

// Dismiss by tapping the first "accept" button (Allow, OK, etc.)
await driver.DismissAlertAsync();

// Dismiss by tapping a specific button
await driver.DismissAlertAsync("Don't Allow");

// Convenience: detect + dismiss if present, no-op if not
await driver.HandleAlertIfPresentAsync();
```

### Example workflow: permission dialog handling
```
1. App requests location → system shows "Allow location?" dialog
2. Agent detects dialog via DetectAlertAsync()
3. Agent sees buttons: ["Allow While Using App", "Allow Once", "Don't Allow"]
4. Agent taps "Allow While Using App" via DismissAlertAsync("Allow While Using App")
5. App receives permission grant, continues normal flow
```

### Dialog test page in SampleMauiApp
The SampleMauiApp includes a **Dialogs** tab with buttons that trigger:
- **Permission dialogs**: Location, Camera, Photos, Contacts, Microphone, Notifications
- **App alerts**: OK-only, OK/Cancel, custom buttons (Delete/Keep)
- **Action sheets**: Multiple options with cancel/destructive
- **Prompt dialogs**: Text input with OK/Cancel

Use these to test and validate dialog detection and dismissal workflows.

## Dark Mode Testing

### Toggle dark mode
```bash
# Preferred when available: use an in-app theme toggle so the host desktop is unaffected.
#
# iOS Simulator (safe: affects the simulator only)
xcrun simctl ui <UDID> appearance dark
xcrun simctl ui <UDID> appearance light
```

For **Mac Catalyst**, changing system appearance affects the user's entire macOS desktop. Only do
that with explicit user approval; otherwise prefer app-level theme controls and verify via
`maui devflow ui property` / WebView inspection.

### Verify dark mode via inspection
Use `maui devflow` to verify colors without relying on screenshots:
```bash
maui devflow ui property <elementId> BackgroundColor   # check MAUI element colors
maui devflow webview Runtime evaluate "window.matchMedia('(prefers-color-scheme: dark)').matches"  # Blazor
```
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall