# iOS Simulator Build and App Icon Troubleshooting

**Author**: Matthew Raymer  
**Date**: 2025-07-12  
**Status**: 🎯 **ACTIVE** - In Use

## Overview

This guide documents how to build and run the TimeSafari iOS app in the
simulator, and how to resolve common issues with iOS app icons and
`AppIcon.appiconset` errors.

---

## Building and Running the iOS App in Simulator

### 1. Build the App

Use the npm script to build for development (debug/simulator):

```bash
npm run build:ios:dev
```

This prepares the iOS project for simulator deployment.

### 2. Run in Simulator

Use Capacitor to launch the app in the iOS Simulator:

```bash
npx cap run ios
```

This will:
- Sync web assets
- Build the native iOS app
- Launch the iOS Simulator
- Install and run the app

### 3. Open in Xcode (Optional)

To open the project in Xcode for manual simulator/device control:

```bash
npm run build:ios:dev -- --studio
```

Or:

```bash
npx cap open ios
```

---

## Common App Icon and AppIcon.appiconset Errors

### Typical Error Message

```
error: None of the input catalogs contained a matching stickers icon set or app
icon set named "AppIcon".
```

### Why This Happens

- The iOS build expects an `AppIcon.appiconset` in
  `ios/App/App/Assets.xcassets/`.
- If missing or incomplete, the build fails.
- The icon generator may also fail if the source icon is missing or invalid.

### Typical Causes

- No `AppIcon.appiconset` directory
- No or invalid `Contents.json` in the icon set
- Missing or corrupt `icon.png` in `assets/`
- Generator tool errors (permissions, path, or file type)

---

## Step-by-Step: Generating iOS App Icons

### 1. Automatic Generation (Preferred)

- Place a valid PNG icon (at least 1024x1024) at `assets/icon.png`.
- Run:

```bash
npx capacitor-assets generate --ios
```

- This should create `ios/App/App/Assets.xcassets/AppIcon.appiconset/` with all
  required icon sizes and a `Contents.json`.

#### Troubleshooting Automatic Generation

- If you see errors about missing directories, create them manually:

```bash
mkdir -p ios/App/App/Assets.xcassets/AppIcon.appiconset
```

- If you see errors about file type, ensure `icon.png` is a real PNG (not SVG).
- If the generator fails with a TypeError, check for missing or corrupt files.

### 2. Manual Generation (Fallback)

- Use an online tool like [appicon.co](https://appicon.co/) to generate iOS
  icons from your `icon.png`.
- Download and extract the zip.
- Copy the contents into:

```
ios/App/App/Assets.xcassets/AppIcon.appiconset/
```

- Ensure the `Contents.json` is present and valid.

---

## Directory Structure

```
ios/App/App/Assets.xcassets/
  └── AppIcon.appiconset/
      ├── Contents.json
      ├── AppIcon-20x20@2x.png
      ├── AppIcon-20x20@3x.png
      ├── ...
      └── AppIcon-1024x1024@1x.png
```

---

## Troubleshooting Checklist

- [ ] Is `assets/icon.png` present and a valid PNG?
- [ ] Does `AppIcon.appiconset` exist in `Assets.xcassets`?
- [ ] Is `Contents.json` present and correct?
- [ ] Are all required icon PNGs present?
- [ ] If using the generator, did it complete without errors?
- [ ] If manual, did you copy all files from the zip?

---

## iOS Build Troubleshooting

- If the build fails with icon errors, fix the icon set and rebuild.
- If the simulator does not launch, try running:

```bash
npx cap open ios
```

and launch from Xcode.

- For other build errors, check the logs for missing files or permissions.

---

**Status**: In Use  
**Last Updated**: 2025-07-12  
**Maintainer**: Matthew Raymer