# Handles precompiled XCFramework module integration for Expo.
#
# This module provides functionality to:
# 1. Link pods with prebuilt XCFrameworks instead of building from source
# 2. Discover which pods are using prebuilt XCFrameworks
# 3. Filter prebuilt libraries from React Native's codegen to avoid duplicate symbols
#
# When EXPO_USE_PRECOMPILED_MODULES=1 is set, packages with matching XCFrameworks
# in the centralized build output will be linked as vendored frameworks.
#
# Build output:     packages/precompile/.build/<pkg>/output/<flavor>/xcframeworks/<Product>.tar.gz
# Custom path:      Set EXPO_PRECOMPILED_MODULES_PATH to override the base directory
#                   (replaces packages/precompile/.build/), keeping <pkg>/output/... structure
#
# Pod install flow:
#   1. has_prebuilt_xcframework?(pod_name) returns true → autolinking uses :podspec instead of :path
#   2. store_podspec hook auto-patches the spec via patch_spec_for_prebuilt (sandbox.rb)
#   3. spec.source is set to {:http => "file:///<tarball>"} → CocoaPods extracts into Pods/<PodName>/
#   4. prepare_command copies both flavor tarballs into artifacts/ subdirectory
#   5. Script phases switch debug/release at build time via tarball extraction
#
# Resulting layout in Pods/<PodName>/:
#   <Product>.xcframework/                    (extracted by CocoaPods from source tarball)
#   artifacts/<Product>-debug.tar.gz          (copied by prepare_command)
#   artifacts/<Product>-release.tar.gz        (copied by prepare_command)
#   artifacts/.last_build_configuration       (written by prepare_command / switch script)

require 'fileutils'
require 'json'
require 'net/http'
require 'open3'
require 'set'
require 'tempfile'
require 'tmpdir'
require 'uri'

# The macOS system Ruby is 2.6, which lacks Enumerable#filter_map (added in 2.7). Without it the
# precompiled modules code raises NoMethodError, and modules silently fall back to building from source.
unless Enumerable.method_defined?(:filter_map)
  module Enumerable
    def filter_map
      return to_enum(:filter_map) unless block_given?

      each_with_object([]) do |item, result|
        value = yield(item)
        result << value if value
      end
    end
  end
end

