---
name: mac-ipad-display
description: Configure and troubleshoot an old iPad as a low-latency macOS extended or primary display using DeskPad, Sunshine, Moonlight, and displayplacer. Use when a user asks about replacing Yam Display or Sidecar, creating a virtual display, switching mirror to extend, making an iPad the main screen, fixing cursor crossing or display placement, hiding DeskPad previews or Moonlight controls, improving stream latency and quality, configuring login startup, or diagnosing this specific display stack.
---

# Mac iPad Display

Turn an old iPad into a real macOS desktop surface. Prefer the repository's tested installer for mutations and the bundled diagnostic script for read-only inspection.

## Safety rules

- Inspect before changing anything. Run `scripts/diagnose.zsh` first when a setup already exists.
- Treat installation, layout changes, service changes, and package changes as mutations. Perform them only when the user asks to configure or fix the system.
- Never automate Sunshine passwords, bypass macOS privacy controls, disable FileVault, or enable automatic login without a separate explicit request and a security warning.
- Keep Sunshine local to the LAN. Preserve `upnp = disabled`; do not expose its ports publicly.
- Do not redistribute third-party binaries from this skill. Install them from official projects or Homebrew sources.
- The automatic installer supports one physical Mac display during setup. Stop and explain when two or more non-DeskPad displays are present.
- Preserve unrelated display settings and user configuration. Verify the final live layout and service state after every change.

## Workflow

### 1. Classify the request

- For explanation or recommendation, inspect only what is needed and answer without changing the Mac.
- For diagnosis, run the diagnostic script and determine the failed layer: virtual display, layout, host capture, network, or Moonlight client.
- For installation or a fix, inspect first, make the narrow requested change, and verify afterward.

### 2. Inspect the current Mac

Run:

```zsh
skills/mac-ipad-display/scripts/diagnose.zsh
```

If the skill is installed outside the repository, use the absolute path to its `scripts/diagnose.zsh`.

Confirm:

- DeskPad exists and its virtual display has a persistent and contextual ID.
- `displayplacer` reports distinct origins rather than mirroring.
- Sunshine is running with `output_name` set to DeskPad's current contextual ID.
- The management endpoint responds at `https://localhost:47990`.
- The Moonlight `serverinfo` endpoint responds on local port 47989 and no encoder probe remains pending.
- Only one supervisor owns Sunshine; avoid a Homebrew service and custom LaunchAgent running together.

Read [references/system-design.md](references/system-design.md) when reasoning about component ownership or display geometry. Read [references/troubleshooting.md](references/troubleshooting.md) for symptom-specific checks and Moonlight settings.

### 3. Install or reconfigure

When operating from the repository, begin with a no-change check:

```zsh
./install.sh --dry-run --position left --main ipad --resolution 1280x960 --refresh 60
```

If the output is safe and the user requested installation, run the same command without `--dry-run`.

Interpret `--position` as the iPad's location relative to the Mac display. Valid values are `left`, `right`, `above`, and `below`. Valid main displays are `ipad` and `mac`.

For iPad mini 2, start with:

```zsh
./install.sh --position left --main ipad --resolution 1280x960 --refresh 60
```

Do not claim the workflow is fully unattended. The user must grant Screen Recording, create Sunshine credentials, and approve Moonlight pairing.

### 4. Guide the Moonlight client

Use these conservative defaults for iPad mini 2:

- Resolution: custom 1280x960
- Frame rate: 60 FPS
- Bitrate: 15 Mbps; lower to 10-12 Mbps if unstable
- Codec: H.264
- HDR: off
- On-Screen Controls: off

USB is optional for power. Streaming uses the LAN; prefer Ethernet for the Mac and 5 GHz Wi-Fi for the iPad.

### 5. Verify the result

Run:

```zsh
./status.sh
displayplacer list
```

Verify all of the following before reporting completion:

- DeskPad and Sunshine are running.
- Sunshine's management endpoint responds.
- The iPad display has the requested resolution and origin.
- Exactly one display is at origin `(0,0)` and is therefore the intended main display.
- The two display rectangles share an edge where the cursor should cross.
- Re-launching DeskPad changes only the contextual ID and the supervisor recovers Sunshine.
- A persistently unavailable Moonlight endpoint or stalled encoder probe causes the supervisor to rebuild DeskPad and Sunshine after consecutive failures.

Mention that login LaunchAgents start only after macOS login. Do not promise access to FileVault unlock or the pre-login screen.