divine-mobile: Skill for Claude Code

Media Kit macOS Codesign Crash Fix

Problem

Flutter macOS apps using media_kit (video player library) crash immediately at launch after a clean build. The app builds successfully but fails to start due to unsigned native frameworks.

Context / Trigger Conditions

• macOS Flutter app using media_kit or media_kit_video package
• App builds without errors: "Built build/macos/Build/Products/Debug/divine.app"
• App crashes immediately on launch with no UI appearing
• Crash report or console shows:

  Library not loaded: @rpath/Ass.framework/Versions/A/Ass
  Reason: code signature in '...' not valid for use in process: Trying to load an unsigned library
  

• Often occurs after flutter clean, pod deintegrate + pod install, or fresh git clone
• CRITICAL: Can also occur when the codesign script EXISTS but runs in the wrong order

Root Cause: Build Phase Ordering

The most common cause (especially after pod deintegrate + pod install) is that the Xcode build phases end up in the wrong order:

WRONG order (codesign runs before frameworks are copied):

1. [CP] Check Pods Manifest.lock
2. Sources
3. Frameworks
4. Resources
5. Bundle Framework
6. ShellScript (Flutter assemble)
7. Codesign media_kit frameworks    ← SIGNS NOTHING (frameworks not embedded yet)
8. [CP] Embed Pods Frameworks       ← copies frameworks into app bundle

CORRECT order (embed first, then codesign):

1. [CP] Check Pods Manifest.lock
2. Sources
3. Frameworks
4. Resources
5. Bundle Framework
6. ShellScript (Flutter assemble)
7. [CP] Embed Pods Frameworks       ← copies frameworks into app bundle
8. Codesign media_kit frameworks    ← signs the embedded frameworks
9. FlutterFire upload symbols        ← (if applicable, should be last)

Solution

Step 1: Add Codesign Phase via Podfile (if missing)

Add this block inside the post_install do |installer| section:

post_install do |installer|
  # Add script phase to codesign media_kit frameworks (fixes unsigned library crash)
  installer.pods_project.targets.each do |target|
    if target.name == 'media_kit_libs_macos_video'
      target.build_configurations.each do |config|
        config.build_settings['CODE_SIGN_IDENTITY'] = '-'
      end
    end
  end

  # Also add codesigning to the main project's frameworks
  main_project = installer.aggregate_targets.first.user_project
  main_project.targets.each do |target|
    if target.name == 'Runner'
      # Check if script phase already exists
      phase_name = 'Codesign media_kit frameworks'
      existing_phase = target.shell_script_build_phases.find { |p| p.name == phase_name }

      unless existing_phase
        phase = target.new_shell_script_build_phase(phase_name)
        phase.shell_script = <<-SCRIPT
# Codesign media_kit frameworks with ad-hoc signature
for framework in "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Contents/Frameworks"/*.framework; do
  if [ -d "$framework" ]; then
    codesign --force --deep --sign - "$framework" 2>/dev/null || true
  fi
done
        SCRIPT
        phase.shell_path = '/bin/bash'
      end
    end
  end
  main_project.save

  # ... rest of your existing post_install code ...