module Expo
  module PrecompiledModules
    # The environment variable that enables precompiled modules
    ENV_VAR = 'EXPO_USE_PRECOMPILED_MODULES'.freeze

    # Environment variable for build flavor override
    BUILD_FLAVOR_ENV_VAR = 'EXPO_PRECOMPILED_FLAVOR'.freeze

    # Environment variable for custom precompiled modules base path
    MODULES_PATH_ENV_VAR = 'EXPO_PRECOMPILED_MODULES_PATH'.freeze

    # Environment variable for a shared remote base URL used by external prebuilt packages.
    EXTERNAL_MODULES_BASE_URL_ENV_VAR = 'EXPO_PRECOMPILED_MODULES_BASE_URL'.freeze

    # When set to a file path, `pod install` writes the derivations dump there.
    DUMP_ENV_VAR = 'EXPO_PRECOMPILED_DUMP'.freeze

    # Subdirectory within each pod dir for tarballs and build state
    ARTIFACTS_DIR_NAME = 'artifacts'.freeze

    # Centralized build output directory under packages/precompile/
    PRECOMPILE_BUILD_DIR = '.build'.freeze

    # Subdir under packages/precompile/.build/ holding <Name>/<flavor>/<Name>.xcframework (monorepo source).
    SHARED_SPM_DEPS_SOURCE_DIR = '.spm-deps'.freeze
    # Subdir inside an npm package that bundles shared SPM xcframeworks for standalone consumers.
    BUNDLED_SHARED_SPM_DEPS_SUBPATH = File.join('prebuilds', 'spm-deps').freeze

    # Apple platforms supported by CocoaPods podspecs
    APPLE_PLATFORMS = %w[ios osx tvos watchos visionos].freeze

    # Implementation source file extensions (everything except headers)
    SOURCE_FILE_EXTENSIONS = %w[.m .mm .c .cpp .swift].freeze

    # ExpoModulesJSI is always provided as an xcframework by its own podspec/npm package,
    # so it is not resolved through the Expo precompiled tarball pipeline.
    CUSTOM_XCFRAMEWORK_DEPENDENCIES = %w[ExpoModulesJSI].freeze

    # Prebuilt pods whose headers already reach every target through another mechanism.
    GLOBALLY_INJECTED_PREBUILT_PODS = %w[
      ExpoModulesCore
      React
      React-Core-prebuilt
      Hermes
      ReactNativeDependencies
    ].freeze

    # Unavailability reasons where the pod's own artifact is fine and an interdependent
    # pod pulled it to source. The expected-tarball hint is misleading for these.
    CASCADED_UNAVAILABLE_REASONS = %i[dependency_unavailable dependent_unavailable].freeze

    # bsdtar's wording when a member pattern matches nothing, as opposed to a real failure.
    TAR_NO_MATCH_MESSAGE = 'Not found in archive'.freeze

    # Module-level caches (initialized lazily)
    @pod_lookup_map = nil
    @repo_root = nil
    @linked_pods = nil
    @build_from_source_patterns = []
    @react_native_version = nil
    @hermes_version = nil
    @claimed_vendored_frameworks = nil  # Set<String> — xcframework names already claimed by a prebuilt pod
    @framework_owner_map = nil          # Hash: framework_name -> owning_pod_name
    @prebuilt_dependent_pods = nil      # Hash: pod_name -> pods declaring it as a dependency
    @failed_remote_downloads = Set.new
    @warned_no_prebuilt_react = false
    @target_platform = nil
    @xcframework_slice_cache = nil
    @status_cache = {}                  # Hash: pod_name -> resolve_prebuilt_status result
    @spm_dependency_pods = Set.new

    # Prepended onto React Native's SPMManager, which keeps the pods calling `spm_dependency` private.
    module SPMDependencyRecorder
      def dependency(pod_spec, **kwargs)
        Expo::PrecompiledModules.spm_dependency_pods.add(pod_spec.name.split('/').first)
        super
      end
    end

    class << self
      # Root names of pods that resolve Swift packages through React Native's `spm_dependency`.
      attr_reader :spm_dependency_pods

      # Starts recording `spm_dependency` calls. Must run before podspecs are evaluated;
      # `use_expo_modules!` does, after the Podfile has loaded React Native's SPMManager.
      # Repeated calls are no-ops: Ruby prepends a module only once.
      def record_spm_dependency_pods
        ::SPMManager.prepend(SPMDependencyRecorder) if defined?(::SPMManager)
      end

      # Returns the build flavor (debug/release) for precompiled modules.
      # Defaults to 'debug', can be overridden via EXPO_PRECOMPILED_FLAVOR env var.
      def build_flavor
        ENV[BUILD_FLAVOR_ENV_VAR] || 'debug'
      end

      # Returns custom base path for precompiled module output, if set.
      # When set, replaces the default `packages/precompile/.build/` base directory.
      # The directory structure under this path must match:
      #   <npm_package>/output/<flavor>/xcframeworks/<Product>.tar.gz
      def custom_modules_path
        ENV[MODULES_PATH_ENV_VAR]
      end

      # Returns the shared base URL for remote external prebuilt artifacts, if set.
      def external_modules_base_url
        ENV[EXTERNAL_MODULES_BASE_URL_ENV_VAR]
      end

      # Returns true if precompiled modules are enabled via environment variable.
      # Precompiled module xcframeworks are linked against the prebuilt
      # React.xcframework, so they also require RCT_USE_PREBUILT_RNCORE=1. If
      # the user opted in to precompiled modules but React Native is still set
      # to build from source, fall back to source-built modules and print once.
      def enabled?
        return false unless ENV[ENV_VAR] == '1'
        return true if prebuilt_react_active?

        unless @warned_no_prebuilt_react
          @warned_no_prebuilt_react = true
          Pod::UI.puts "[Expo] EXPO_USE_PRECOMPILED_MODULES=1 was set, but React Native is configured to build from source (RCT_USE_PREBUILT_RNCORE is not 1). Precompiled Expo modules require the prebuilt React.xcframework, so every Expo module will be built from source for this install. To use precompiled modules, ensure `ios.buildReactNativeFromSource` is not `true` in the `expo-build-properties` plugin (the default uses the prebuilt framework), or export RCT_USE_PREBUILT_RNCORE=1 before running `pod install`.".yellow
        end
        false
      end

      def configure(target_platform: nil, build_from_source: nil)
        self.target_platform = target_platform unless target_platform.nil?
        self.build_from_source = build_from_source unless build_from_source.nil?
      end

      def build_from_source=(patterns)
        @build_from_source_patterns = (patterns || []).map { |p| Regexp.new("^#{p}$") }
        @prebuilt_dependent_pods = nil
        @status_cache = {}
      end

      def target_platform=(platform)
        normalized = normalize_xcframework_platform(platform)
        return if @target_platform == normalized

        @target_platform = normalized
        @all_bundled_frameworks = nil
        @claimed_vendored_frameworks = nil
        @framework_owner_map = nil
        @xcframework_slice_cache = nil
        @prebuilt_dependent_pods = nil
        @status_cache = {}
      end

      # Checks if a pod is configured to be built from source via buildFromSource.
      # Matches against both the pod name and the npm package name.
      def build_from_source?(pod_name)
        return false unless @build_from_source_patterns&.any?

        npm_package = pod_lookup_map[pod_name]&.dig(:npm_package)
        @build_from_source_patterns.any? { |re|
          re.match?(pod_name) || (npm_package && re.match?(npm_package))
        }
      end

      # @react-native-community/cli autolinking output (same shape as RN CLI's `config`).
      # Used to locate 3rd-party packages via real node resolution so non-flat node_modules
      # layouts (pnpm non-hoisted, yarn PnP, aliased specifiers) resolve correctly.
      def react_native_config
        @react_native_config ||= invoke_autolinking('react-native-config', platform: 'ios')
      end

      # The resolved Expo modules list. Used by scan_node_modules_configs to locate
      # each internal package's spm.config.json via its resolved podspec dir.
      def resolved_modules
        @resolved_modules ||= invoke_autolinking('resolve', platform: 'apple').fetch('modules', [])
      end

      # ──────────────────────────────────────────────────────────────────────
      # Facade methods — called from installer.rb / autolinking_manager.rb
      # ──────────────────────────────────────────────────────────────────────

      # Runs all precompiled module post-install steps.
      # Called from installer.rb after CocoaPods' own post-install actions.
      #
      # @param installer [Pod::Installer] The CocoaPods installer instance
      def perform_post_install(installer)
        dump_derivations(ENV[DUMP_ENV_VAR]) unless ENV[DUMP_ENV_VAR].to_s.empty?
        print_linking_summary
        disable_swift_interface_verification(installer)
        ensure_modular_react_header_flags(installer)
        requote_swift_compat_header_paths(installer)
        ensure_artifacts(installer)
        configure_header_search_paths(installer)
        configure_prebuilt_dependency_header_search_paths(installer)
        configure_codegen_for_prebuilt_modules(installer)
        stub_bundled_pod_targets(installer)
        quote_swift_compatibility_header_search_paths(installer)
      end

      # Runs all precompiled module pre-install steps.
      # Disables use_frameworks! for pods that can't be built as frameworks:
      # - Hardcoded list of pods with React headers in their public API
      # - Pods that vendor xcframeworks (already precompiled)
      # - Source-built pods that depend on React-Core (non-modular includes)
      # - Pods that depend, directly or transitively, on a static pod (CocoaPods rejects that for frameworks)
      # With dynamic frameworks, pods that call React Native's `spm_dependency` keep them, and so do
      # their dependencies, unless one of those is in `framework_modules_to_patch`.
      #
      # Also stages shared SPM dep xcframework symlinks inside their owner pod's
      # directory — must run before `generate_pods_project` reads each xcframework's
      # Info.plist to slice it.
      #
      # @param installer [Pod::Installer] The CocoaPods installer instance
      def perform_pre_install(installer)
        return unless enabled?
        ensure_shared_spm_deps(installer)
        linkage = linkage(installer)
        return if linkage.nil?

        pods_to_downgrade = pods_to_downgrade(
          installer.pod_targets,
          linkage: linkage,
          framework_modules_to_patch: installer.podfile.framework_modules_to_patch,
          spm_dependency_pods: spm_dependency_pods
        )

        Pod::UI.puts "[Expo] ".blue + "Disabling USE_FRAMEWORKS for #{pods_to_downgrade.size} pods (#{pods_to_downgrade.to_a.join(', ')})"

        installer.pod_targets.each do |t|
          if pods_to_downgrade.include?(t.name)
            def t.build_type
              Pod::BuildType.static_library
            end
          else
            # @react-native-firebase's `rnfirebase_restore_dynamic_linkage_after_expo_prebuilt!` calls
            # `build_type`, which CocoaPods keeps private, on every RNFB pod, downgraded or not.
            def t.build_type
              super
            end
          end
        end
      end

      # Returns the names of the pods that `perform_pre_install` builds as static libraries.
      #
      # @param pod_targets [Array<Pod::PodTarget>]
      # @param linkage [Symbol] :dynamic or :static, see `linkage`
      # @param framework_modules_to_patch [Array<String>] Pods the Podfile forces to link statically
      # @param spm_dependency_pods [Set<String>] Root names of pods that call React Native's `spm_dependency`
      # @return [Set<String>]
      def pods_to_downgrade(pod_targets, linkage:, framework_modules_to_patch:, spm_dependency_pods:)
        pods_to_downgrade = Set.new(framework_modules_to_patch)

        pod_targets.each do |t|
          if has_vendored_xcframeworks?(t)
            pods_to_downgrade.add(t.name)
          elsif t.root_spec.dependencies.any? { |d| d.name.start_with?('React-Core') }
            pods_to_downgrade.add(t.name)
          end
        end

        pod_targets.each do |t|
          next unless t.should_build? && t.build_as_dynamic?
          if t.recursive_dependent_targets.any? { |d| pods_to_downgrade.include?(d.name) || d.build_as_static? }
            pods_to_downgrade.add(t.name)
          end
        end

        return pods_to_downgrade unless linkage == :dynamic

        # Packages such as @stripe/stripe-react-native fail their own post-install check unless
        # their pod is a dynamic framework, and CocoaPods rejects a dynamic framework with any
        # static dependency. So the pod and its whole dependency graph keep their linkage,
        # unless that graph contains a pod the installer forces static after this step.
        exempted_pods = []
        pod_targets.each do |t|
          next unless spm_dependency_pods.include?(t.pod_name)
          graph = [t] + t.recursive_dependent_targets
          static_pod = graph.map(&:name).find { |name| framework_modules_to_patch.include?(name) }
          if static_pod
            Pod::UI.puts "[Expo] ".blue + "Disabling USE_FRAMEWORKS for #{t.name}, which resolves Swift packages through spm_dependency, because #{static_pod} must link statically"
            next
          end
          graph.each { |d| pods_to_downgrade.delete(d.name) }
          exempted_pods << t.name
        end

        unless exempted_pods.empty?
          Pod::UI.puts "[Expo] ".blue + "Keeping USE_FRAMEWORKS for pods that resolve Swift packages through spm_dependency, and their dependencies (#{exempted_pods.join(', ')})"
        end

        pods_to_downgrade
      end

      # Canonical JSON dump (one pod per line) of the pure derivations behind
      # pod_lookup_map — the ENG-25370 snapshot/differential baseline.
      # build_output_dir is excluded: it depends on which artifacts exist locally.
      def dump_derivations(output_path)
        repo_root = memoized_repo_root
        lines = pod_lookup_map.sort_by { |pod_name, _| pod_name }.map do |pod_name, info|
          entry = {
            'type' => info[:type].to_s,
            'npmPackage' => info[:npm_package],
            'packageRoot' => repo_relative_path(info[:package_root], repo_root),
            'podspecDir' => repo_relative_path(info[:podspec_dir], repo_root),
            'productName' => info[:product_name],
            'codegenName' => info[:codegen_name],
            'spmDependencyFrameworks' => info[:spm_dependency_frameworks] || [],
            'spmDependencyVersions' => (info[:spm_dependency_versions] || {}).sort.to_h,
            'dependencyProducts' => info[:prebuilt_dependency_pods] || [],
            'autolinkWhen' => info[:autolink_when],
          }
          "  #{pod_name.to_json}: #{JSON.generate(entry)}"
        end
        FileUtils.mkdir_p(File.dirname(output_path))
        File.write(output_path, "{\n#{lines.join(",\n")}\n}\n")
        Pod::UI.puts "[Expo-precompiled] Wrote derivations dump (#{lines.size} pods) to #{output_path}"
      end

      # pnpm store segments are collapsed: their names embed version and patch
      # hashes, which would churn the fixture on every dependency bump.
      def repo_relative_path(path, repo_root)
        return path unless path && repo_root && path.start_with?(repo_root + File::SEPARATOR)
        path[(repo_root.length + 1)..].sub(%r{\Anode_modules/\.pnpm/[^/]+/node_modules/}, 'node_modules/')
      end

      # Symlinks each shared SPM dependency xcframework (e.g. SDWebImage) into the
      # pod directory of its owner. Ownership is whatever `build_vendored_paths` set
      # in `@framework_owner_map` during `store_podspec` (resolution-first);
      # falls back to alphabetical-first only if the map has no entry. Must run
      # before `generate_pods_project` so CocoaPods sees the symlinks when reading
      # each xcframework's Info.plist.
      def ensure_shared_spm_deps(installer)
        return unless enabled?

        consumers_by_dep = collect_shared_spm_deps(installer)
        return if consumers_by_dep.empty?

        @framework_owner_map ||= {}
        @claimed_vendored_frameworks ||= Set.new

        unresolved = []
        staged = 0

        consumers_by_dep.each do |dep_name, consumers|
          existing = @framework_owner_map[dep_name]
          owner_name = (existing && consumers.key?(existing)) ? existing : consumers.keys.sort.first
          owner_info = consumers[owner_name]
          @framework_owner_map[dep_name] ||= owner_name
          @claimed_vendored_frameworks.add(dep_name)

          source_path = shared_spm_dep_xcframework_path(dep_name, owner_info, build_flavor)
          owner_pod_dir = File.join(installer.sandbox.root, owner_name)
          unless source_path && File.directory?(owner_pod_dir)
            unresolved << dep_name
            next
          end

          FileUtils.rm_rf(File.join(owner_pod_dir, "#{dep_name}.xcframework"))
          File.symlink(source_path, File.join(owner_pod_dir, "#{dep_name}.xcframework"))
          staged += 1
        end

        if unresolved.any?
          Pod::UI.warn "[Expo-precompiled] Shared SPM xcframeworks not found for: #{unresolved.join(', ')} (flavor: #{build_flavor}). The Expo modules that depend on them will fail at runtime with dyld 'Library not loaded: @rpath/<Name>.framework/<Name>'. Run the precompile prebuild pipeline, or ensure each consuming npm package ships prebuilds/spm-deps/<Name>/<flavor>/<Name>.xcframework."
        end

        Pod::UI.puts "[Expo] ".blue + "Staged #{staged}/#{consumers_by_dep.size} shared SPM xcframework(s) (#{build_flavor})" if staged > 0
      end

      # dep_name => { pod_name => pod_info } for shared SPM deps consumed by enabled prebuilt pods in this install.
      def collect_shared_spm_deps(installer)
        by_dep = {}
        installer.pod_targets.each do |pod_target|
          info = pod_lookup_map[pod_target.name]
          next unless info && has_prebuilt_xcframework?(pod_target.name)
          (info[:spm_dependency_frameworks] || []).each do |dep_name|
            (by_dep[dep_name] ||= {})[pod_target.name] = info
          end
        end
        by_dep
      end

      # ──────────────────────────────────────────────────────────────────────
      # Cache management
      # ──────────────────────────────────────────────────────────────────────

      # Clears CocoaPods caches for precompiled pods to ensure specs are re-fetched
      # and patched on every `pod install`. Without this, incremental installs reuse
      # stale unpatched specs from `Pods/Local Podspecs/` and the external download
      # cache, causing precompiled pods to fall back to source builds.
      def clear_cocoapods_cache
        return unless enabled?

        cache_root = File.join(Dir.home, 'Library', 'Caches', 'CocoaPods', 'Pods', 'External')
        pods_root = Pod::Config.instance.sandbox_root rescue nil
        local_podspecs_dir = pods_root ? File.join(pods_root, 'Local Podspecs') : nil

        pod_lookup_map.each_key do |pod_name|
          next unless has_prebuilt_xcframework?(pod_name)

          # Clear the external download cache
          if cache_root && File.directory?(cache_root)
            cache_dir = File.join(cache_root, pod_name)
            FileUtils.rm_rf(cache_dir) if File.directory?(cache_dir)
          end

          # Clear cached podspecs so store_podspec is called again on the next install,
          # allowing the spec to be patched for precompiled xcframework usage.
          if local_podspecs_dir && File.directory?(local_podspecs_dir)
            cached_spec = File.join(local_podspecs_dir, "#{pod_name}.podspec.json")
            FileUtils.rm_f(cached_spec) if File.exist?(cached_spec)
          end

          # Clear the pod's installed directory so CocoaPods re-downloads from the
          # patched spec's source tarball instead of reusing stale source-build artifacts.
          if pods_root
            pod_dir = File.join(pods_root, pod_name)
            if File.directory?(pod_dir)
              product_name = pod_lookup_map[pod_name]&.dig(:product_name) || pod_name
              xcfw_info = File.join(pod_dir, "#{product_name}.xcframework", 'Info.plist')
              unless File.exist?(xcfw_info)
                FileUtils.rm_rf(pod_dir)
              end
            end
          end
        end
      end

      # ──────────────────────────────────────────────────────────────────────
      # Query methods
      # ──────────────────────────────────────────────────────────────────────

      # Checks whether a prebuilt XCFramework tarball exists for the given pod.
      # Used by autolinking_manager to decide between :podspec and :path registration.
      #
      # @param pod_name [String] The pod name to check
      # @return [Boolean] true if a prebuilt tarball exists in the build output
      def has_prebuilt_xcframework?(pod_name)
        return false unless enabled?

        resolve_prebuilt_status(pod_name)[:available]
      end

      # Returns whether test specs should be included for a pod.
      # Prebuilt pods don't contain test files, so test specs must be skipped.
      #
      # @param pod_name [String] The pod name to check
      # @return [Boolean] true if test specs should be included
      def should_include_test_specs?(pod_name)
        !has_prebuilt_xcframework?(pod_name)
      end

      # Checks whether a pod should be stubbed because it is bundled inside a prebuilt
      # xcframework. When stubbed, the pod keeps its headers (so dependents can compile)
      # but has no implementation files (the symbols come from the xcframework).
      #
      # @param name [String] The pod name
      # @return [Boolean] true if this pod is bundled in a prebuilt xcframework
      def bundled_dependency?(name)
        return false unless enabled?
        root_name = name.split('/').first
        bundled = all_bundled_frameworks
        bundled.include?(name) || bundled.include?(root_name)
      end

      # Checks whether a podspec should be auto-patched for precompiled module support.
      # Returns true if the pod has a prebuilt xcframework AND the spec hasn't already
      # been configured by an inline try_link_with_prebuilt_xcframework call.
      #
      # @param name [String] The pod name
      # @param spec [Pod::Specification] The evaluated podspec
      # @return [Boolean] true if the spec should be auto-patched
      def should_auto_patch_spec?(name, spec)
        return false unless enabled?
        return false unless has_prebuilt_xcframework?(name)

        vendored = spec.attributes_hash['vendored_frameworks']
        if vendored
          frameworks = vendored.is_a?(Array) ? vendored : [vendored]
          return false if frameworks.any? { |f| f.to_s.include?('.xcframework') }
        end

        true
      end

      # Returns true if the pod target vendors .xcframework files.
      # These pods are already precompiled — CocoaPods doesn't need to wrap them in a framework.
      def has_vendored_xcframeworks?(pod_target)
        vendored = pod_target.root_spec.attributes_hash['vendored_frameworks']
        return false unless vendored
        frameworks = vendored.is_a?(Array) ? vendored : [vendored]
        frameworks.any? { |f| f.to_s.include?('.xcframework') }
      end

      # Returns the linkage type if use_frameworks! is active, otherwise returns nil.
      # Checks both the USE_FRAMEWORKS env var and podfile properties (ios.useFrameworks).
      #
      # @param installer [Pod::Installer] The CocoaPods installer instance
      # @return [Symbol, nil] :dynamic, :static, or nil
      def linkage(installer)
        value = ENV["USE_FRAMEWORKS"]
        if value.nil?
          podfile_dir = File.dirname(installer.podfile.defined_in_file)
          props_path = File.join(podfile_dir, 'Podfile.properties.json')
          if File.exist?(props_path)
            value = JSON.parse(File.read(props_path))['ios.useFrameworks']
          end
        end
        return nil if value.nil?
        return :dynamic if value.downcase == 'dynamic'
        return :static if value.downcase == 'static'
        nil
      end

      # ──────────────────────────────────────────────────────────────────────
      # Pod registration (called from autolinking_manager.rb)
      # ──────────────────────────────────────────────────────────────────────

      # Returns the pod registration options hash for a given pod.
      # When a prebuilt xcframework exists, returns :podspec options so CocoaPods
      # respects spec.source and extracts the tarball. Otherwise returns :path options.
      #
      # @param pod [Expo::PackagePod] The pod to register
      # @param project_directory [Pathname] The project root for computing relative paths
      # @param debug_configurations [Array<String>] Debug configuration names
      # @param package [Expo::Package] The package containing the pod
      # @param global_flags [Hash] Global flags to merge into pod options
      # @return [Hash] Pod options hash suitable for passing to podfile.pod
      def pod_registration_options(pod, project_directory, debug_configurations, package, global_flags)
        configuration = package.debugOnly ? debug_configurations : []

        if has_prebuilt_xcframework?(pod.pod_name)
          podspec_file_path = Pathname.new(pod.podspec_dir)
            .relative_path_from(project_directory)
            .join("#{pod.pod_name}.podspec").to_path
          { :podspec => podspec_file_path, :configuration => configuration }.merge(global_flags, package.flags)
        else
          podspec_dir_path = Pathname.new(pod.podspec_dir).relative_path_from(project_directory).to_path
          { :path => podspec_dir_path, :configuration => configuration }.merge(global_flags, package.flags)
        end
      end

      # Registers external (3rd-party) prebuilt pods with :podspec BEFORE RN CLI's
      # use_native_modules! runs. RN CLI always uses :path which makes CocoaPods ignore
      # spec.source. By registering here first, RN CLI will skip these pods (it checks
      # for existing dependencies), and CocoaPods will respect the spec.source tarball URL.
      #
      # @param podfile [Pod::Podfile] The podfile to register pods in
      # @param target_definition [Pod::Podfile::TargetDefinition] The current target definition
      # @param project_directory [Pathname] The project root for computing relative paths
      def register_external_pods(podfile, target_definition, project_directory)
        external_prebuilt_pods(project_directory).each do |ext_pod|
          next if target_definition.dependencies.any? { |dep| dep.name == ext_pod[:pod_name] }

          Pod::UI.message "— #{ext_pod[:pod_name].green} (prebuilt xcframework)"
          podfile.pod(ext_pod[:pod_name], :podspec => ext_pod[:podspec_path])
        end
      end

      # Registers companion pods gated by a Podfile property or resolved dependency.
      # A product can declare `autolinkWhen` in its spm.config.json to opt into this flow.
      # The pod is auto-registered when:
      #   1. The podspec exists (source build) or prebuilt xcframework exists (precompiled)
      #   2. The gating Podfile.properties.json value is not the disabled value, or
      #      the gating dependency is present in the resolved dependency graph
      #   3. It's not already registered in the Podfile
      #   4. All of its local dependencies (pods in the lookup map) are already registered
      #
      # Works for both precompiled and source builds. For precompiled builds, the
      # podspec is patched to use the xcframework. For source builds, CocoaPods
      # builds from source via :podspec.
      #
      # Companion pods are production-only code (they never declare test specs) and
      # typically depend on their sibling main pod. When the Podfile calls
      # `use_expo_modules_tests!` (tests_only), main pods without test specs are skipped,
      # so registering a companion that depends on a skipped main pod would fail
      # dependency resolution. Skip companions entirely in tests-only mode.
      #
      # Example spm.config.json:
      #   "autolinkWhen": {
      #     "podfileProperty": "expo.camera.barcode-scanner-enabled",
      #     "disabledValue": "false"
      #   }
      #   "autolinkWhen": {
      #     "podName": "RNWorklets"
      #   }
      def register_companion_pods(podfile, target_definition, project_directory, tests_only: false)
        return if tests_only

        properties = read_podfile_properties(project_directory)

        pod_lookup_map.each do |pod_name, info|
          condition = info[:autolink_when]
          next unless condition
          next if target_definition.dependencies.any? { |dep| dep.name == pod_name }
          next unless companion_autolink_condition_met?(condition, properties)

          podspec_file = File.join(info[:podspec_dir], "#{pod_name}.podspec")
          unless File.exist?(podspec_file)
            Pod::UI.warn "[Expo] Companion pod #{pod_name}: podspec not found at #{podspec_file}"
            next
          end

          podspec_rel = Pathname.new(podspec_file).relative_path_from(project_directory).to_s

          # Parse the companion podspec to inspect its dependencies.
          begin
            spec = Pod::Specification.from_file(podspec_file)
          rescue => e
            Pod::UI.warn "[Expo] Companion pod #{pod_name}: failed to parse podspec: #{e.message}"
            next
          end

          # Skip companion pods whose local dependencies (sibling pods from the same
          # monorepo / node_modules) aren't registered in the Podfile. For example,
          # ExpoCameraBarcodeScanning depends on ExpoCamera — if expo-camera isn't
          # installed in the project, ExpoCamera won't be in the Podfile and CocoaPods
          # would fail with "Unable to find a specification for ExpoCamera".
          registered_pod_names = target_definition.dependencies.map(&:name)
          missing_local_dep = spec.all_dependencies.find do |dep|
            root_spec_name = dep.name.partition('/').first
            dep_info = pod_lookup_map[root_spec_name]
            dep_info && dep_info[:type] == :internal && !registered_pod_names.include?(root_spec_name)
          end
          if missing_local_dep
            Pod::UI.message "[Expo] Skipping companion pod #{pod_name}: dependency #{missing_local_dep.name} is not installed"
            next
          end

          # Enable modular headers for the companion pod's transitive Objective-C dependencies so
          # the Swift pod can `import` them. Mirrors the logic in autolinking_manager.rb's
          # `use_modular_headers_for_dependencies`.
          spec.all_dependencies.each do |dep|
            root_spec_name = dep.name.partition('/').first
            unless target_definition.build_pod_as_module?(root_spec_name)
              target_definition.set_use_modular_headers_for_pod(root_spec_name, true)
            end
          end

          condition_label = companion_autolink_condition_label(condition)

          if enabled? && has_prebuilt_xcframework?(pod_name)
            Pod::UI.message "— #{pod_name.green} (prebuilt companion, gated by #{condition_label})"
            podfile.pod(pod_name, :podspec => podspec_rel)
          else
            Pod::UI.message "— #{pod_name.green} (companion, gated by #{condition_label})"
            podspec_dir_rel = Pathname.new(info[:podspec_dir]).relative_path_from(project_directory).to_s
            podfile.pod(pod_name, :path => podspec_dir_rel)
          end
        end
      end

      # Reads Podfile.properties.json from the Podfile's directory (installation root).
      # Returns an empty hash if the file doesn't exist or fails to parse.
      def read_podfile_properties(_project_directory)
        props_path = File.join(Pod::Config.instance.installation_root.to_s, 'Podfile.properties.json')
        return {} unless File.exist?(props_path)
        JSON.parse(File.read(props_path)) rescue {}
      end

      def companion_autolink_condition_met?(condition, properties)
        pod_name = condition['podName']
        return pod_lookup_map.key?(pod_name) if pod_name

        npm_package = condition['npmPackage']
        return react_native_config.dig('dependencies', npm_package) != nil if npm_package

        property = condition['podfileProperty']
        return false unless property

        # Only skip if the property is explicitly set to the disabled value.
        properties[property] != condition['disabledValue']
      end

      def companion_autolink_condition_label(condition)
        condition['podName'] || condition['npmPackage'] || condition['podfileProperty']
      end

      # ──────────────────────────────────────────────────────────────────────
      # Spec patching (called from sandbox.rb / podspecs)
      # ──────────────────────────────────────────────────────────────────────

      # Links a pod spec with a prebuilt XCFramework.
      #
      # NOTE: Pods in this repo are auto-patched in store_podspec → patch_spec_for_prebuilt.
      # external-configs/ios/README.md documents this method for external packages.
      #
      # Sets spec.source to the local tarball so CocoaPods extracts it into Pods/<PodName>/.
      # Adds a prepare_command to copy both flavor tarballs into artifacts/.
      # Adds script phases for debug/release switching at build time.
      #
      # @param spec [Pod::Spec] The podspec to link with a prebuilt framework
      # @return [Boolean] true if a prebuilt framework was linked, false otherwise
      def try_link_with_prebuilt_xcframework(spec)
        return false unless enabled?

        resolution = resolve_prebuilt_status(spec.name)
        unless resolution[:available]
          log_linking_status(spec.name, false, resolution)
          return false
        end

        pod_info, product_name, default_tarball = resolution[:resolved]

        log_linking_status(spec.name, true, default_tarball)

        spec.source = { :http => local_file_uri(default_tarball), :flatten => false }
        spec.vendored_frameworks = build_vendored_paths(product_name, pod_info, spec.name)

        extra_fw_paths = framework_search_paths_for_skipped_deps(spec.name, pod_info)
        if extra_fw_paths.any?
          spec.pod_target_xcconfig ||= {}
          existing = spec.pod_target_xcconfig['FRAMEWORK_SEARCH_PATHS'] || '$(inherited)'
          spec.pod_target_xcconfig['FRAMEWORK_SEARCH_PATHS'] = ([existing] + extra_fw_paths).join(' ')
        end

        strip_bundled_deps_from_spec(spec, pod_info)

        spec.prepare_command = prepare_command_script(product_name, pod_info[:build_output_dir])
        add_script_phases(spec, product_name, pod_info)

        true
      end

      # Takes a fully-evaluated podspec (with source-build attributes set),
      # converts it to JSON, patches it for precompiled xcframework usage,
      # and returns a new Pod::Specification.
      #
      # @param spec [Pod::Specification] The podspec to patch
      # @return [Pod::Specification] A new patched specification (or original on failure)
      def patch_spec_for_prebuilt(spec)
        resolution = resolve_prebuilt_status(spec.name)
        unless resolution[:available]
          log_linking_status(spec.name, false, resolution) if CASCADED_UNAVAILABLE_REASONS.include?(resolution[:reason])
          return spec
        end

        pod_info, product_name, default_tarball = resolution[:resolved]

        log_linking_status(spec.name, true, default_tarball)

        spec_json = JSON.parse(spec.to_pretty_json)

        # Override source to local tarball
        spec_json['source'] = { 'http' => local_file_uri(default_tarball), 'flatten' => false }
        spec_json['vendored_frameworks'] = build_vendored_paths(product_name, pod_info, spec.name)

        # Clear source-build attributes
        %w[source_files exclude_files static_framework header_dir
           header_mappings_dir private_header_files compiler_flags].each do |attr|
          spec_json.delete(attr)
        end

        # Clear platform-specific source attributes
        clear_platform_source_attributes(spec_json)

        # Remove subspecs and testspecs (source file groupings / test files not in tarball)
        spec_json.delete('subspecs')
        spec_json.delete('testspecs')

        strip_bundled_deps_from_json(spec_json, pod_info, spec.name)

        spec_json['prepare_command'] = prepare_command_script(product_name, pod_info[:build_output_dir])
        spec_json['script_phases'] = build_script_phases_json(spec.name, product_name, pod_info)

        # Ensure DEFINES_MODULE is set
        spec_json['pod_target_xcconfig'] ||= {}
        spec_json['pod_target_xcconfig']['DEFINES_MODULE'] = 'YES'

        # Add framework search paths for shared SPM deps owned by another prebuilt pod
        extra_fw_paths = framework_search_paths_for_skipped_deps(spec.name, pod_info)
        if extra_fw_paths.any?
          existing = spec_json['pod_target_xcconfig']['FRAMEWORK_SEARCH_PATHS'] || '$(inherited)'
          spec_json['pod_target_xcconfig']['FRAMEWORK_SEARCH_PATHS'] = ([existing] + extra_fw_paths).join(' ')
        end

        Pod::Specification.from_json(spec_json.to_json)
      end

      # Patches a podspec to be header-only, removing implementation files.
      # The pod's headers remain available so dependent pods can still compile,
      # but no object files are produced — the symbols live in the prebuilt xcframework.
      #
      # @param spec [Pod::Specification] The podspec to stub
      # @return [Pod::Specification] A new header-only specification
      def stub_bundled_pod(spec)
        spec_json = JSON.parse(spec.to_pretty_json)

        Pod::UI.puts "#{'[Expo-precompiled] '.blue}Stubbing '#{spec.name}' — bundled in prebuilt xcframework"

        stub_source_files_to_headers(spec_json)

        (spec_json['subspecs'] || []).each do |subspec|
          stub_source_files_to_headers(subspec)
        end

        Pod::Specification.from_json(spec_json.to_json)
      end

      # Prints a consolidated summary of all precompiled module linking results.
      def print_linking_summary
        return unless @linked_pods&.any?

        prefix = "[Expo-precompiled] ".blue
        Pod::UI.info "#{prefix}Precompiled modules:"
        @linked_pods.sort_by { |name, _| name.downcase }.each do |pod_name, info|
          version = installed_version_for(pod_name)
          version_suffix = version ? " #{"(#{version})".dark}" : ""
          if info[:found]
            Pod::UI.info "#{prefix}  📦 #{pod_name.green}#{version_suffix}"
          else
            reason = format_prebuilt_unavailable_reason(info)
            Pod::UI.info "#{prefix}  ⚠️  #{pod_name}#{version_suffix} #{"(#{reason})".dark}"
          end
          spm_versions = pod_lookup_map.dig(pod_name, :spm_dependency_versions) || {}
          info[:spm_deps].each do |dep_name|
            dep_version = spm_versions[dep_name]
            dep_suffix = dep_version ? " #{"(#{dep_version})".dark}" : ""
            Pod::UI.info "#{prefix}      ∟ #{"#{dep_name}.xcframework".green}#{dep_suffix}"
          end
        end

        if @linked_pods.none? { |_, info| info[:found] }
          Pod::UI.warn "#{prefix}⚠️  Precompiled modules enabled but no xcframeworks found. All modules will build from source."
        end
      end

      # Returns the installed version for a pod by reading its package.json, or nil.
      def installed_version_for(pod_name)
        package_root = pod_lookup_map.dig(pod_name, :package_root)
        return nil unless package_root

        pkg_json = File.join(package_root, 'package.json')
        return nil unless File.exist?(pkg_json)

        JSON.parse(File.read(pkg_json))['version']
      rescue JSON::ParserError, Errno::ENOENT
        nil
      end

      # ──────────────────────────────────────────────────────────────────────
      # Post-install configuration steps
      # ──────────────────────────────────────────────────────────────────────

      # Copies flavor tarballs into Pods/<PodName>/artifacts/ for all precompiled pods.
      # Called from post_install which runs reliably on every pod install, unlike
      # prepare_command which CocoaPods skips for "unchanged" pods.
      #
      # @param installer [Pod::Installer] The CocoaPods installer instance
      def ensure_artifacts(installer)
        return unless enabled?

        pods_root = installer.sandbox.root

        pod_lookup_map.each do |pod_name, info|
          next unless has_prebuilt_xcframework?(pod_name)

          product_name = info[:product_name] || pod_name
          build_output_dir = info[:build_output_dir]
          pod_dir = File.join(pods_root, pod_name)

          next unless File.directory?(pod_dir)

          artifacts_dir = File.join(pod_dir, ARTIFACTS_DIR_NAME)
          FileUtils.mkdir_p(artifacts_dir)

          # Copy both flavor tarballs
          ['debug', 'release'].each do |flavor|
            src = resolve_prebuilt_tarball(info, product_name, flavor, pod_name)
            dst = File.join(artifacts_dir, "#{product_name}-#{flavor}.tar.gz")
            FileUtils.cp(src, dst) if File.exist?(src) && !File.exist?(dst)
          end

          # Write initial .last_build_configuration if missing
          last_config_file = File.join(artifacts_dir, '.last_build_configuration')
          File.write(last_config_file, build_flavor) unless File.exist?(last_config_file)

          # Self-healing: extract xcframework if missing (CocoaPods cache issue)
          xcframework_dir = File.join(pod_dir, "#{product_name}.xcframework")
          unless File.directory?(xcframework_dir)
            tarball = resolve_prebuilt_tarball(info, product_name, build_flavor, pod_name)
            if File.exist?(tarball)
              Pod::UI.info "#{'[Expo-precompiled] '.blue}Extracting #{product_name}.xcframework (cache miss)"
              system("tar", "xzf", tarball, "-C", pod_dir)
            end
          end
        end
      end

      # Prevents swiftinterface verification failures when BUILD_LIBRARY_FOR_DISTRIBUTION=YES
      # is propagated from brownfield/framework user targets to pod targets by CocoaPods 1.16+.
      def disable_swift_interface_verification(installer)
        return unless prebuilt_react_active?

        Pod::UI.puts "[Expo] ".blue + "Disabling SWIFT_EMIT_MODULE_INTERFACE for pod targets (prebuilt React compatibility)"

        installer.pod_targets.each do |pod_target|
          pod_target.build_settings.each do |config_name, _|
            xcconfig_path = pod_target.xcconfig_path(config_name)
            next unless File.exist?(xcconfig_path)

            content = File.read(xcconfig_path)
            next if content.include?('SWIFT_EMIT_MODULE_INTERFACE')

            File.open(xcconfig_path, 'a') do |f|
              f.puts 'SWIFT_EMIT_MODULE_INTERFACE = NO'
            end
          end
        end
      end

      # Mirrors React Native's rncore.rb add_prebuilt_header_search_paths for the pods RN's own loop
      # misses (it only covers the React-* pod targets, not the Expo pods). Re-applies the flattened
      # ReactNativeHeaders module map + header search path idempotently, skipping any xcconfig that
      # already carries the flag (those RN already covered).
      #
      # Gated on the module map actually existing: the Maven prebuilt path (RCT_USE_PREBUILT_RNCORE
      # without RCT_TESTONLY_RNCORE_TARBALL_PATH) can install a React-Core-prebuilt that does not ship
      # Headers/module.modulemap. Pointing -fmodule-map-file at a missing file fails `ScanDependencies`
      # ("module map file ... not found"), so when it is absent we inject nothing and warn — the
      # faithful path is a tarball that ships ReactNativeHeaders via RCT_TESTONLY_RNCORE_TARBALL_PATH.
      #
      # The absence of the pod itself is a different case and must stay silent. prebuilt_react_active?
      # reads RCT_USE_PREBUILT_RNCORE as "prebuilt unless explicitly 0", while React Native's own
      # rncore.rb requires an explicit "1"; with the variable unset RN builds React from source and
      # never installs React-Core-prebuilt. There is nothing to extend in that sandbox, so warning
      # about a missing module map would be noise on a perfectly good source build.
      def ensure_modular_react_header_flags(installer)
        return unless prebuilt_react_active?

        react_prebuilt_dir = File.join(installer.sandbox.root, 'React-Core-prebuilt')
        return unless Dir.exist?(react_prebuilt_dir)

        module_map_file = File.join(react_prebuilt_dir, 'Headers', 'module.modulemap')
        unless File.exist?(module_map_file)
          Pod::UI.warn "[Expo] Prebuilt React-Core-prebuilt is missing Headers/module.modulemap — " \
            "skipping Expo module-map coverage. If the build fails with a missing module map or " \
            "-Wnon-modular-include, the installed prebuilt React does not match React Native's " \
            "CocoaPods scripts; install a tarball that ships ReactNativeHeaders via " \
            "RCT_TESTONLY_RNCORE_TARBALL_PATH."
          return
        end

        module_map = '$(PODS_ROOT)/React-Core-prebuilt/Headers/module.modulemap'
        header_path = '"$(PODS_ROOT)/React-Core-prebuilt/Headers"'
        # Quoted exactly as RN's rncore.rb writes it, for two reasons: a $(PODS_ROOT) containing
        # spaces has to stay a single clang argument, and the already-present checks below only
        # recognise RN's own injection — and skip re-adding it — if the spelling matches.
        cflags_flag = %("-fmodule-map-file=#{module_map}")
        swift_flag = "-Xcc #{cflags_flag}"
        umbrella_flag = '-Xcc -Wno-incomplete-umbrella'

        patched = 0
        Dir.glob(File.join(installer.sandbox.root, 'Target Support Files', '**', '*.xcconfig')).each do |xcconfig_path|
          content = File.read(xcconfig_path)
          original = content.dup

          # Each flag is ensured INDEPENDENTLY (not "skip the pod if the module-map flag is present").
          # A pod can carry the -fmodule-map-file flag from its own podspec (e.g. react-native-reanimated
          # 4.x adds it) yet still lack the flattened-headers search path — in which case the module map
          # activates the yoga/react modules but <yoga/style/Style.h> & co. textually fail to resolve
          # (the modules' headers live under React-Core-prebuilt/Headers/). Add whichever piece is absent.
          #
          # OTHER_CPLUSPLUSFLAGS needs its own copy: Xcode does not fold OTHER_CFLAGS into it, so once a
          # target sets it (RN's new_architecture.rb does, for -DRCT_NEW_ARCH_ENABLED) that value replaces
          # OTHER_CFLAGS for every .mm/.cpp/.cc translation unit. Without it the module map never reaches
          # the C++ sources that consume the relocated react/ and yoga/ namespaces.
          content = append_xcconfig_flag(content, 'HEADER_SEARCH_PATHS', header_path)
          content = append_xcconfig_flag(content, 'OTHER_CFLAGS', cflags_flag)
          content = append_xcconfig_flag(content, 'OTHER_CPLUSPLUSFLAGS', cflags_flag)
          content = append_xcconfig_flag(content, 'OTHER_SWIFT_FLAGS', umbrella_flag)
          content = append_xcconfig_flag(content, 'OTHER_SWIFT_FLAGS', swift_flag)

          next if content == original
          File.write(xcconfig_path, content)
          patched += 1
        end

        Pod::UI.puts "[Expo] ".blue + "Ensured modular React header flags on #{patched} xcconfig(s)"
      end

      # Re-quote unquoted `.../Swift Compatibility Header` entries in HEADER_SEARCH_PATHS. The path
      # has a space, and CocoaPods drops the podspec's quotes when it's supplied via a joined
      # `pod_target_xcconfig` string, so clang space-splits it and a cross-pod `#import
      # "<Pod>-Swift.h"` fails in the static-library source build (no framework bundle to fall back
      # on). Runs on the final xcconfigs; RN's post-install preserves quotes, so this stays
      # authoritative. Idempotent (already-quoted tokens are skipped).
      def quote_swift_compatibility_header_search_paths(installer)
        # $(…)/${…}PODS_CONFIGURATION_BUILD_DIR / <pod-name> / "Swift Compatibility Header", unquoted only.
        token = /(?<!")(\$[({]PODS_CONFIGURATION_BUILD_DIR[)}]\/[^\s"\/]+\/Swift Compatibility Header)(?!")/
        patched = 0
        Dir.glob(File.join(installer.sandbox.root, 'Target Support Files', '**', '*.xcconfig')).each do |xcconfig_path|
          content = File.read(xcconfig_path)
          new_content = content.gsub(/^HEADER_SEARCH_PATHS\s*=.*$/) { |line| line.gsub(token, '"\1"') }
          next if new_content == content
          File.write(xcconfig_path, new_content)
          patched += 1
        end
        Pod::UI.puts "[Expo] ".blue + "Quoted Swift compatibility header search paths in #{patched} xcconfig(s)" if patched > 0
      end

      # Appends `value` to an xcconfig `key` line (preserving $(inherited)), or adds the key if absent.
      # No-ops when `key` already carries `value`.
      #
      # The already-present check is scoped to `key`'s own line, not the whole file: the same flag
      # legitimately belongs on several keys (OTHER_CFLAGS and OTHER_CPLUSPLUSFLAGS both need the
      # module map), so a file-wide check would let whichever key is written first silently suppress
      # every later one.
      def append_xcconfig_flag(content, key, value)
        line = /^(#{Regexp.escape(key)}\s*=.*)$/
        existing = content[line, 1]
        return content if existing&.include?(value)
        return content.sub(line) { "#{$1} #{value}" } if existing

        (content.end_with?("\n") ? content : content + "\n") + "#{key} = $(inherited) #{value}\n"
      end

      # CocoaPods shell-splits `pod_target_xcconfig` search paths, dropping the quotes
      # around entries that contain spaces. `.../Swift Compatibility Header` then lands
      # in the generated pod xcconfigs as three broken -I flags, so a source-built Swift
      # pod's dependents can't find its generated ObjC compatibility header (e.g. the
      # Expo pod importing ExpoModulesCore-Swift.h). Re-quote those entries after
      # CocoaPods writes the xcconfigs. Aggregate (user-target) xcconfigs keep their
      # quotes and are left untouched by the negative-lookaround guards.
      def requote_swift_compat_header_paths(installer)
        Dir.glob(File.join(installer.sandbox.root, 'Target Support Files', '**', '*.xcconfig')).each do |xcconfig_path|
          content = File.read(xcconfig_path)
          fixed = content.gsub(%r{(?<!")(\$[({]PODS_CONFIGURATION_BUILD_DIR[)}]/[^ "\n]+/Swift Compatibility Header)(?!")}, '"\1"')
          File.write(xcconfig_path, fixed) if fixed != content
        end
      end

      # TODO(ExpoModulesJSI-xcframework): Remove this method when ExpoModulesJSI.xcframework
      # is built and distributed separately. At that point, pods can depend on ExpoModulesJSI
      # directly and this header search path workaround won't be needed.
      #
      # Configures header search paths for prebuilt XCFrameworks in the post_install phase.
      # When using prebuilt modules, ExpoModulesJSI headers are bundled inside
      # ExpoModulesCore.xcframework. This method adds the necessary header search paths
      # to all pod targets so that `#import <ExpoModulesJSI/...>` works correctly.
      #
      # @param installer [Pod::Installer] The CocoaPods installer instance
      def configure_header_search_paths(installer)
        return unless enabled?

        expo_core_xcframework = find_expo_modules_core_xcframework(installer)
        return unless expo_core_xcframework

        header_search_paths = collect_xcframework_header_paths(expo_core_xcframework, 'ExpoModulesCore')
        return if header_search_paths.empty?

        paths_string = header_search_paths.map { |p| "\"#{p}\"" }.join(' ')

        Pod::UI.info "#{'[Expo-precompiled] '.blue}Adding ExpoModulesJSI header search paths to all targets"

        # Modify xcconfig files directly - these take precedence over Xcode project settings
        target_support_files_dir = File.join(installer.sandbox.root, 'Target Support Files')
        Dir.glob(File.join(target_support_files_dir, '**', '*.xcconfig')).each do |xcconfig_path|
          update_xcconfig_header_search_paths(xcconfig_path, paths_string)
        end

        # Also update the main project targets' build settings directly
        installer.pods_project.targets.each do |target|
          target.build_configurations.each do |config|
            existing = config.build_settings['HEADER_SEARCH_PATHS'] || '$(inherited)'
            existing = existing.join(' ') if existing.is_a?(Array)
            unless existing.include?(paths_string)
              config.build_settings['HEADER_SEARCH_PATHS'] = "#{existing} #{paths_string}"
            end
          end
        end
      end

      # Lets a source-built pod include headers from its prebuilt dependencies, which
      # exist only inside the xcframework and never in `Pods/Headers/Public`.
      #
      # @param installer [Pod::Installer] The CocoaPods installer instance
      def configure_prebuilt_dependency_header_search_paths(installer)
        return unless enabled?

        installer.pod_targets.each do |pod_target|
          next if has_prebuilt_xcframework?(pod_target.pod_name)

          prebuilt_dependencies = pod_target.dependent_targets.map(&:pod_name).uniq.sort.select do |dep_name|
            !GLOBALLY_INJECTED_PREBUILT_PODS.include?(dep_name) && has_prebuilt_xcframework?(dep_name)
          end
          next if prebuilt_dependencies.empty?

          header_search_paths = prebuilt_dependencies.flat_map do |dep_name|
            prebuilt_xcframework_header_paths(installer, dep_name)
          end
          next if header_search_paths.empty?

          paths_string = header_search_paths.map { |p| "\"#{p}\"" }.join(' ')
          Pod::UI.info "#{'[Expo-precompiled] '.blue}Adding #{prebuilt_dependencies.join(', ')} header search paths to #{pod_target.pod_name}"

          pod_target.build_settings.each_key do |config_name|
            xcconfig_path = pod_target.xcconfig_path(config_name)
            update_xcconfig_header_search_paths(xcconfig_path, paths_string) if File.exist?(xcconfig_path)
          end
        end
      end

      # Configures the ReactCodegen target to properly handle prebuilt modules.
      # Removes source file references for prebuilt libraries from the compile sources phase
      # and adds a shell script build phase to clean up regenerated codegen files.
      def configure_codegen_for_prebuilt_modules(installer)
        return unless enabled?

        script_phase_name = '[Expo] Remove duplicate codegen output'
        react_codegen_target = installer.pods_project.targets.find { |target| target.name == 'ReactCodegen' }

        unless react_codegen_target
          Pod::UI.puts "[Expo] ".yellow + "ReactCodegen target not found in pods project"
          return
        end

        already_exists = react_codegen_target.build_phases.any? do |phase|
          phase.is_a?(Xcodeproj::Project::Object::PBXShellScriptBuildPhase) && phase.name == script_phase_name
        end

        codegen_exclusions = codegen_exclusion_list(installer.pod_targets)

        if codegen_exclusions.any?
          Pod::UI.puts "[Expo] ".blue + "Will remove codegen output for prebuilt libraries: #{codegen_exclusions.join(', ')}"
          remove_codegen_sources_from_compile_phase(react_codegen_target, codegen_exclusions)
        end

        unless already_exists
          Pod::UI.puts "[Expo] ".blue + "Adding '#{script_phase_name}' build phase to ReactCodegen"
          add_codegen_cleanup_script_phase(react_codegen_target, script_phase_name, codegen_exclusions)
          installer.pods_project.save
        end
      end

      # Removes implementation files from compile phases of pod targets that are bundled
      # inside prebuilt xcframeworks. This handles CDN pods (like SDWebImage) that don't
      # go through the store_podspec hook.
      #
      # @param installer [Pod::Installer] The CocoaPods installer instance
      def stub_bundled_pod_targets(installer)
        return unless enabled?

        bundled = all_bundled_frameworks
        return if bundled.empty?

        stubbed_lib_names = Set.new

        installer.pods_project.targets.each do |target|
          target_root = target.name.split('-').first.split('/').first
          framework_name = [target.name, target_root].find { |name| bundled.include?(name) }
          next unless framework_name

          unless stub_bundled_pod_target?(installer, target_root, framework_name)
            Pod::UI.puts "#{'[Expo-precompiled] '.blue}Keeping '#{target.name}' built from source: no consumer links a prebuilt xcframework bundling it"
            next
          end

          compile_phase = target.build_phases.find { |p| p.is_a?(Xcodeproj::Project::Object::PBXSourcesBuildPhase) }
          next unless compile_phase

          files_removed = 0
          compile_phase.files.to_a.each do |build_file|
            file_ref = build_file.file_ref
            next unless file_ref

            path = file_ref.path.to_s
            if SOURCE_FILE_EXTENSIONS.any? { |ext| path.end_with?(ext) }
              compile_phase.files.delete(build_file)
              files_removed += 1
            end
          end

          if files_removed > 0
            stubbed_lib_names.add(target.name)
            Pod::UI.puts "#{'[Expo-precompiled] '.blue}Stubbed '#{target.name}': removed #{files_removed} source files from compile phase"
          end
        end

        if stubbed_lib_names.any?
          remove_linker_flags_for_stubbed_libs(installer, stubbed_lib_names)
        end

        installer.pods_project.save
      end

      # Returns the package_root for a given pod name, or nil if not found.
      def package_root_for(pod_name)
        pod_lookup_map[pod_name]&.dig(:package_root)
      end

      private

      # ──────────────────────────────────────────────────────────────────────
      # Helpers: common checks
      # ──────────────────────────────────────────────────────────────────────

      # Returns true when the prebuilt React.xcframework is in use.
      #
      # Must mirror React Native's default (`!= '0'`): `use_react_native!` defaults
      # `RCT_USE_PREBUILT_RNCORE` to "1" but runs after `use_expo_modules!`, so reading
      # `== '1'` here would see the value before React Native sets it.
      def prebuilt_react_active?
        ENV['RCT_USE_PREBUILT_RNCORE'] != '0'
      end

      # Builds a `file://` URI for a local filesystem path, percent-encoding
      # any non-ASCII characters so paths with Unicode segments (e.g. emoji or
      # accented characters) don't trip URI::File.build's RFC 3986 path
      # validation.
      def local_file_uri(path)
        URI::File.build(path: URI::DEFAULT_PARSER.escape(path)).to_s
      end

      # ──────────────────────────────────────────────────────────────────────
      # Helpers: spec patching
      # ──────────────────────────────────────────────────────────────────────

      # Clears platform-specific source attributes from a spec JSON hash.
      def clear_platform_source_attributes(spec_json)
        APPLE_PLATFORMS.each do |platform|
          next unless spec_json[platform].is_a?(Hash)
          %w[source_files exclude_files private_header_files
             header_dir header_mappings_dir compiler_flags vendored_frameworks].each do |attr|
            spec_json[platform].delete(attr)
          end
          spec_json.delete(platform) if spec_json[platform].empty?
        end
      end

      # Replaces source_files with header-only patterns in a spec or subspec JSON hash.
      def stub_source_files_to_headers(json)
        if json['source_files']
          json['source_files'] = header_only_pattern(json['source_files'])
        end

        APPLE_PLATFORMS.each do |platform|
          next unless json[platform].is_a?(Hash) && json[platform]['source_files']
          json[platform]['source_files'] = header_only_pattern(json[platform]['source_files'])
        end
      end

      # Converts source_files patterns to header-only patterns.
      #
      # @param patterns [String, Array<String>] Original source_files patterns
      # @return [Array<String>] Patterns matching only header files
      def header_only_pattern(patterns)
        patterns = [patterns] unless patterns.is_a?(Array)
        patterns.map do |p|
          p.gsub(/\.\{[^}]+\}/, '.{h,hpp}')
           .gsub(/\*\.(m|mm|swift|c|cpp)$/, '*.{h,hpp}')
        end.uniq
      end

      # Strips dependencies on SPM packages bundled in the xcframework from a spec JSON hash.
      #
      # @param spec_json [Hash] The podspec as a parsed JSON hash (modified in place)
      # @param pod_info [Hash] Package info from spm.config.json lookup
      # @param pod_name [String] Pod name for logging
      def strip_bundled_deps_from_json(spec_json, pod_info, pod_name)
        bundled = bundled_framework_set(pod_info)
        return if bundled.empty? || !spec_json['dependencies'].is_a?(Hash)

        strip_matching_dependencies(spec_json['dependencies'], bundled, pod_name)
        spec_json.delete('dependencies') if spec_json['dependencies'].empty?
      end

      # Strips dependencies on SPM packages bundled in the xcframework from a live spec object.
      #
      # NOTE: Pod::Specification doesn't expose a public API to remove dependencies,
      # so we modify the attributes_hash directly.
      #
      # @param spec [Pod::Specification] The podspec to modify
      # @param pod_info [Hash] Package info from spm.config.json lookup
      def strip_bundled_deps_from_spec(spec, pod_info)
        bundled = bundled_framework_set(pod_info)
        return if bundled.empty?

        deps = spec.attributes_hash['dependencies']
        return unless deps.is_a?(Hash)

        strip_matching_dependencies(deps, bundled, spec.name)
      end

      # Returns the set of bundled framework names from pod_info.
      def bundled_framework_set(pod_info)
        (pod_info[:spm_dependency_frameworks] || []).to_set
      end

      # Deletes dependencies whose name (or root name) matches the bundled set.
      def strip_matching_dependencies(deps_hash, bundled, pod_name)
        deps_hash.delete_if do |dep_name, _|
          root_name = dep_name.split('/').first
          if bundled.include?(dep_name) || bundled.include?(root_name)
            Pod::UI.puts "#{'[Expo-precompiled] '.blue}Stripping bundled dependency '#{dep_name}' from #{pod_name}"
            true
          else
            false
          end
        end
      end

      # Returns vendored_frameworks paths for a prebuilt pod: the product's own
      # xcframework plus any shared SPM deps this pod owns (first to claim wins;
      # non-owners get FRAMEWORK_SEARCH_PATHS instead). Shared dep entries are
      # symlinks staged by `ensure_shared_spm_deps` inside the owner's pod dir.
      def build_vendored_paths(product_name, pod_info, pod_name)
        @claimed_vendored_frameworks ||= Set.new
        @framework_owner_map ||= {}

        paths = ["#{product_name}.xcframework"]
        @claimed_vendored_frameworks.add(product_name)
        @framework_owner_map[product_name] = pod_name

        (pod_info[:spm_dependency_frameworks] || []).each do |dep_name|
          owner = (@framework_owner_map[dep_name] ||= pod_name)
          if owner == pod_name
            paths << "#{dep_name}.xcframework"
          else
            Pod::UI.puts "#{'[Expo-precompiled] '.blue}Skipping #{dep_name}.xcframework from #{pod_name} — already vendored by #{owner}"
          end
          log_spm_dependency(pod_name, dep_name)
        end
        paths
      end

      # FRAMEWORK_SEARCH_PATHS entries for shared SPM deps claimed by another pod.
      # CocoaPods slices each xcframework into `${PODS_XCFRAMEWORKS_BUILD_DIR}/<owner>/`,
      # which is where the linker resolves the framework.
      def framework_search_paths_for_skipped_deps(pod_name, pod_info)
        @framework_owner_map ||= {}
        owners = (pod_info[:spm_dependency_frameworks] || []).filter_map do |dep_name|
          owner = @framework_owner_map[dep_name]
          owner if owner && owner != pod_name
        end.uniq
        owners.flat_map { |owner| [%("${PODS_XCFRAMEWORKS_BUILD_DIR}/#{owner}"), %("${PODS_ROOT}/#{owner}")] }
      end

      # ──────────────────────────────────────────────────────────────────────
      # Helpers: script phases
      # ──────────────────────────────────────────────────────────────────────

      # Builds the switch and dSYM script phases as JSON-compatible hashes.
      #
      # @param spec_name [String] The pod name
      # @param product_name [String] The product/module name
      # @param pod_info [Hash] Package info from spm.config.json lookup
      # @return [Array<Hash>] Array of script phase hashes with string keys
      def build_script_phases_json(spec_name, product_name, pod_info)
        project_root = Pod::Config.instance.installation_root
        scripts_dir = __dir__
        switch_script_rel = Pathname.new(File.join(scripts_dir, 'replace-xcframework.js')).relative_path_from(project_root).to_s
        dsym_script_rel = Pathname.new(File.join(scripts_dir, 'resolve-dsym-sourcemaps.js')).relative_path_from(project_root).to_s
        package_root_rel = Pathname.new(pod_info[:package_root]).relative_path_from(project_root).to_s

        pods_parent = "$PODS_ROOT/.."
        switch_script_path = "#{pods_parent}/#{switch_script_rel}"
        dsym_script_path = "#{pods_parent}/#{dsym_script_rel}"
        xcframeworks_dir_var = "$PODS_ROOT/#{spec_name}"
        package_root_var = "#{pods_parent}/#{package_root_rel}"
        dsym_stamp = "$(DERIVED_FILE_DIR)/expo-dsym-resolve-#{product_name}-$(CONFIGURATION).stamp"

        shared_deps = shared_dep_switch_args(spec_name, pod_info)

        switch_phase = {
          'name' => "[Expo] Switch #{spec_name} XCFramework for build configuration",
          'execution_position' => 'before_compile',
          'input_files' => ["#{pods_parent}/#{switch_script_rel}"],
          'script' => xcframework_switch_script(product_name, xcframeworks_dir_var, switch_script_path, shared_deps),
        }

        if Gem::Version.new(Pod::VERSION) >= Gem::Version.new('1.13.0')
          switch_phase['always_out_of_date'] = '1'
        end

        dsym_phase = {
          'name' => "[Expo] Resolve #{spec_name} dSYM source maps",
          'execution_position' => 'before_compile',
          'input_files' => ["#{pods_parent}/#{dsym_script_rel}"],
          'output_files' => [dsym_stamp],
          'script' => dsym_resolve_script(product_name, xcframeworks_dir_var, dsym_script_path, pod_info[:npm_package], package_root_var),
        }

        [switch_phase, dsym_phase]
      end

      # Adds script phases to the podspec for xcframework switching and dSYM resolution.
      # Converts string keys to symbols (CocoaPods inline API uses symbols).
      def add_script_phases(spec, product_name, pod_info)
        json_phases = build_script_phases_json(spec.name, product_name, pod_info)
        spec.script_phases = json_phases.map do |phase|
          phase.each_with_object({}) do |(k, v), h|
            h[k.to_sym] = k == 'execution_position' ? v.to_sym : v
          end
        end
      end

      # Generates the prepare_command shell script.
      def prepare_command_script(product_name, build_output_dir)
        <<~SH
          # Self-healing: extract xcframework from tarball if CocoaPods cache was stale/empty
          if [ ! -d "#{product_name}.xcframework" ]; then
            TARBALL="#{build_output_dir}/#{build_flavor}/xcframeworks/#{product_name}.tar.gz"
            if [ -f "$TARBALL" ]; then
              echo "[Expo XCFramework] #{product_name}: Extracting xcframework from build output (cache miss)"
              tar xzf "$TARBALL"
            fi
          fi
        SH
      end

      # Shell script for the xcframework switch phase. With no shared deps the
      # script short-circuits in shell when the per-pod state file matches; with
      # shared deps Node is always invoked so each dep's symlink can be repointed
      # (it has its own per-dep state file inside replace-xcframework.js).
      def xcframework_switch_script(product_name, xcframeworks_dir, script_path, shared_deps = [])
        config_detect = <<~SH.chomp
          CONFIG="release"
          if echo "$GCC_PREPROCESSOR_DEFINITIONS" | grep -q "DEBUG=1"; then
            CONFIG="debug"
          fi
        SH

        if shared_deps.empty?
          <<~SH
            # Auto-generated by expo-modules-autolinking
            #{config_detect}
            LAST_CONFIG_FILE="#{xcframeworks_dir}/artifacts/.last_build_configuration"
            if [ -f "$LAST_CONFIG_FILE" ] && [ "$(cat "$LAST_CONFIG_FILE")" = "$CONFIG" ]; then
              exit 0
            fi
            . "$REACT_NATIVE_PATH/scripts/xcode/with-environment.sh"
            "$NODE_BINARY" "#{script_path}" -c "$CONFIG" -m "#{product_name}" -x "#{xcframeworks_dir}"
          SH
        else
          shared_args = shared_deps.map { |arg| "  #{arg}" }.join(" \\\n")
          <<~SH
            # Auto-generated by expo-modules-autolinking
            #{config_detect}
            . "$REACT_NATIVE_PATH/scripts/xcode/with-environment.sh"
            "$NODE_BINARY" "#{script_path}" \\
              -c "$CONFIG" \\
              -m "#{product_name}" \\
              -x "#{xcframeworks_dir}" \\
            #{shared_args}
          SH
        end
      end

      # '--shared "<Name>:<source_base>"' tokens for shared SPM deps this pod owns.
      # Non-owners reach the framework via FRAMEWORK_SEARCH_PATHS at link time.
      def shared_dep_switch_args(pod_name, pod_info)
        return [] unless pod_info && pod_info[:spm_dependency_frameworks]
        @framework_owner_map ||= {}
        pod_info[:spm_dependency_frameworks].filter_map do |dep_name|
          next nil unless @framework_owner_map[dep_name] == pod_name
          source_base = shared_spm_dep_source_base(dep_name, pod_info)
          next nil unless source_base
          %(--shared "#{dep_name}:#{source_base.gsub(/[\\"$`]/) { |c| "\\#{c}" }}")
        end
      end

      # Returns the shell script for the dSYM source map resolution phase.
      def dsym_resolve_script(product_name, xcframeworks_dir, script_path, npm_package, package_root)
        <<~SH
          # Resolve dSYM source path mappings for prebuilt xcframeworks
          # This script is auto-generated by expo-modules-autolinking
          #
          # Writes UUID plists into dSYMs so lldb can remap
          # /expo-src/... paths back to local package paths.

          STAMP_FILE="$DERIVED_FILE_DIR/expo-dsym-resolve-#{product_name}-$CONFIGURATION.stamp"

          # Find dSYMs inside the xcframework (all slices)
          XCFW_PATH="#{xcframeworks_dir}/#{product_name}.xcframework"

          if [ -d "$XCFW_PATH" ]; then
            FOUND_DSYM=0
            for DSYM_DIR in "$XCFW_PATH"/*/dSYMs; do
              if [ -d "$DSYM_DIR/#{product_name}.framework.dSYM" ]; then
                if [ $FOUND_DSYM -eq 0 ]; then
                  . "$REACT_NATIVE_PATH/scripts/xcode/with-environment.sh"
                  FOUND_DSYM=1
                fi
                "$NODE_BINARY" "#{script_path}" \\
                  -d "$DSYM_DIR" \\
                  -m "#{product_name}" \\
                  -n "#{npm_package}" \\
                  -r "#{package_root}"
              fi
            done
          fi

          # Touch stamp file for Xcode dependency tracking
          mkdir -p "$(dirname "$STAMP_FILE")"
          touch "$STAMP_FILE"
        SH
      end

      # ──────────────────────────────────────────────────────────────────────
      # Helpers: pod lookup map
      # ──────────────────────────────────────────────────────────────────────

      # Builds and caches a map from pod names to package information.
      # Scans all spm.config.json files in:
      #   - packages/*/spm.config.json (internal Expo packages)
      #   - external-configs/ios/*/spm.config.json (3rd-party packages, bundled with autolinking)
      #
      # @return [Hash] Map of podName -> { type:, npm_package:, podspec_dir:, build_output_dir:, ... }
      def pod_lookup_map
        return @pod_lookup_map if @pod_lookup_map

        @pod_lookup_map = {}
        repo_root = find_repo_root

        if repo_root
          scan_spm_configs(repo_root)
        else
          # Standalone project: discover spm.config.json from node_modules instead of packages/.
          # Prebuilds are resolved from EXPO_PRECOMPILED_MODULES_PATH if set,
          # otherwise from prebuilds/ bundled inside each package directory.
          project_root = File.dirname(Dir.pwd) # Dir.pwd is ios/ during pod install
          scan_node_modules_configs(project_root)
        end

        @pod_lookup_map
      end

      # Scans all spm.config.json files and populates @pod_lookup_map.
      # Used in monorepo context where find_repo_root succeeds.
      def scan_spm_configs(repo_root)
        # Internal Expo packages: packages/*/spm.config.json
        Dir.glob(File.join(repo_root, 'packages', '*', 'spm.config.json')).each do |config_path|
          process_spm_config(config_path, :internal, repo_root)
        end

        # External 3rd-party packages: bundled in external-configs/ios/
        scan_external_configs(repo_root)
      end

      # Locates spm.config.json for internal Expo modules in standalone projects
      # (no monorepo root). Uses resolved podspec dirs so non-flat layouts work.
      def scan_node_modules_configs(project_root)
        resolved_modules.each do |mod|
          podspec_dir = (mod['pods'] || []).map { |pod| pod['podspecDir'] }.compact.first
          next unless podspec_dir

          config_path = spm_config_path_for_podspec_dir(podspec_dir)
          next unless config_path

          process_spm_config(config_path, :internal, project_root)
        end

        scan_external_configs(project_root)
      end

      # Resolves spm.config.json from an Expo autolinking podspecDir. Most modules
      # report `<package>/ios`, while packages with root podspecs report `<package>`.
      def spm_config_path_for_podspec_dir(podspec_dir)
        [podspec_dir, File.dirname(podspec_dir)].uniq.each do |package_dir|
          config_path = File.join(package_dir, 'spm.config.json')
          return config_path if File.exist?(config_path)
        end

        nil
      end

      # Scans spm.config.json files from external-configs/ios/ for 3rd-party packages
      # (e.g. react-native-screens, react-native-svg) that don't ship their own spm.config.json.
      # Shared by both monorepo and standalone project paths.
      #
      # @param effective_root [String] The project or repo root (used to compute the default build output dir)
      def scan_external_configs(effective_root)
        external_configs_dir = File.join(__dir__, '..', '..', 'external-configs', 'ios')
        return unless File.directory?(external_configs_dir)

        # Non-scoped: external-configs/ios/*/spm.config.json
        Dir.glob(File.join(external_configs_dir, '*', 'spm.config.json')).each do |config_path|
          npm_package = File.basename(File.dirname(config_path))
          process_external_config(config_path, npm_package, effective_root)
        end

        # Scoped: external-configs/ios/@scope/*/spm.config.json
        Dir.glob(File.join(external_configs_dir, '@*', '*', 'spm.config.json')).each do |config_path|
          rel = config_path.sub("#{external_configs_dir}/", '')
          npm_package = File.dirname(rel) # e.g. "@shopify/react-native-skia"
          process_external_config(config_path, npm_package, effective_root)
        end
      end

      # Processes a single external spm.config.json for a 3rd-party package.
      def process_external_config(config_path, npm_package, effective_root)
        config = JSON.parse(File.read(config_path))
        products = config['products'] || []

        # Resolve via rncli autolinking so we use real node resolution (handles pnpm,
        # yarn resolutions/PnP, aliased specifiers). Skip if the package isn't installed.
        dep = react_native_config.dig('dependencies', npm_package)
        return unless dep

        package_root = dep['root']
        pkg_version = dep.dig('platforms', 'ios', 'version')

        # codegenConfig.name isn't surfaced by rncli; read it from package.json.
        installed_codegen_name = nil
        pkg_json_path = File.join(package_root, 'package.json')
        if File.exist?(pkg_json_path)
          pkg_json = JSON.parse(File.read(pkg_json_path))
          installed_codegen_name = pkg_json.dig('codegenConfig', 'name')
          pkg_version ||= pkg_json['version']
        end

        base_dir = custom_modules_path || File.join(effective_root, 'packages', 'precompile', PRECOMPILE_BUILD_DIR)

        # Compute versioned output path for 3rd-party packages:
        # <base>/<npm_package>/output/<pkgVersion>/<rnVersion>/<hermesVersion>
        version_prefix = version_prefix_for_external_package(pkg_version)

        products.each do |product|
          pod_name = product['podName']
          next unless pod_name

          product_name = product['name'] || pod_name
          codegen_name = installed_codegen_name || product['codegenName']

          # Use versioned path if versions are available, otherwise fall back to flat path
          if version_prefix
            build_output_dir = File.join(base_dir, npm_package, 'output', version_prefix)
          else
            build_output_dir = File.join(base_dir, npm_package, 'output')
          end

          # Fallback: check for prebuilds bundled inside the package directory (shipped in npm)
          # Try versioned path first, then flat path for backward compatibility
          if !File.directory?(File.join(build_output_dir, build_flavor, 'xcframeworks'))
            bundled_versioned_dir = version_prefix ? File.join(package_root, 'prebuilds', 'output', version_prefix) : nil
            bundled_flat_dir = File.join(package_root, 'prebuilds', 'output')

            if bundled_versioned_dir && File.directory?(bundled_versioned_dir)
              build_output_dir = bundled_versioned_dir
            elsif File.directory?(bundled_flat_dir)
              build_output_dir = bundled_flat_dir
            end
          end

          targets = (product['targets'] || [])
            .select { |t| t['type'] != 'framework' && !t['path']&.start_with?('.build/') }
            .map { |t| { name: t['name'], path: t['path'] } }

          spm_dependency_frameworks = (product['spmPackages'] || []).map { |pkg| pkg['productName'] }.compact
          spm_dependency_versions = spm_package_versions(product['spmPackages'])

          @pod_lookup_map[pod_name] = {
            type: :external,
            npm_package: npm_package,
            package_root: package_root,
            podspec_dir: package_root,
            build_output_dir: build_output_dir,
            codegen_name: codegen_name,
            product_name: product_name,
            targets: targets,
            spm_dependency_frameworks: spm_dependency_frameworks,
            spm_dependency_versions: spm_dependency_versions,
            prebuilt_dependency_pods: prebuilt_dependency_pods(product['externalDependencies']),
            autolink_when: product['autolinkWhen']
          }
        end
      rescue JSON::ParserError, StandardError => e
        Pod::UI.warn "[Expo-precompiled] Failed to read external config at #{config_path}: #{e.message}"
      end

      # Returns { productName => versionString } from a spm.config.json spmPackages array.
      def spm_package_versions(spm_packages)
        (spm_packages || []).each_with_object({}) do |pkg, h|
          version = pkg['version'].is_a?(Hash) ? pkg['version']['exact'] : pkg['version']
          h[pkg['productName']] = version if pkg['productName'] && version
        end
      end

      # Processes a single spm.config.json file and adds entries to @pod_lookup_map.
      def process_spm_config(config_path, type, repo_root)
        config = JSON.parse(File.read(config_path))
        products = config['products'] || []
        package_dir = File.dirname(config_path)
        npm_package = resolve_npm_package_name(package_dir, type, repo_root)

        products.each do |product|
          pod_name = product['podName']
          next unless pod_name

          @pod_lookup_map[pod_name] = build_pod_info(product, pod_name, npm_package, package_dir, type, repo_root)
        end
      rescue JSON::ParserError, StandardError => e
        Pod::UI.warn "[Expo-precompiled] Failed to read spm.config.json at #{config_path}: #{e.message}"
      end

      # Resolves the npm package name from a package directory.
      # External scoped packages derive it from the path; internal packages read package.json.
      def resolve_npm_package_name(package_dir, type, repo_root)
        if type == :external
          external_dir = File.join(repo_root, 'packages', 'external')
          package_dir.sub("#{external_dir}/", '')
        else
          package_json_path = File.join(package_dir, 'package.json')
          if File.exist?(package_json_path)
            JSON.parse(File.read(package_json_path))['name'] || File.basename(package_dir)
          else
            File.basename(package_dir)
          end
        end
      end

      # Builds a pod info hash for a single product from spm.config.json.
      def build_pod_info(product, pod_name, npm_package, package_dir, type, repo_root)
        product_name = product['name'] || pod_name
        codegen_name = resolve_codegen_name(product, pod_name, npm_package, type, repo_root)
        base_dir = custom_modules_path || File.join(repo_root, 'packages', 'precompile', PRECOMPILE_BUILD_DIR)
        build_output_dir = File.join(base_dir, npm_package, 'output')

        # Fallback: check for prebuilds bundled inside the package directory (shipped in npm)
        bundled_output_dir = File.join(package_dir, 'prebuilds', 'output')
        if !File.directory?(build_output_dir) && File.directory?(bundled_output_dir)
          build_output_dir = bundled_output_dir
        end

        package_root, podspec_dir = resolve_package_paths(pod_name, package_dir, npm_package, type, repo_root)

        targets = (product['targets'] || [])
          .select { |t| t['type'] != 'framework' && !t['path']&.start_with?('.build/') }
          .map { |t| { name: t['name'], path: t['path'] } }

        spm_dependency_frameworks = (product['spmPackages'] || []).map { |pkg| pkg['productName'] }.compact
        spm_dependency_versions = spm_package_versions(product['spmPackages'])

        {
          type: type,
          npm_package: npm_package,
          package_root: package_root,
          podspec_dir: podspec_dir,
          build_output_dir: build_output_dir,
          codegen_name: codegen_name,
          product_name: product_name,
          targets: targets,
          spm_dependency_frameworks: spm_dependency_frameworks,
          spm_dependency_versions: spm_dependency_versions,
          prebuilt_dependency_pods: prebuilt_dependency_pods(product['externalDependencies']),
          autolink_when: product['autolinkWhen']
        }
      end

      # Returns the product names of dependencies whose prebuilt availability must
      # match this product's availability. Both slash-form package/product strings
      # (e.g. "expo-modules-core/ExpoModulesCore") and bare product names (e.g.
      # "RNWorklets") are surfaced. Which of them are actually precompiled-managed
      # pods is decided later by @pod_lookup_map membership in the resolver, so
      # runtime deps like React/Hermes are surfaced here but ignored there.
      def prebuilt_dependency_pods(external_dependencies)
        (external_dependencies || []).filter_map do |dep|
          next unless dep.is_a?(String)

          parts = dep.split('/')
          product_name =
            if parts.length == 1
              parts[0]                          # bare, e.g. "RNWorklets"
            elsif parts[0].start_with?('@')
              parts[2]                          # @scope/package/Product
            else
              parts[1]                          # package/Product
            end

          next if CUSTOM_XCFRAMEWORK_DEPENDENCIES.include?(product_name)

          product_name
        end.uniq
      end

      # Reverse of `prebuilt_dependency_pods` over 3rd-party pods: maps a pod to the
      # pods that declare it as a dependency.
      #
      # @return [Hash<String, Array<String>>] Pod name to the pods depending on it
      def prebuilt_dependent_pods
        @prebuilt_dependent_pods ||= begin
          dependents = {}
          pod_lookup_map.each do |pod_name, info|
            next unless info[:type] == :external
            (info[:prebuilt_dependency_pods] || []).each do |dep_name|
              next unless pod_lookup_map.dig(dep_name, :type) == :external
              (dependents[dep_name] ||= []) << pod_name
            end
          end
          dependents
        end
      end

      # Resolves the codegen module name. For external packages, prefers codegenConfig.name
      # from the installed package.json over spm.config.json's codegenName.
      def resolve_codegen_name(product, pod_name, npm_package, type, repo_root)
        codegen_name = product['codegenName']
        return codegen_name unless type == :external && codegen_name

        ext_pkg_json = File.join(repo_root, 'node_modules', npm_package, 'package.json')
        return codegen_name unless File.exist?(ext_pkg_json)

        begin
          rn_codegen_name = JSON.parse(File.read(ext_pkg_json)).dig('codegenConfig', 'name')
          if rn_codegen_name && rn_codegen_name != codegen_name
            Pod::UI.info "#{'[Expo-precompiled] '.blue}#{pod_name}: using codegenConfig.name '#{rn_codegen_name}' instead of '#{codegen_name}'"
            return rn_codegen_name
          end
        rescue JSON::ParserError
          # Fall back to spm.config.json value
        end

        codegen_name
      end

      # Resolves the package_root and podspec_dir for a pod.
      # @return [Array<String>] [package_root, podspec_dir]
      def resolve_package_paths(pod_name, package_dir, npm_package, type, repo_root)
        if type == :internal
          package_root = package_dir
          ios_podspec = File.join(package_root, 'ios', "#{pod_name}.podspec")
          root_podspec = File.join(package_root, "#{pod_name}.podspec")

          podspec_dir = if File.exist?(ios_podspec)
            File.join(package_root, 'ios')
          elsif File.exist?(root_podspec)
            package_root
          else
            File.join(package_root, 'ios')
          end

          [package_root, podspec_dir]
        else
          package_root = resolve_external_package_root(npm_package, repo_root)
          [package_root, package_root]
        end
      end

      # Resolves the package root for an external (3rd-party) npm package.
      # Tries multiple node_modules locations to support pnpm/yarn workspaces.
      def resolve_external_package_root(npm_package, repo_root)
        # Try repo root node_modules first (works for npm/yarn classic)
        candidate = File.join(repo_root, 'node_modules', npm_package)
        return candidate if File.exist?(candidate)

        # Try resolving from the Podfile directory (works for pnpm workspaces
        # where packages are symlinked in the app's node_modules)
        podfile_dir = Dir.pwd
        project_root = File.dirname(podfile_dir)
        candidate = File.join(project_root, 'node_modules', npm_package)
        return candidate if File.exist?(candidate)

        # Fallback to original path
        File.join(repo_root, 'node_modules', npm_package)
      end

      # Finds the repository root by walking up from the current directory.
      def find_repo_root(start_dir = nil)
        current_dir = start_dir || Dir.pwd

        loop do
          return current_dir if File.exist?(File.join(current_dir, 'packages', 'expo-modules-core', 'spm.config.json'))

          parent = File.dirname(current_dir)
          break if parent == current_dir
          current_dir = parent
        end

        nil
      end

      # Invokes `expo-modules-autolinking <subcommand> --json` and parses the output.
      # Used by `react_native_config` and `resolved_modules` above.
      def invoke_autolinking(subcommand, platform:)
        args = ['node', '--no-warnings', '--eval', "require('expo/bin/autolinking')",
                'expo-modules-autolinking', subcommand, '--platform', platform, '--json']
        JSON.parse(IO.popen(args, &:read))
      rescue => error
        raise "Failed to invoke `expo-modules-autolinking #{subcommand}`: #{error}"
      end

      # ──────────────────────────────────────────────────────────────────────
      # Helpers: bundled frameworks
      # ──────────────────────────────────────────────────────────────────────

      # Returns the set of all SPM dependency framework names that are bundled inside
      # prebuilt XCFrameworks. These pods should be stubbed (header-only) when they appear
      # as source pods, to avoid duplicate symbols with the xcframework.
      #
      # @return [Set<String>] Framework names bundled across all prebuilt pods
      def all_bundled_frameworks
        @all_bundled_frameworks ||= begin
          bundled = Set.new(bundled_framework_owners.keys)
          Pod::UI.puts "#{'[Expo-precompiled] '.blue}Bundled SPM frameworks: #{bundled.to_a.join(', ')}" if bundled.any?
          bundled
        end
      end

      # Maps each bundled SPM framework name to the prebuilt pods whose xcframeworks
      # bundle it (e.g. "SDWebImage" => Set{"ExpoImage"}).
      #
      # @return [Hash<String, Set<String>>] Framework name to owning prebuilt pod names
      def bundled_framework_owners
        @bundled_framework_owners ||= begin
          owners = {}
          pod_lookup_map.each do |pod_name, info|
            next unless resolve_prebuilt_info(pod_name)
            (info[:spm_dependency_frameworks] || []).each do |framework|
              (owners[framework] ||= Set.new).add(pod_name)
            end
          end
          owners
        end
      end

      # Whether a bundled source pod target needs stubbing. Stubbing is only needed when
      # a consumer of the source pod also links a prebuilt xcframework that bundles the
      # same framework — otherwise the consumer would get duplicate classes. A pod whose
      # consumers link no owning prebuilt pod must keep building from source: e.g. an app
      # extension that depends on SDWebImage never links expo-image's bundled
      # SDWebImage.xcframework, so stubbing would leave its symbols unresolved.
      def stub_bundled_pod_target?(installer, pod_name, framework_name)
        owners = bundled_framework_owners[framework_name]
        return true if owners.nil? || owners.empty?

        consumers = installer.aggregate_targets.select do |aggregate_target|
          aggregate_target.pod_targets.any? { |pod_target| pod_target.pod_name == pod_name }
        end
        return true if consumers.empty?

        consumers.any? do |aggregate_target|
          aggregate_target.pod_targets.any? { |pod_target| owners.include?(pod_target.pod_name) }
        end
      end

      # ──────────────────────────────────────────────────────────────────────
      # Helpers: external prebuilt pods
      # ──────────────────────────────────────────────────────────────────────

      # Returns external (3rd-party) pods that have prebuilt XCFrameworks.
      #
      # @param project_directory [Pathname] The project root for computing relative paths
      # @return [Array<Hash>] Array of {:pod_name, :podspec_path} for external prebuilt pods
      def external_prebuilt_pods(project_directory)
        return [] unless enabled?

        results = []
        pod_lookup_map.each do |pod_name, info|
          next unless info[:type] == :external

          resolution = resolve_prebuilt_status(pod_name)
          unless resolution[:available]
            reason = format_prebuilt_unavailable_reason(resolution)
            Pod::UI.puts "#{'[Expo-precompiled] '.blue}#{"#{pod_name}: building from source (#{reason})".yellow}"
            unless CASCADED_UNAVAILABLE_REASONS.include?(resolution[:reason])
              product_name = info[:product_name] || pod_name
              expected = File.join(info[:build_output_dir], build_flavor, 'xcframeworks', "#{product_name}.tar.gz")
              Pod::UI.puts "#{'[Expo-precompiled] '.blue}#{gray("  Expected tarball: #{expected}")}"
            end
            next
          end

          podspec_file = File.join(info[:podspec_dir], "#{pod_name}.podspec")
          next unless File.exist?(podspec_file)

          patched_podspec = generate_prepatched_podspec(pod_name, podspec_file, info)
          next unless patched_podspec

          podspec_rel = Pathname.new(patched_podspec).relative_path_from(project_directory).to_s
          results << { pod_name: pod_name, podspec_path: podspec_rel }
        end

        results
      end

      # Generates a pre-patched podspec JSON file for an external pod.
      def generate_prepatched_podspec(pod_name, podspec_file, info)
        begin
          spec = Pod::Specification.from_file(podspec_file)
        rescue => e
          Pod::UI.warn "[Expo-precompiled] Failed to evaluate podspec for #{pod_name}: #{e.message}"
          return nil
        end

        patched_spec = patch_spec_for_prebuilt(spec)
        return nil if patched_spec.equal?(spec)

        spec_json = JSON.parse(patched_spec.to_pretty_json)
        spec_json.delete('dependencies')

        json_path = podspec_file.sub(/\.podspec$/, '.podspec.json')
        File.write(json_path, JSON.pretty_generate(spec_json))

        json_path
      end

      # ──────────────────────────────────────────────────────────────────────
      # Helpers: version resolution for 3rd-party prebuild versioning
      # ──────────────────────────────────────────────────────────────────────

      # RN package path, as resolved by rncli (handles pnpm workspaces correctly).
      def react_native_path
        react_native_config['reactNativePath']
      end

      def react_native_version
        @react_native_version ||= begin
          rn_pkg = react_native_path && File.join(react_native_path, 'package.json')
          rn_pkg && File.exist?(rn_pkg) ? JSON.parse(File.read(rn_pkg))['version'] : nil
        end
      end

      # Returns the Hermes version. Hermes v1 is the default; classic Hermes is opt-out.
      # Mirrors the TypeScript resolution logic in tools/src/prebuilds/Utils.ts.
      def hermes_version
        @hermes_version ||= begin
          rn_path = react_native_path
          if rn_path
            # Matches hermes-engine.podspec polarity: V1 is the default, classic
            # is selected only when the consuming app explicitly sets the env var to "0".
            is_v1 = ENV['RCT_HERMES_V1_ENABLED'] != '0'
            props_path = File.join(rn_path, 'sdks', 'hermes-engine', 'version.properties')
            version = File.exist?(props_path) ?
              parse_version_properties(props_path)[is_v1 ? 'HERMES_V1_VERSION_NAME' : 'HERMES_VERSION_NAME'] : nil

            # Fallback to tag files
            unless version
              tag_path = File.join(rn_path, 'sdks', is_v1 ? '.hermesv1version' : '.hermesversion')
              version = File.read(tag_path).strip if File.exist?(tag_path)
            end

            # Normalize: strip "hermes-" prefix and "v" prefix
            version&.gsub(/^hermes-?/i, '')&.gsub(/^v/i, '')&.strip
          end
        end
      end

      # Parses a Java-style .properties file into a Hash.
      def parse_version_properties(file_path)
        props = {}
        File.readlines(file_path).each do |line|
          trimmed = line.strip
          next if trimmed.empty? || trimmed.start_with?('#')
          key, value = trimmed.split('=', 2)
          props[key.strip] = value.strip if key && value
        end
        props
      end

      # Returns the version prefix path for a 3rd-party package.
      # Format: "<packageVersion>/<reactNativeVersion>/<hermesVersion>"
      # Returns nil if versions cannot be resolved.
      def version_prefix_for_external_package(package_version)
        rn_ver = react_native_version
        hermes_ver = hermes_version
        return nil unless package_version && rn_ver && hermes_ver
        File.join(package_version, rn_ver, hermes_ver)
      end

      # ──────────────────────────────────────────────────────────────────────
      # Helpers: prebuilt info resolution
      # ──────────────────────────────────────────────────────────────────────

      # Resolves prebuilt xcframework info for a pod.
      # @return [Array, nil] [pod_info, product_name, tarball_path] or nil
      def resolve_prebuilt_info(pod_name)
        resolution = resolve_prebuilt_status(pod_name)
        resolution[:available] ? resolution[:resolved] : nil
      end

      # Resolves only this pod's own prebuilt artifact without checking parent dependencies.
      # @return [Hash] Availability information with :available, :resolved, :reason, and :path.
      def resolve_own_prebuilt_info(pod_name)
        pod_info = pod_lookup_map[pod_name]
        return { available: false, reason: :missing_config } unless pod_info

        product_name = pod_info[:product_name] || pod_name
        tarball = resolve_prebuilt_tarball(pod_info, product_name, build_flavor, pod_name)
        return { available: false, reason: :missing_tarball, path: tarball } unless File.exist?(tarball)
        return { available: false, reason: :missing_platform_slice, path: tarball } unless xcframework_supports_target_platform?(tarball)

        { available: true, resolved: [pod_info, product_name, tarball] }
      end

      # A pod may use a prebuilt xcframework only when its own prebuilt artifact
      # exists and every pod it is interdependent with also uses prebuilt — in either
      # direction, so a set of interdependent pods is all prebuilt or all from source.
      def resolve_prebuilt_status(pod_name, visiting = Set.new)
        return _resolve_prebuilt_status_uncached(pod_name, visiting) unless visiting.empty?
        @status_cache[pod_name] ||= _resolve_prebuilt_status_uncached(pod_name, visiting)
      end

      def _resolve_prebuilt_status_uncached(pod_name, visiting)
        return { available: false, reason: :build_from_source } if build_from_source?(pod_name)
        return { available: true } if visiting.include?(pod_name)

        own_resolution = resolve_own_prebuilt_info(pod_name)
        return own_resolution unless own_resolution[:available]

        pod_info = own_resolution[:resolved][0]
        next_visiting = visiting.dup.add(pod_name)

        (pod_info[:prebuilt_dependency_pods] || []).each do |dep_name|
          # Only precompiled-managed pods participate in availability propagation.
          # Runtime deps like React/Hermes are surfaced by prebuilt_dependency_pods
          # but are not in the map, so they are ignored here.
          next unless pod_lookup_map.key?(dep_name)

          dep_resolution = resolve_prebuilt_status(dep_name, next_visiting)
          next if dep_resolution[:available]

          return {
            available: false,
            reason: :dependency_unavailable,
            dependency: dep_name,
            dependency_resolution: dep_resolution
          }
        end

        # Unavailability propagates to dependencies too: a source-built dependent
        # includes its dependency's headers from `Pods/Headers/Public/<dep>`, which
        # CocoaPods only populates while the dependency builds from source.
        prebuilt_dependent_pods.fetch(pod_name, []).each do |dependent_name|
          dependent_resolution = resolve_prebuilt_status(dependent_name, next_visiting)
          next if dependent_resolution[:available]

          return {
            available: false,
            reason: :dependent_unavailable,
            dependent: dependent_name,
            dependent_resolution: dependent_resolution
          }
        end

        own_resolution
      end

      # Candidate parent dirs (each holds <flavor>/<Name>.xcframework subtrees) for
      # a shared SPM dep. Ordered: EXPO_PRECOMPILED_MODULES_PATH override, monorepo
      # .spm-deps, then the consumer-side npm-bundled location.
      def shared_spm_dep_source_base_candidates(dep_name, pod_info)
        candidates = []
        candidates << File.join(custom_modules_path, SHARED_SPM_DEPS_SOURCE_DIR, dep_name) if custom_modules_path
        candidates << File.join(memoized_repo_root, 'packages', 'precompile', PRECOMPILE_BUILD_DIR, SHARED_SPM_DEPS_SOURCE_DIR, dep_name) if memoized_repo_root
        candidates << File.join(pod_info[:package_root], BUNDLED_SHARED_SPM_DEPS_SUBPATH, dep_name) if pod_info && pod_info[:package_root]
        candidates
      end

      # First candidate base that has at least one flavor on disk (used to build switch-script source_base args).
      def shared_spm_dep_source_base(dep_name, pod_info)
        shared_spm_dep_source_base_candidates(dep_name, pod_info).find do |base|
          %w[debug release].any? { |f| File.directory?(File.join(base, f, "#{dep_name}.xcframework")) }
        end
      end

      # First candidate that has the requested flavor on disk (walks all candidates so a partial monorepo doesn't shadow a complete npm bundle).
      def shared_spm_dep_xcframework_path(dep_name, pod_info, flavor)
        shared_spm_dep_source_base_candidates(dep_name, pod_info).each do |base|
          path = File.join(base, flavor, "#{dep_name}.xcframework")
          return path if File.directory?(path)
        end
        nil
      end

      def memoized_repo_root
        return @repo_root if @memoized_repo_root_set
        begin
          @repo_root = find_repo_root
        ensure
          @memoized_repo_root_set = true
        end
        @repo_root
      end

      def resolve_prebuilt_tarball(pod_info, product_name, flavor, pod_name = nil)
        tarball = File.join(pod_info[:build_output_dir], flavor, 'xcframeworks', "#{product_name}.tar.gz")
        return tarball if File.exist?(tarball)

        base_url = external_modules_base_url
        return tarball unless pod_info[:type] == :external && base_url

        output_prefix = File.join(pod_info[:npm_package], 'output')
        idx = pod_info[:build_output_dir].rindex(output_prefix)
        relative_path = [
          (idx ? pod_info[:build_output_dir][idx..] : output_prefix),
          flavor,
          'xcframeworks',
          "#{product_name}.tar.gz"
        ].join('/')
        remote_url = "#{base_url.chomp('/')}/#{relative_path}"
        remote_tarball = File.join(remote_precompiled_artifacts_dir, relative_path)

        return remote_tarball if File.exist?(remote_tarball)
        return remote_tarball if failed_remote_downloads.include?(remote_url)

        download_remote_tarball(remote_url, remote_tarball, pod_name || product_name, flavor)
        remote_tarball
      end

      def normalize_xcframework_platform(platform)
        name = platform.respond_to?(:name) ? platform.name : platform
        name = name.string_name if name.respond_to?(:string_name)
        normalized = name.to_s.downcase
        normalized == 'osx' ? 'macos' : normalized
      end

      def xcframework_supports_target_platform?(path)
        return true unless @target_platform

        @xcframework_slice_cache ||= {}
        cache_key = [path, @target_platform]
        return @xcframework_slice_cache[cache_key] if @xcframework_slice_cache.key?(cache_key)

        @xcframework_slice_cache[cache_key] = begin
          info_plists = File.directory?(path) ? [read_plist(File.join(path, 'Info.plist'))] : read_xcframework_info_plists_from_tarball(path)
          info_plists.any? && info_plists.all? { |info_plist| info_plist_supports_target_platform?(info_plist) }
        end
      end

      def info_plist_supports_target_platform?(info_plist)
        return false unless info_plist

        available_libraries = info_plist['AvailableLibraries']
        return false unless available_libraries.is_a?(Array)

        available_libraries.any? do |library|
          normalize_xcframework_platform(library['SupportedPlatform']) == @target_platform
        end
      end

      # Reads every `*.xcframework/Info.plist` out of a prebuilt tarball.
      #
      # A tarball can hold more than one xcframework — the product plus any bundled SPM
      # dependency, such as SDWebImage inside ExpoImage — and the caller requires all of
      # them to support the target platform, so every match must be read, not just the
      # first.
      #
      # Extracting the whole glob in one pass replaces a listing pass plus one extract per
      # plist. `tar` decompresses a gzip stream from the start, so that was 1 + N full
      # decompressions of an archive that also carries the dSYM bundles; on a 4 MB artifact
      # it measured 36 ms against 19 ms for a single pass. This runs for every prebuilt pod
      # during Podfile evaluation.
      def read_xcframework_info_plists_from_tarball(tarball)
        Dir.mktmpdir('expo-xcframework-info') do |dir|
          # /usr/bin/tar rather than `tar`: this relies on bsdtar's member globbing, and a
          # GNU tar earlier in PATH would match nothing and send every pod to source.
          output, status = Open3.capture2e('/usr/bin/tar', 'xzf', tarball, '-C', dir, '*.xcframework/Info.plist')
          plists = Dir.glob(File.join(dir, '**', '*.xcframework', 'Info.plist')).sort

          # `tar` extracts members in order, so a truncated archive can yield the first
          # plist and then fail. Treating a partial result as usable would let the caller's
          # all-xcframeworks check pass on a subset, and link a damaged tarball that used
          # to fall back to source.
          if !status.success? && !plists.empty?
            Pod::UI.warn "[Expo-precompiled] Failed to inspect #{File.basename(tarball)}: #{output.strip}"
            next []
          end

          if plists.empty?
            # A pattern that matches nothing also exits non-zero, so the two cases are
            # told apart by bsdtar's message; only the wording differs, both give up.
            if status.success? || output.include?(TAR_NO_MATCH_MESSAGE)
              Pod::UI.warn "[Expo-precompiled] No XCFramework Info.plist found in #{File.basename(tarball)}"
            else
              Pod::UI.warn "[Expo-precompiled] Failed to inspect #{File.basename(tarball)}: #{output.strip}"
            end
            next []
          end

          parsed = plists.map { |path| read_plist(path) }
          if parsed.any?(&:nil?)
            # Dropping the unreadable one would check a subset, which is the same hole a
            # partial extraction opens.
            Pod::UI.warn "[Expo-precompiled] Unreadable XCFramework Info.plist in #{File.basename(tarball)}"
            next []
          end

          parsed
        end
      rescue StandardError => e
        Pod::UI.warn "[Expo-precompiled] Failed to inspect #{File.basename(tarball)}: #{e.message}"
        []
      end

      def read_plist(path)
        Xcodeproj::Plist.read_from_path(path)
      rescue StandardError => e
        Pod::UI.warn "[Expo-precompiled] Failed to read #{File.basename(path)}: #{e.message}"
        nil
      end

      def failed_remote_downloads
        @failed_remote_downloads ||= Set.new
      end

      def remote_precompiled_artifacts_dir
        pods_root = Pod::Config.instance.sandbox_root rescue File.join(Dir.pwd, 'Pods')
        File.join(pods_root.to_s, 'ExpoPrecompiledArtifacts')
      end

      def gray(text)
        text.respond_to?(:gray) ? text.gray : text
      end

      def download_remote_tarball(remote_url, destination_path, pod_name, flavor)
        FileUtils.mkdir_p(File.dirname(destination_path))
        tmp_path = "#{destination_path}.download-#{Process.pid}"

        download_to_file(remote_url, tmp_path)
        FileUtils.mv(tmp_path, destination_path)
        Pod::UI.info "#{'[Expo-precompiled] '.blue}#{pod_name}: downloaded remote #{flavor} artifact"
        destination_path
      rescue => e
        FileUtils.rm_f(tmp_path) if tmp_path && File.exist?(tmp_path)
        failed_remote_downloads.add(remote_url)
        Pod::UI.puts "#{'[Expo-precompiled] '.blue}#{"#{pod_name}: remote #{flavor} artifact unavailable (#{e.message}); building from source".yellow}"
        Pod::UI.puts "#{'[Expo-precompiled] '.blue}#{gray("  URL: #{remote_url}")}"
        nil
      end

      def download_to_file(url, destination_path, limit = 5)
        raise 'Too many HTTP redirects' if limit <= 0

        uri = URI.parse(url)

        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.is_a?(URI::HTTPS), open_timeout: 10, read_timeout: 120) do |http|
          request = Net::HTTP::Get.new(uri.request_uri)

          http.request(request) do |response|
            case response
            when Net::HTTPSuccess
              File.open(destination_path, 'wb') do |file|
                response.read_body { |chunk| file.write(chunk) }
              end
            when Net::HTTPRedirection
              redirect_url = URI.join(uri.to_s, response['location']).to_s
              return download_to_file(redirect_url, destination_path, limit - 1)
            else
              raise "HTTP #{response.code}"
            end
          end
        end
      end

      # ──────────────────────────────────────────────────────────────────────
      # Helpers: codegen
      # ──────────────────────────────────────────────────────────────────────

      # Returns the codegenConfig library names for pods that should be excluded from codegen.
      #
      # @param pod_targets [Array<Pod::PodTarget>] The pod targets
      # @return [Array<String>] codegenConfig.name values to exclude from codegen
      def codegen_exclusion_list(pod_targets)
        return [] unless enabled?

        exclusions = []
        pod_lookup_map.each do |pod_name, info|
          next unless info[:type] == :external
          next unless info[:codegen_name]
          next unless resolve_prebuilt_info(pod_name)

          exclusions << info[:codegen_name]
          Pod::UI.info "#{'[Expo-precompiled] '.blue}Found external package '#{info[:npm_package]}' with codegen module: #{info[:codegen_name]}"
        end

        exclusions.uniq
      end

      # Removes source file references for prebuilt libraries from ReactCodegen compile sources.
      def remove_codegen_sources_from_compile_phase(target, codegen_exclusions)
        compile_sources_phase = target.build_phases.find do |p|
          p.is_a?(Xcodeproj::Project::Object::PBXSourcesBuildPhase)
        end
        return unless compile_sources_phase

        files_to_remove = compile_sources_phase.files.select do |build_file|
          file_ref = build_file.file_ref
          next false unless file_ref

          codegen_file_matches_exclusion?(build_file, file_ref, codegen_exclusions)
        end

        if files_to_remove.any?
          Pod::UI.puts "[Expo] ".blue + "Removing #{files_to_remove.count} codegen source files from ReactCodegen compile sources"
          files_to_remove.each { |bf| compile_sources_phase.files.delete(bf) }
        end
      end

      # Checks whether a build file belongs to an excluded codegen library.
      def codegen_file_matches_exclusion?(build_file, file_ref, codegen_exclusions)
        file_path = file_ref.path.to_s
        display_name = build_file.display_name.to_s
        parent_name = (file_ref.respond_to?(:parent) && file_ref.parent) ? (file_ref.parent.name.to_s rescue '') : ''

        codegen_exclusions.any? do |lib|
          file_path.start_with?("#{lib}-") ||
            file_path.start_with?("#{lib}JSI") ||
            display_name.start_with?("#{lib}-") ||
            display_name.start_with?("#{lib}JSI") ||
            file_path.include?("/#{lib}/") ||
            file_path.start_with?("#{lib}/") ||
            parent_name == lib
        end
      end

      # Adds a shell script build phase to clean up codegen output for prebuilt libraries.
      def add_codegen_cleanup_script_phase(target, phase_name, codegen_exclusions)
        codegen_cleanup_list = codegen_exclusions.map { |lib| "\"#{lib}\"" }.join(' ')

        phase = target.new_shell_script_build_phase(phase_name)
        phase.shell_path = '/bin/sh'
        phase.shell_script = codegen_cleanup_shell_script(codegen_cleanup_list)
        phase.input_paths = ['$(PODS_ROOT)/../build/generated/autolinking/autolinking.json']
        phase.output_paths = ['$(DERIVED_FILE_DIR)/expo-codegen-cleanup.stamp']

        compile_sources_index = target.build_phases.find_index do |p|
          p.is_a?(Xcodeproj::Project::Object::PBXSourcesBuildPhase)
        end

        if compile_sources_index
          target.build_phases.delete(phase)
          target.build_phases.insert(compile_sources_index, phase)
        else
          Pod::UI.puts "[Expo] ".yellow + "Could not find 'Compile Sources' phase, build phase added at default position"
        end
      end

      # Returns the shell script content for the codegen cleanup build phase.
      def codegen_cleanup_shell_script(codegen_cleanup_list)
        <<~SH
          # Cleanup generated codegen files for prebuilt libraries to avoid duplicate symbols
          # When a library is prebuilt as an XCFramework, its codegen output is already included in the framework.
          # We need to remove the generated files so they don't get compiled into the ReactCodegen pod as well.
          # NOTE: The source file references have already been removed from the Xcode project during pod install,
          # but we still need to delete the files because codegen regenerates them on each build.

          PREBUILT_CODEGEN_LIBS=(#{codegen_cleanup_list})
          CODEGEN_OUTPUT_DIR="$PODS_ROOT/../build/generated/ios/ReactCodegen"

          if [ ${#PREBUILT_CODEGEN_LIBS[@]} -gt 0 ]; then
            echo "[Expo] Cleaning up codegen output for prebuilt libraries: ${PREBUILT_CODEGEN_LIBS[*]}"

            for lib in "${PREBUILT_CODEGEN_LIBS[@]}"; do
              # Remove module directory (contains .h and -generated.mm files)
              if [ -d "$CODEGEN_OUTPUT_DIR/$lib" ]; then
                echo "[Expo] Removing module: $CODEGEN_OUTPUT_DIR/$lib"
                rm -rf "$CODEGEN_OUTPUT_DIR/$lib"
              fi

              # Remove JSI header file
              if [ -f "$CODEGEN_OUTPUT_DIR/${lib}JSI.h" ]; then
                echo "[Expo] Removing JSI header: $CODEGEN_OUTPUT_DIR/${lib}JSI.h"
                rm -f "$CODEGEN_OUTPUT_DIR/${lib}JSI.h"
              fi

              # Remove components directory
              if [ -d "$CODEGEN_OUTPUT_DIR/react/renderer/components/$lib" ]; then
                echo "[Expo] Removing components: $CODEGEN_OUTPUT_DIR/react/renderer/components/$lib"
                rm -rf "$CODEGEN_OUTPUT_DIR/react/renderer/components/$lib"
              fi
            done
          fi

          # Touch the stamp file for Xcode dependency tracking
          mkdir -p "$DERIVED_FILE_DIR"
          touch "$DERIVED_FILE_DIR/expo-codegen-cleanup.stamp"
        SH
      end

      # ──────────────────────────────────────────────────────────────────────
      # Helpers: xcconfig / header search paths
      # ──────────────────────────────────────────────────────────────────────

      # Removes -l<lib> linker flags for stubbed libraries from all xcconfig files.
      def remove_linker_flags_for_stubbed_libs(installer, stubbed_lib_names)
        lib_flags = stubbed_lib_names.flat_map { |name| ["-l\"#{name}\"", "-l#{name}"] }
        return if lib_flags.empty?

        xcconfig_dir = File.join(installer.sandbox.root, 'Target Support Files')
        return unless File.directory?(xcconfig_dir)

        Dir.glob(File.join(xcconfig_dir, '**', '*.xcconfig')).each do |xcconfig_path|
          content = File.read(xcconfig_path)
          original = content.dup

          lib_flags.each do |flag|
            content = content.gsub(/\s*#{Regexp.escape(flag)}/, '')
          end

          if content != original
            File.write(xcconfig_path, content)
            Pod::UI.puts "#{'[Expo-precompiled] '.blue}Cleaned linker flags from #{File.basename(File.dirname(xcconfig_path))}/#{File.basename(xcconfig_path)}"
          end
        end
      end

      # TODO(ExpoModulesJSI-xcframework): Remove this method when ExpoModulesJSI.xcframework
      # is built and distributed separately.
      #
      # Updates HEADER_SEARCH_PATHS in an xcconfig file
      def update_xcconfig_header_search_paths(xcconfig_path, paths_string)
        content = File.read(xcconfig_path)

        if content.include?('HEADER_SEARCH_PATHS')
          updated_content = content.gsub(/^(HEADER_SEARCH_PATHS\s*=\s*)(.*)$/) do |match|
            $2.include?(paths_string) ? match : "#{$1}#{$2} #{paths_string}"
          end
          File.write(xcconfig_path, updated_content) if updated_content != content
        else
          File.open(xcconfig_path, 'a') { |f| f.puts "HEADER_SEARCH_PATHS = $(inherited) #{paths_string}" }
        end
      end

      # Finds the ExpoModulesCore.xcframework path from the installer
      def find_expo_modules_core_xcframework(installer)
        installer.pod_targets.each do |target|
          next unless target.name == 'ExpoModulesCore'

          vendored = target.root_spec.attributes_hash['vendored_frameworks']
          next unless vendored

          frameworks = vendored.is_a?(Array) ? vendored : [vendored]
          frameworks.each do |framework|
            if framework.to_s.include?('ExpoModulesCore.xcframework')
              podspec_dir = target.sandbox.pod_dir(target.name)
              framework_path = File.expand_path(framework, podspec_dir)

              Pod::UI.info "#{'[Expo-precompiled] '.blue}Looking for ExpoModulesCore.xcframework at: #{framework_path}"
              return framework_path if File.directory?(framework_path)
            end
          end
        end

        nil
      end

      # Collects header paths from all slices of an XCFramework.
      def collect_xcframework_header_paths(xcframework_path, product_name)
        return [] unless File.directory?(xcframework_path)

        Dir.children(xcframework_path).filter_map do |slice|
          slice_path = File.join(xcframework_path, slice)
          next unless File.directory?(slice_path)

          framework_headers = File.join(slice_path, "#{product_name}.framework", 'Headers')
          framework_headers if File.directory?(framework_headers)
        end
      end

      # Header dirs of an installed prebuilt pod's xcframework, one per slice.
      def prebuilt_xcframework_header_paths(installer, pod_name)
        product_name = pod_lookup_map[pod_name]&.dig(:product_name) || pod_name
        xcframework_path = File.join(installer.sandbox.root, pod_name, "#{product_name}.xcframework")
        collect_xcframework_header_paths(xcframework_path, product_name)
      end

      # ──────────────────────────────────────────────────────────────────────
      # Helpers: linking summary tracking
      # ──────────────────────────────────────────────────────────────────────

      # Records the linking status for a pod (only once per pod to avoid duplicates).
      def log_linking_status(pod_name, found, info = nil)
        @linked_pods ||= {}
        return if @linked_pods[pod_name]
        status = info.is_a?(Hash) ? info.dup : { path: info }
        @linked_pods[pod_name] = status.merge(found: found, spm_deps: [])
      end

      def format_prebuilt_unavailable_reason(info)
        case info[:reason]
        when :build_from_source
          'configured by buildFromSource'
        when :missing_config
          'prebuilt config not found'
        when :missing_tarball
          'prebuilt tarball not found'
        when :missing_platform_slice
          "prebuilt xcframework does not contain a slice for #{@target_platform}"
        when :dependency_unavailable
          reason = format_prebuilt_unavailable_reason(info[:dependency_resolution])
          "dependency #{info[:dependency]} is not using prebuilt: #{reason}"
        when :dependent_unavailable
          reason = format_prebuilt_unavailable_reason(info[:dependent_resolution])
          "dependent #{info[:dependent]} is not using prebuilt: #{reason}"
        else
          info[:path] || 'prebuilt unavailable'
        end
      end

      # Records an SPM dependency xcframework bundled inside a precompiled pod.
      def log_spm_dependency(pod_name, dep_name)
        @linked_pods ||= {}
        @linked_pods[pod_name] ||= { found: true, path: nil, spm_deps: [] }
        @linked_pods[pod_name][:spm_deps] << dep_name
      end
    end
  end
end
