App Extensions

• Check deployment target (iOS 16+ / macOS 13+)
• Check Swift version (requires Swift 5.9+)
• Identify project structure (find .xcodeproj or Package.swift)
• Identify source file locations

2. Existing Extension Detection

Search for existing extension targets:

Glob: **/*Extension*/*.swift, **/*Extension*/Info.plist
Grep: "NSExtensionPointIdentifier" or "NSExtensionPrincipalClass"

If existing extensions found:

• Ask if user wants to add another or modify existing
• Identify existing App Groups configuration

3. App Groups Detection

Check for existing App Groups setup:

Glob: **/*.entitlements
Grep: "com.apple.security.application-groups"

If App Groups exist, reuse the existing group identifier.

Configuration Questions

Ask user via AskUserQuestion:

1. What type of extension?

   • Share Extension (accept content from other apps, display share UI)
   • Action Extension (manipulate content in-place -- transform text, edit images)
   • Keyboard Extension (custom input keyboard with KeyboardViewController)
   • Safari Web Extension (inject JavaScript/CSS into web pages)

2. What content types does it handle?

   • Text (plain text, rich text)
   • URLs (web links, deep links)
   • Images (photos, screenshots)
   • Files (documents, PDFs, archives)
   • All (any content type)

3. Does the extension need to share data with the main app?

   • Yes -- needs App Groups (shared UserDefaults, shared file container, shared Keychain)
   • No -- extension is self-contained

Generation Process

Step 1: Read Templates

Read templates.md for production Swift code.

Step 2: Create Extension Files

Based on extension type selected:

Share Extension:

1. ShareViewController.swift -- Main share extension view controller with content handling
2. Info.plist -- Extension configuration with activation rules

Action Extension: 3. ActionViewController.swift -- Action extension with content manipulation 4. Info.plist -- Extension configuration

Keyboard Extension: 5. KeyboardViewController.swift -- Custom keyboard with UIInputViewController 6. Info.plist -- Keyboard extension configuration

Safari Web Extension: 7. SafariWebExtensionHandler.swift -- Native message handler 8. manifest.json -- Web extension manifest 9. content.js -- Content script template

Step 3: Create Shared Infrastructure

If data sharing selected: 10. SharedDataManager.swift -- App Group data sharing helper

Step 4: Determine File Location

Extensions are separate targets:

• Share Extension -> ShareExtension/
• Action Extension -> ActionExtension/
• Keyboard Extension -> KeyboardExtension/
• Safari Web Extension -> SafariWebExtension/
• Shared code -> Shared/ or within main app target

Output Format

After generation, provide:

Files Created

Share Extension:

ShareExtension/
├── ShareViewController.swift  # Main share extension view controller
└── Info.plist                 # Extension activation rules & config

Action Extension:

ActionExtension/
├── ActionViewController.swift # Content manipulation controller
└── Info.plist                 # Extension activation rules & config

Keyboard Extension:

KeyboardExtension/
├── KeyboardViewController.swift # UIInputViewController subclass
└── Info.plist                   # Keyboard extension config

Safari Web Extension:

SafariWebExtension/
├── SafariWebExtensionHandler.swift # Native message handler
└── Resources/
    ├── manifest.json               # Web extension manifest
    ├── content.js                  # Content script
    └── popup.html                  # Popup UI (optional)

Shared (if data sharing enabled):

Shared/
└── SharedDataManager.swift    # App Group data sharing

Integration Steps

1. Add Extension Target in Xcode:

• File > New > Target
• Select the extension type (Share, Action, Keyboard, Safari Web)
• Configure bundle identifier: com.yourapp.ShareExtension
• Xcode creates the target with boilerplate -- replace with generated code

2. Configure App Groups (if data sharing):

• Select main app target > Signing & Capabilities > Add "App Groups"
• Add group: group.com.yourapp.shared
• Select extension target > Signing & Capabilities > Add "App Groups"
• Add the same group identifier

3. Share code between targets:

• Add shared files to both the app and extension targets
• Or create a shared framework target

Extension Content Handling

Accept shared URLs:

if provider.hasItemConformingToTypeIdentifier(UTType.url.identifier) {
    provider.loadItem(forTypeIdentifier: UTType.url.identifier) { item, error in
        guard let url = item as? URL else { return }
        // Process URL
    }
}

Accept shared images:

if provider.hasItemConformingToTypeIdentifier(UTType.image.identifier) {
    provider.loadItem(forTypeIdentifier: UTType.image.identifier) { item, error in
        if let imageURL = item as? URL {
            let imageData = try? Data(contentsOf: imageURL)
            // Process image data
        }
    }
}

Share data to main app via App Groups:

let shared = SharedDataManager.shared
shared.saveSharedContent(url.absoluteString, forKey: "lastSharedURL")

Testing

Share Extension:

1. Build and run the extension scheme
2. Select a host app (Safari, Photos, etc.)
3. Share content and verify your extension appears
4. Test with different content types

Action Extension:

1. Build and run the extension scheme
2. Open content in a supported app
3. Tap the share/action button and select your action

Keyboard Extension:

1. Build and run the keyboard extension scheme
2. Go to Settings > General > Keyboard > Keyboards > Add New Keyboard
3. Select your keyboard
4. Open any text field and switch to your keyboard

Safari Web Extension:

1. Build and run the app (which contains the extension)
2. Go to Safari > Settings > Extensions
3. Enable your extension
4. Navigate to a web page and verify behavior

Extension Lifecycle and Limits

Memory Limits

• Share Extension: ~120 MB
• Action Extension: ~120 MB
• Keyboard Extension: ~48 MB (very constrained)
• Safari Web Extension: ~6 MB for content scripts

Execution Limits

• Extensions must complete work quickly (no long background execution)
• Must call completeRequest() or cancelRequest() when done
• No access to HealthKit, CallKit, or some restricted frameworks
• Network requests are allowed but should be brief

Extension Termination

The system can terminate extensions at any time for resource reclamation. Save state frequently and handle interruption gracefully.

Gotchas

completeRequest Must Be Called

The extension host waits for extensionContext?.completeRequest(returningItems:). If you never call it, the share sheet hangs and the user is stuck. Always call it in both success and error paths.

Keyboard Extensions Need Open Access for Network

By default keyboard extensions have no network access. The user must explicitly grant "Allow Full Access" in Settings. Without it, URLSession calls fail silently. Design your keyboard to work without network and enhance when access is granted.

App Groups Require Matching Identifiers

The App Group identifier must be identical in both the main app and extension entitlements. A typo means UserDefaults(suiteName:) returns a different (empty) container.

Safari Web Extension Content Scripts Run in Isolated World

Content scripts cannot directly access the page's JavaScript variables. Use window.postMessage or the browser messaging API to communicate between content scripts and the page.

Extension Bundle Identifier Convention

Extension bundle identifiers must be prefixed with the main app bundle identifier:

• Main app: com.yourcompany.myapp
• Share Extension: com.yourcompany.myapp.ShareExtension

References

• templates.md -- All production Swift templates for each extension type
• App Extension Programming Guide
• Creating a Share Extension
• Custom Keyboard Guide
• Safari Web Extensions
• Related: generators/deep-linking -- Handle URLs received via extensions
• Related: generators/push-notifications -- Notification extensions (Service/Content)