ruflet 0.0.19 → 0.0.21

data/lib/ruflet/cli/build_command.rb

@@ -26,6 +26,7 @@ module Ruflet
         "lottie" => { package: "flet_lottie", alias: "ruflet_lottie" },
         "map" => { package: "flet_map", alias: "ruflet_map" },
         "permission_handler" => { package: "flet_permission_handler", alias: "ruflet_permission_handler" },
+        "qrcode_scanner" => { package: "ruflet_qrcode_scanner", alias: "ruflet_qrcode_scanner" },
         "rive" => { package: "flet_rive", alias: "ruflet_rive" },
         "secure_storage" => { package: "flet_secure_storage", alias: "ruflet_secure_storage" },
         "video" => { package: "flet_video", alias: "ruflet_video" },
@@ -37,6 +38,9 @@ module Ruflet
         "location" => %w[geolocator permission_handler],
         "motion" => %w[permission_handler]
       }.freeze
+      EXTENSION_REQUIRED_SERVICES = {
+        "qrcode_scanner" => %w[camera]
+      }.freeze
       ANDROID_SERVICE_PERMISSIONS = {
         "camera" => %w[android.permission.CAMERA],
         "microphone" => %w[android.permission.RECORD_AUDIO],
@@ -49,13 +53,27 @@ module Ruflet
         "location" => "NSLocationWhenInUseUsageDescription",
         "motion" => "NSMotionUsageDescription"
       }.freeze
+      # Clients that are told which server to use at launch rather than at build
+      # time, so they may be built without a configured backend_url.
+      RUNTIME_RESOLVED_BACKEND_PLATFORMS = %w[web macos windows linux].freeze
+      # What the underlying generators can actually produce per platform:
+      # flutter_native_splash covers android/ios/web, flutter_launcher_icons
+      # covers android/ios/web/windows/macos. Linux has neither.
+      PLATFORM_ASSET_SUPPORT = {
+        "android" => { splash: true, icon: true },
+        "ios" => { splash: true, icon: true },
+        "web" => { splash: true, icon: true },
+        "macos" => { splash: false, icon: true },
+        "windows" => { splash: false, icon: true },
+        "linux" => { splash: false, icon: false }
+      }.freeze
 
       def command_build(args)
         self_contained = args.delete("--self")
         verbose = args.delete("--verbose") || args.delete("-v")
         platform = (args.shift || "").downcase
         if platform.empty?
-          warn "Usage: ruflet build <apk|android|ios|aab|web|macos|windows|linux> [--self] [--verbose]"
+          warn "Usage: ruflet build <apk|android|aab|ios|ipa|web|macos|windows|linux> [--self] [--verbose]"
           return 1
         end
 
@@ -65,6 +83,20 @@ module Ruflet
           return 1
         end
 
+        # `ipa` produces the uploadable archive; every other step — pods,
+        # signing, icons, package name — is the same as a plain iOS build.
+        requested_platform = platform
+        platform = "ios" if platform == "ipa"
+
+        # The embedded Ruby VM is a native plugin with no browser
+        # implementation, so a self-contained web build produces an app that
+        # cannot start. Say so rather than shipping one that hangs.
+        if self_contained && platform == "web"
+          warn "build config error: --self is not supported for web"
+          warn "A web client runs no embedded Ruby; build it with `ruflet build web`."
+          return 1
+        end
+
         ensure_ruflet_build_assets(verbose: !!verbose)
         client_dir = ensure_flutter_client_dir(verbose: !!verbose)
         unless client_dir
@@ -88,7 +120,7 @@ module Ruflet
         return 1 unless ok
 
         build_args = [*flutter_cmd, *args]
-        build_args << "--codesign" if ios_device_build_needs_codesign_flag?(platform, build_args)
+        build_args << "--codesign" if ios_device_build_needs_codesign_flag?(requested_platform, build_args)
         target_entrypoint = flutter_target_entrypoint(client_dir, self_contained: !!self_contained)
         build_args += ["--target", target_entrypoint] if target_entrypoint
         backend_url = configured_backend_url(config)
@@ -98,15 +130,21 @@ module Ruflet
           # deterministically instead of inferring from a single main.rb — the
           # app tree now ships many main.rb files (standalone_apps/*/main.rb).
           build_args += ["--dart-define", "RUFLET_EMBEDDED_PROJECT=#{self_contained_project_name}"]
-        else
-          unless backend_url
-            warn "build config error: backend_url is required for server-driven builds"
-            warn "Set app.backend_url or backend_url in ruflet.yaml"
-            return 1
-          end
+        elsif backend_url
           build_args += ["--dart-define", "RUFLET_BACKEND_URL=#{backend_url}"]
+        elsif RUNTIME_RESOLVED_BACKEND_PLATFORMS.include?(platform)
+          # These clients learn their server at launch: a web client from the
+          # origin it is served from, a desktop client from the URL the launcher
+          # passes. Baking one in would pin them to a single host and port,
+          # which a preview client cannot use.
+          build_note("No backend_url configured; the #{platform} client will resolve its server at launch")
+        else
+          warn "build config error: backend_url is required for server-driven builds"
+          warn "Set app.backend_url or backend_url in ruflet.yaml"
+          return 1
         end
         build_args << "-v" if verbose
+        stage_ios_simulator_ruby_runtime(client_dir, build_args, verbose: !!verbose) if self_contained
 
         build_log(verbose, "mode=#{self_contained ? 'self' : 'server'}")
         build_log(verbose, "client_dir=#{client_dir}")
@@ -400,8 +438,12 @@ module Ruflet
 
       def prepare_flutter_client(client_dir, platform:, tools:, config:, self_contained: false, verbose: false)
         refresh_managed_client_template_files(client_dir, verbose: verbose)
-        sync_client_metadata(client_dir, config, verbose: verbose)
+        metadata = sync_client_metadata(client_dir, config, verbose: verbose)
+        return false unless validate_mobile_app_identity(metadata, platform: platform)
+
         apply_native_service_permissions(client_dir, config)
+        apply_android_signing_config(client_dir, platform, verbose: !!verbose)
+        apply_ios_signing_team(client_dir, config) if %w[ios ipa macos].include?(platform.to_s)
         configured = configure_client_runtime_mode(client_dir, self_contained: self_contained, verbose: verbose)
         return false if configured == false
         @ruflet_self_contained_build = self_contained
@@ -424,6 +466,10 @@ module Ruflet
           return false
         end
 
+        unless apply_mobile_package_name(client_dir, metadata, platform: platform, tools: tools, verbose: verbose)
+          return false
+        end
+
         unless ensure_native_build_dependencies(client_dir, platform, tools[:env], verbose: verbose)
           return false
         end
@@ -446,9 +492,60 @@ module Ruflet
           end
         end
 
+        verify_android_generated_assets(client_dir, asset_flags, platform, verbose: verbose)
+
         true
       end
 
+      # The generators can succeed while silently skipping Android output, which
+      # ships a build with the stock Flutter icon and splash. Confirm the native
+      # resources that ruflet.yaml asked for are actually on disk.
+      def verify_android_generated_assets(client_dir, asset_flags, platform, verbose: false)
+        return true unless %w[apk android aab appbundle].include?(platform.to_s)
+
+        res_dir = File.join(client_dir, "android", "app", "src", "main", "res")
+        return true unless File.directory?(res_dir)
+
+        ok = true
+
+        if asset_flags[:has_splash]
+          launch_background = File.join(res_dir, "drawable", "launch_background.xml")
+          if !File.file?(launch_background) || !read_text_file(launch_background).include?("splash")
+            warn "Android splash screen was not generated in res/drawable/launch_background.xml"
+            ok = false
+          end
+
+          styles_v31 = File.join(res_dir, "values-v31", "styles.xml")
+          if !File.file?(styles_v31) || !read_text_file(styles_v31).include?("windowSplashScreenBackground")
+            warn "Android 12+ splash screen is missing from res/values-v31/styles.xml; " \
+                 "devices on Android 12 and newer will show the system default splash"
+            ok = false
+          else
+            build_log(verbose, "android 12+ splash present in values-v31/styles.xml")
+          end
+        end
+
+        if asset_flags[:has_icon]
+          adaptive_icon = File.join(res_dir, "mipmap-anydpi-v26", "launcher_icon.xml")
+          if File.file?(adaptive_icon)
+            build_log(verbose, "adaptive launcher icon present in mipmap-anydpi-v26")
+          else
+            warn "Android adaptive launcher icon was not generated in res/mipmap-anydpi-v26/; " \
+                 "set android.adaptive_icon_foreground and android.adaptive_icon_background in ruflet.yaml"
+            ok = false
+          end
+
+          manifest = File.join(client_dir, "android", "app", "src", "main", "AndroidManifest.xml")
+          if File.file?(manifest) && !read_text_file(manifest).include?("@mipmap/launcher_icon")
+            warn "AndroidManifest.xml does not reference @mipmap/launcher_icon; the configured launcher icon is unused"
+            ok = false
+          end
+        end
+
+        build_note("Android launcher icon and splash resources verified") if ok && (asset_flags[:has_icon] || asset_flags[:has_splash])
+        ok
+      end
+
       def ensure_flutter_platform_artifacts(client_dir, platform, env, flutter, verbose: false)
         precache_flags = flutter_precache_flags(platform)
         return true if precache_flags.empty?
@@ -495,6 +592,50 @@ module Ruflet
         end
       end
 
+      # CocoaPods can incorrectly treat the static-library XCFramework copy
+      # phase as up to date after Ruflet clears Debug-iphonesimulator. The
+      # Runner then links with -lruflet_vm while the selected simulator slice
+      # is absent. Stage that deterministic slice before Flutter invokes
+      # Xcode; CocoaPods may still copy over it normally.
+      def stage_ios_simulator_ruby_runtime(client_dir, build_args, verbose: false)
+        return true unless build_args.include?("ios")
+        return true unless build_args.include?("--simulator")
+
+        runtime_root = explicit_local_ruby_runtime_path || source_checkout_ruby_runtime_path
+        return true unless runtime_root
+
+        source = File.join(
+          runtime_root,
+          "ios",
+          "Frameworks",
+          "RufletVM.xcframework",
+          "ios-arm64_x86_64-simulator"
+        )
+        library = File.join(source, "libruflet_vm.a")
+        return true unless File.file?(library)
+
+        destination = File.join(
+          client_dir,
+          "build",
+          "ios",
+          "Debug-iphonesimulator",
+          "XCFrameworkIntermediates",
+          "ruby_runtime"
+        )
+        FileUtils.mkdir_p(destination)
+        FileUtils.cp(library, File.join(destination, "libruflet_vm.a"))
+
+        headers = File.join(source, "Headers")
+        if Dir.exist?(headers)
+          destination_headers = File.join(destination, "Headers")
+          FileUtils.rm_rf(destination_headers)
+          FileUtils.cp_r(headers, destination_headers)
+        end
+
+        build_log(verbose, "staged iOS simulator Ruflet VM at #{destination}")
+        true
+      end
+
       def ensure_cocoapods_install(client_dir, platform_dir, env, verbose: false)
         pod_dir = File.join(client_dir, platform_dir)
         return true unless Dir.exist?(pod_dir)
@@ -549,7 +690,7 @@ module Ruflet
         shim_dir = File.join(client_dir, ".ruflet", "bin")
         FileUtils.mkdir_p(shim_dir)
         shim_path = File.join(shim_dir, "pod")
-        File.write(
+        write_text_file(
           shim_path,
           <<~SH
             #!/bin/sh
@@ -599,12 +740,19 @@ module Ruflet
           alt = "ruflet.yml"
           config_path = alt if File.file?(alt)
         end
-        return {} unless File.file?(config_path)
-
-        config = YAML.safe_load(File.read(config_path), aliases: true) || {}
-        services_path = File.join(File.dirname(File.expand_path(config_path)), "services.yaml")
+        config_exists = File.file?(config_path)
+        config = config_exists ? YAML.safe_load(read_text_file(config_path), aliases: true) || {} : {}
+        config_dir = File.dirname(File.expand_path(config_path))
+        services_path = File.join(config_dir, "services.yaml")
         if File.file?(services_path)
-          service_config = YAML.safe_load(File.read(services_path), aliases: true) || {}
+          service_config = YAML.safe_load(read_text_file(services_path), aliases: true) || {}
+          if service_config["app"].is_a?(Hash)
+            # ruflet.yaml declares the app; services.yaml may still carry an
+            # identity from older projects, so it fills gaps rather than
+            # overriding what the project states.
+            declared = config["app"].is_a?(Hash) ? config["app"] : {}
+            config["app"] = service_config["app"].merge(declared)
+          end
           config["services"] = service_config["services"] if service_config.key?("services")
         end
         config
@@ -640,16 +788,93 @@ module Ruflet
         splash = resolve_asset.call(build["splash_screen"] || assets["splash_screen"] || config["splash_screen"])
         splash_dark = resolve_asset.call(build["splash_dark"] || build["splash_dark_image"] || assets["splash_dark"])
         icon = resolve_asset.call(build["icon_launcher"] || assets["icon_launcher"] || config["icon_launcher"])
-        icon_android = resolve_asset.call(build["icon_android"] || assets["icon_android"])
-        icon_ios = resolve_asset.call(build["icon_ios"] || assets["icon_ios"])
-        icon_web = resolve_asset.call(build["icon_web"] || assets["icon_web"])
-        icon_windows = resolve_asset.call(build["icon_windows"] || assets["icon_windows"])
-        icon_macos = resolve_asset.call(build["icon_macos"] || assets["icon_macos"])
 
-        splash_color = build["splash_color"]
-        splash_dark_color = build["splash_dark_color"] || build["splash_color_dark"]
-        icon_background = build["icon_background"]
-        theme_color = build["theme_color"]
+        # Splash and icon appearance belongs with the assets it styles. `build`
+        # is still read first so existing projects keep working.
+        splash_color = build["splash_color"] || assets["splash_color"]
+        splash_dark_color = build["splash_dark_color"] || build["splash_color_dark"] ||
+          assets["splash_dark_color"] || assets["splash_color_dark"]
+        icon_background = build["icon_background"] || assets["icon_background"]
+        theme_color = build["theme_color"] || assets["theme_color"]
+
+        # Every platform gets its own section with the same key names, falling
+        # back to the shared assets/build values when a key is not overridden.
+        platforms = PLATFORM_ASSET_SUPPORT.keys.each_with_object({}) do |name, resolved|
+          section = platform_build_config(config, name)
+          resolved[name] = {
+            config: section,
+            splash: resolve_asset.call(
+              section["splash_screen"] || section["splash_image"] ||
+                build["splash_#{name}"] || assets["splash_#{name}"]
+            ),
+            splash_dark: resolve_asset.call(
+              section["splash_dark"] || section["splash_dark_image"] || assets["splash_#{name}_dark"]
+            ),
+            icon: resolve_asset.call(
+              section["icon_launcher"] || section["icon"] ||
+                build["icon_#{name}"] || assets["icon_#{name}"]
+            ),
+            background_image: resolve_asset.call(
+              section["splash_background_image"] || section["background_image"] || assets["splash_background_#{name}"]
+            ),
+            background_image_dark: resolve_asset.call(
+              section["splash_background_image_dark"] || section["background_image_dark"]
+            ),
+            branding: resolve_asset.call(section["splash_branding"] || section["branding"]),
+            branding_dark: resolve_asset.call(section["splash_branding_dark"] || section["branding_dark"]),
+            splash_color: section["splash_color"] || splash_color,
+            splash_dark_color: section["splash_dark_color"] || section["splash_color_dark"] || splash_dark_color,
+            icon_background: section["icon_background"] || icon_background,
+            theme_color: section["theme_color"] || theme_color
+          }
+        end
+
+        splash_background_image = resolve_asset.call(
+          build["splash_background_image"] || assets["splash_background_image"] || build["background_image"]
+        )
+        splash_background_image_dark = resolve_asset.call(
+          build["splash_background_image_dark"] || assets["splash_background_image_dark"]
+        )
+        splash_branding = resolve_asset.call(build["splash_branding"] || assets["splash_branding"])
+        splash_branding_dark = resolve_asset.call(build["splash_branding_dark"] || assets["splash_branding_dark"])
+        splash_branding_mode = build["splash_branding_mode"] || build["branding_mode"] ||
+          assets["splash_branding_mode"] || assets["branding_mode"]
+        splash_branding_padding = build["splash_branding_bottom_padding"] || build["branding_bottom_padding"] ||
+          assets["splash_branding_bottom_padding"] || assets["branding_bottom_padding"]
+
+        android = platforms.dig("android", :config)
+        android_splash = platforms.dig("android", :splash)
+        android_splash_dark = platforms.dig("android", :splash_dark)
+        android_12_splash = resolve_asset.call(
+          android["splash_android_12"] || android["android_12_image"] || assets["splash_android_12"]
+        )
+        android_12_splash_dark = resolve_asset.call(
+          android["splash_android_12_dark"] || android["android_12_image_dark"] || assets["splash_android_12_dark"]
+        )
+        adaptive_foreground = resolve_asset.call(
+          android["adaptive_icon_foreground"] || android["icon_foreground"] ||
+            assets["icon_adaptive_foreground"] || assets["icon_foreground"]
+        )
+        adaptive_background_image = resolve_asset.call(
+          android["adaptive_icon_background_image"] || assets["icon_adaptive_background_image"]
+        )
+        adaptive_monochrome = resolve_asset.call(
+          android["adaptive_icon_monochrome"] || android["icon_monochrome"] || assets["icon_adaptive_monochrome"]
+        )
+
+        android_splash_color = platforms.dig("android", :splash_color)
+        android_splash_dark_color = platforms.dig("android", :splash_dark_color)
+        android_12_icon_background = android["splash_android_12_icon_background_color"] ||
+          android["icon_background_color"] || android_splash_color
+        android_12_icon_background_dark = android["splash_android_12_icon_background_color_dark"] ||
+          android["icon_background_color_dark"] || android_splash_dark_color
+        android_12_color = android["splash_android_12_color"] || android["android_12_color"]
+        android_12_color_dark = android["splash_android_12_color_dark"] || android["android_12_color_dark"]
+        android_12_branding = resolve_asset.call(android["splash_android_12_branding"] || android["android_12_branding"])
+        adaptive_background_color = android["adaptive_icon_background"] || icon_background
+        android_min_sdk = android["min_sdk"] || android["min_sdk_android"] || build["min_sdk_android"]
+        android_splash_fullscreen = first_defined(android, "splash_fullscreen", "fullscreen")
+        android_splash_gravity = android["splash_gravity"] || android["android_gravity"]
 
         assets_dir = File.join(client_dir, "assets")
         FileUtils.mkdir_p(assets_dir)
@@ -662,14 +887,43 @@ module Ruflet
         copy_asset.call(splash, "splash.png")
         copy_asset.call(splash_dark, "splash_dark.png")
         copy_asset.call(icon, "icon.png")
-        copy_asset.call(icon_android, "icon_android.png")
-        copy_asset.call(icon_ios, "icon_ios.png")
-        copy_asset.call(icon_web, "icon_web.png")
-        if icon_windows
-          ext = File.extname(icon_windows).downcase
-          copy_asset.call(icon_windows, ext == ".ico" ? "icon_windows.ico" : "icon_windows.png")
+        copy_asset.call(splash_background_image, "splash_background.png")
+        copy_asset.call(splash_background_image_dark, "splash_background_dark.png")
+        copy_asset.call(splash_branding, "splash_branding.png")
+        copy_asset.call(splash_branding_dark, "splash_branding_dark.png")
+
+        platforms.each do |name, entry|
+          support = PLATFORM_ASSET_SUPPORT.fetch(name)
+          if support[:splash]
+            copy_asset.call(entry[:splash], "splash_#{name}.png")
+            copy_asset.call(entry[:splash_dark], "splash_#{name}_dark.png")
+            copy_asset.call(entry[:background_image], "splash_background_#{name}.png")
+            copy_asset.call(entry[:background_image_dark], "splash_background_#{name}_dark.png")
+            copy_asset.call(entry[:branding], "splash_branding_#{name}.png")
+            copy_asset.call(entry[:branding_dark], "splash_branding_#{name}_dark.png")
+          elsif entry[:splash] || entry[:splash_dark]
+            build_note("#{name} has no splash screen generator; ignoring #{name}.splash_screen")
+          end
+
+          next unless entry[:icon]
+
+          unless support[:icon]
+            build_note("#{name} has no launcher icon generator; ignoring #{name}.icon_launcher")
+            next
+          end
+
+          if name == "windows" && File.extname(entry[:icon]).downcase == ".ico"
+            copy_asset.call(entry[:icon], "icon_windows.ico")
+          else
+            copy_asset.call(entry[:icon], "icon_#{name}.png")
+          end
         end
-        copy_asset.call(icon_macos, "icon_macos.png")
+
+        copy_asset.call(android_12_splash, "splash_android_12.png")
+        copy_asset.call(android_12_splash_dark, "splash_android_12_dark.png")
+        copy_asset.call(adaptive_foreground, "icon_foreground.png")
+        copy_asset.call(adaptive_background_image, "icon_background.png")
+        copy_asset.call(adaptive_monochrome, "icon_monochrome.png")
 
         default_splash = File.file?(File.join(assets_dir, "splash.png"))
         default_icon = File.file?(File.join(assets_dir, "icon.png"))
@@ -694,43 +948,235 @@ module Ruflet
           end
         end
 
-        has_splash = !splash.nil? || default_splash
-        has_icon = !icon.nil? || default_icon
+        # A project may configure nothing shared and declare everything under the
+        # platform sections, so a platform asset alone has to run the generators.
+        platform_splash = platforms.any? { |name, entry| PLATFORM_ASSET_SUPPORT.fetch(name)[:splash] && entry[:splash] }
+        platform_icon = platforms.any? { |name, entry| PLATFORM_ASSET_SUPPORT.fetch(name)[:icon] && entry[:icon] }
+
+        platforms.each do |name, entry|
+          support = PLATFORM_ASSET_SUPPORT.fetch(name)
+          if support[:splash] && entry[:splash].nil? && key_defined?(entry[:config], "splash_screen")
+            build_note("#{name}.splash_screen was set but the file was not found")
+          end
+          if support[:icon] && entry[:icon].nil? && key_defined?(entry[:config], "icon_launcher")
+            build_note("#{name}.icon_launcher was set but the file was not found")
+          end
+        end
+
+        shared_splash_asset = !splash.nil? || default_splash
+        shared_icon_asset = !icon.nil? || default_icon
+        has_splash = shared_splash_asset || platform_splash
+        has_icon = shared_icon_asset || platform_icon
+
+        # Fall back to whatever Android configured when nothing is shared.
+        effective_icon_background = icon_background || platforms.dig("android", :icon_background)
+        effective_theme_color = theme_color || platforms.dig("android", :theme_color)
 
         pubspec_path = File.join(client_dir, "pubspec.yaml")
         unless File.file?(pubspec_path)
           return { has_icon: has_icon, has_splash: has_splash, error: nil }
         end
 
+        ensure_pubspec_block(pubspec_path, "flutter_launcher_icons") if has_icon
+        ensure_pubspec_block(pubspec_path, "flutter_native_splash") if has_splash
+
         if has_icon
-          update_pubspec_value(pubspec_path, "flutter_launcher_icons", "image_path", "\"assets/icon.png\"", multiple: true)
+          if shared_icon_asset
+            update_pubspec_value(pubspec_path, "flutter_launcher_icons", "image_path", "\"assets/icon.png\"", multiple: true)
+          end
+          # Android 8+ renders adaptive icons. Without these keys flutter_launcher_icons
+          # never writes mipmap-anydpi-v26/, and the launcher falls back to the legacy
+          # bitmap, ignoring icon_background entirely.
+          update_pubspec_value(pubspec_path, "flutter_launcher_icons", "android", "launcher_icon", multiple: true)
+          adaptive_foreground_path =
+            if adaptive_foreground then "assets/icon_foreground.png"
+            elsif platforms.dig("android", :icon) then "assets/icon_android.png"
+            else "assets/icon.png"
+            end
+          update_pubspec_value(
+            pubspec_path, "flutter_launcher_icons", "adaptive_icon_foreground",
+            "\"#{adaptive_foreground_path}\"", multiple: true
+          )
+          adaptive_background_value =
+            if adaptive_background_image
+              "\"assets/icon_background.png\""
+            elsif adaptive_background_color
+              "\"#{adaptive_background_color}\""
+            end
+          if adaptive_background_value
+            update_pubspec_value(
+              pubspec_path, "flutter_launcher_icons", "adaptive_icon_background",
+              adaptive_background_value, multiple: true
+            )
+          end
+          if adaptive_monochrome
+            update_pubspec_value(
+              pubspec_path, "flutter_launcher_icons", "adaptive_icon_monochrome",
+              "\"assets/icon_monochrome.png\"", multiple: true
+            )
+          end
+          update_pubspec_value(pubspec_path, "flutter_launcher_icons", "min_sdk_android", android_min_sdk.to_s) if android_min_sdk
         end
-        update_pubspec_value(pubspec_path, "flutter_launcher_icons", "image_path_android", "\"assets/icon_android.png\"", multiple: true) if icon_android
-        update_pubspec_value(pubspec_path, "flutter_launcher_icons", "image_path_ios", "\"assets/icon_ios.png\"", multiple: true) if icon_ios
-        update_pubspec_value(pubspec_path, "flutter_launcher_icons", "image_path_web", "\"assets/icon_web.png\"", multiple: true) if icon_web
-        if icon_windows
-          ext = File.extname(icon_windows).downcase
-          value = ext == ".ico" ? "\"assets/icon_windows.ico\"" : "\"assets/icon_windows.png\""
-          update_pubspec_value(pubspec_path, "flutter_launcher_icons", "image_path_windows", value, multiple: true)
+        if has_icon
+          # flutter_launcher_icons takes android/ios as flat image_path_* keys but
+          # web/windows/macos as nested platform blocks.
+          if platforms.dig("android", :icon)
+            update_pubspec_value(pubspec_path, "flutter_launcher_icons", "image_path_android", "\"assets/icon_android.png\"", multiple: true)
+          end
+          if platforms.dig("ios", :icon)
+            update_pubspec_value(pubspec_path, "flutter_launcher_icons", "image_path_ios", "\"assets/icon_ios.png\"", multiple: true)
+          end
+          if (remove_alpha = first_defined(platforms.dig("ios", :config), "remove_alpha", "remove_alpha_ios"))
+            update_pubspec_value(pubspec_path, "flutter_launcher_icons", "remove_alpha_ios", remove_alpha ? "true" : "false")
+          end
+
+          %w[web windows macos].each do |name|
+            entry = platforms.fetch(name)
+            section = entry[:config]
+            next if entry[:icon].nil? && section.empty?
+
+            update_pubspec_nested_value(pubspec_path, "flutter_launcher_icons", name, "generate", "true")
+            if entry[:icon]
+              image = if name == "windows" && File.extname(entry[:icon]).downcase == ".ico"
+                "assets/icon_windows.ico"
+              else
+                "assets/icon_#{name}.png"
+              end
+              update_pubspec_nested_value(pubspec_path, "flutter_launcher_icons", name, "image_path", "\"#{image}\"")
+            end
+            if name == "web"
+              update_pubspec_nested_value(pubspec_path, "flutter_launcher_icons", "web", "background_color", "\"#{entry[:icon_background]}\"") if entry[:icon_background]
+              update_pubspec_nested_value(pubspec_path, "flutter_launcher_icons", "web", "theme_color", "\"#{entry[:theme_color]}\"") if entry[:theme_color]
+            end
+            if name == "windows" && (icon_size = section["icon_size"])
+              update_pubspec_nested_value(pubspec_path, "flutter_launcher_icons", "windows", "icon_size", icon_size.to_s)
+            end
+          end
         end
-        update_pubspec_value(pubspec_path, "flutter_launcher_icons", "image_path_macos", "\"assets/icon_macos.png\"", multiple: true) if icon_macos
-        update_pubspec_value(pubspec_path, "flutter_launcher_icons", "background_color", "\"#{icon_background}\"") if icon_background
-        update_pubspec_value(pubspec_path, "flutter_launcher_icons", "theme_color", "\"#{theme_color}\"") if theme_color
+        update_pubspec_value(pubspec_path, "flutter_launcher_icons", "background_color", "\"#{effective_icon_background}\"") if effective_icon_background
+        update_pubspec_value(pubspec_path, "flutter_launcher_icons", "theme_color", "\"#{effective_theme_color}\"") if effective_theme_color
 
-        update_pubspec_value(pubspec_path, "flutter_native_splash", "image", "\"assets/splash.png\"") if has_splash
+        update_pubspec_value(pubspec_path, "flutter_native_splash", "image", "\"assets/splash.png\"") if shared_splash_asset
         update_pubspec_value(pubspec_path, "flutter_native_splash", "image_dark", "\"assets/splash_dark.png\"") if splash_dark
         update_pubspec_value(pubspec_path, "flutter_native_splash", "color", "\"#{splash_color}\"") if splash_color
         update_pubspec_value(pubspec_path, "flutter_native_splash", "color_dark", "\"#{splash_dark_color}\"") if splash_dark_color
 
+        if has_splash
+          update_pubspec_value(pubspec_path, "flutter_native_splash", "background_image", "\"assets/splash_background.png\"") if splash_background_image
+          update_pubspec_value(pubspec_path, "flutter_native_splash", "background_image_dark", "\"assets/splash_background_dark.png\"") if splash_background_image_dark
+          update_pubspec_value(pubspec_path, "flutter_native_splash", "branding", "\"assets/splash_branding.png\"") if splash_branding
+          update_pubspec_value(pubspec_path, "flutter_native_splash", "branding_dark", "\"assets/splash_branding_dark.png\"") if splash_branding_dark
+          update_pubspec_value(pubspec_path, "flutter_native_splash", "branding_mode", splash_branding_mode.to_s) if splash_branding_mode
+          update_pubspec_value(pubspec_path, "flutter_native_splash", "branding_bottom_padding", splash_branding_padding.to_s) if splash_branding_padding
+        end
+
+        if has_splash
+          # flutter_native_splash only generates for android, ios, and web; each
+          # takes the shared keys suffixed with the platform name.
+          %w[android ios web].each do |name|
+            entry = platforms.fetch(name)
+            update_pubspec_value(pubspec_path, "flutter_native_splash", name, "true")
+            update_pubspec_value(pubspec_path, "flutter_native_splash", "image_#{name}", "\"assets/splash_#{name}.png\"") if entry[:splash]
+            update_pubspec_value(pubspec_path, "flutter_native_splash", "image_dark_#{name}", "\"assets/splash_#{name}_dark.png\"") if entry[:splash_dark]
+            if entry[:splash_color] && entry[:splash_color] != splash_color
+              update_pubspec_value(pubspec_path, "flutter_native_splash", "color_#{name}", "\"#{entry[:splash_color]}\"")
+            end
+            if entry[:splash_dark_color] && entry[:splash_dark_color] != splash_dark_color
+              update_pubspec_value(pubspec_path, "flutter_native_splash", "color_dark_#{name}", "\"#{entry[:splash_dark_color]}\"")
+            end
+            update_pubspec_value(pubspec_path, "flutter_native_splash", "background_image_#{name}", "\"assets/splash_background_#{name}.png\"") if entry[:background_image]
+            update_pubspec_value(pubspec_path, "flutter_native_splash", "background_image_dark_#{name}", "\"assets/splash_background_#{name}_dark.png\"") if entry[:background_image_dark]
+            update_pubspec_value(pubspec_path, "flutter_native_splash", "branding_#{name}", "\"assets/splash_branding_#{name}.png\"") if entry[:branding]
+            update_pubspec_value(pubspec_path, "flutter_native_splash", "branding_dark_#{name}", "\"assets/splash_branding_#{name}_dark.png\"") if entry[:branding_dark]
+          end
+
+          if (ios_content_mode = platforms.dig("ios", :config)["content_mode"] || platforms.dig("ios", :config)["ios_content_mode"])
+            update_pubspec_value(pubspec_path, "flutter_native_splash", "ios_content_mode", ios_content_mode.to_s)
+          end
+          if (web_image_mode = platforms.dig("web", :config)["image_mode"] || platforms.dig("web", :config)["web_image_mode"])
+            update_pubspec_value(pubspec_path, "flutter_native_splash", "web_image_mode", web_image_mode.to_s)
+          end
+          update_pubspec_value(pubspec_path, "flutter_native_splash", "fullscreen", android_splash_fullscreen ? "true" : "false") unless android_splash_fullscreen.nil?
+          update_pubspec_value(pubspec_path, "flutter_native_splash", "android_gravity", android_splash_gravity.to_s) if android_splash_gravity
+
+          # Android 12+ draws the splash itself and ignores the legacy `image`/`color`
+          # keys. Without an android_12 section the OS shows the launcher icon on a
+          # system background, so mirror the configured splash into it.
+          android_12_image =
+            if android_12_splash then "assets/splash_android_12.png"
+            elsif android_splash then "assets/splash_android.png"
+            else "assets/splash.png"
+            end
+          update_pubspec_nested_value(pubspec_path, "flutter_native_splash", "android_12", "image", "\"#{android_12_image}\"")
+          if android_12_icon_background
+            update_pubspec_nested_value(
+              pubspec_path, "flutter_native_splash", "android_12",
+              "icon_background_color", "\"#{android_12_icon_background}\""
+            )
+          end
+          android_12_image_dark =
+            if android_12_splash_dark then "assets/splash_android_12_dark.png"
+            elsif android_splash_dark then "assets/splash_android_dark.png"
+            elsif splash_dark then "assets/splash_dark.png"
+            end
+          if android_12_image_dark
+            update_pubspec_nested_value(
+              pubspec_path, "flutter_native_splash", "android_12",
+              "image_dark", "\"#{android_12_image_dark}\""
+            )
+          end
+          if android_12_icon_background_dark
+            update_pubspec_nested_value(
+              pubspec_path, "flutter_native_splash", "android_12",
+              "icon_background_color_dark", "\"#{android_12_icon_background_dark}\""
+            )
+          end
+          update_pubspec_nested_value(pubspec_path, "flutter_native_splash", "android_12", "color", "\"#{android_12_color}\"") if android_12_color
+          update_pubspec_nested_value(pubspec_path, "flutter_native_splash", "android_12", "color_dark", "\"#{android_12_color_dark}\"") if android_12_color_dark
+          if android_12_branding
+            copy_asset.call(android_12_branding, "splash_android_12_branding.png")
+            update_pubspec_nested_value(
+              pubspec_path, "flutter_native_splash", "android_12",
+              "branding", "\"assets/splash_android_12_branding.png\""
+            )
+          end
+        end
+
         {
           has_icon: has_icon,
           has_splash: has_splash,
           using_default_icon: using_default_icon,
           using_default_splash: using_default_splash,
+          android_adaptive_icon: has_icon,
+          android_12_splash: has_splash,
           error: nil
         }
       end
 
+      # Platform-specific overrides may live in a top-level `<platform>:` block,
+      # under `build.<platform>:`, or under `assets.<platform>:`. Later sources win.
+      def platform_build_config(config, platform)
+        name = platform.to_s
+        build = config["build"].is_a?(Hash) ? config["build"] : {}
+        assets = config["assets"].is_a?(Hash) ? config["assets"] : {}
+        [config[name], build[name], assets[name]].each_with_object({}) do |source, merged|
+          next unless source.is_a?(Hash)
+
+          source.each { |key, value| merged[key.to_s] = value }
+        end
+      end
+
+      # Like first_present, but keeps `false` — needed for boolean toggles.
+      def first_defined(hash, *keys)
+        return nil unless hash.is_a?(Hash)
+
+        keys.each do |key|
+          return hash[key] if hash.key?(key)
+          return hash[key.to_sym] if hash.key?(key.to_sym)
+        end
+        nil
+      end
+
       def sync_client_metadata(client_dir, config = {}, verbose: false)
         metadata = build_client_metadata(config, client_dir)
         apply_pubspec_metadata(client_dir, metadata)
@@ -744,21 +1190,30 @@ module Ruflet
           verbose,
           "app=#{metadata[:display_name]} package=#{metadata[:package_name]} org=#{metadata[:organization]} bundle=#{metadata[:bundle_identifier]}"
         )
+        metadata
       end
 
       def build_client_metadata(config, client_dir)
         app = config["app"].is_a?(Hash) ? config["app"] : {}
         current_pubspec = load_client_pubspec(client_dir)
         current_name = current_pubspec["name"].to_s
-        inferred_display_name = app["name"] || config["name"] || humanize_name(File.basename(Dir.pwd))
-        package_name = normalize_package_name(app["package_name"] || config["package_name"] || current_name || inferred_display_name)
-        display_name = first_present(app["display_name"], app["name"], config["display_name"], config["name"], humanize_name(package_name))
+        inferred_display_name = app["app_name"] || app["name"] || config["name"] || humanize_name(File.basename(Dir.pwd))
+        configured_app_name = first_present(app["app_name"], app["display_name"], app["name"])
+        package_source = first_present(app["package_name"], config["package_name"], configured_app_name)
+        package_source = current_name if package_source.nil?
+        package_name = normalize_package_name(package_source)
+        display_name = first_present(app["app_name"], app["display_name"], app["name"], config["display_name"], config["name"], humanize_name(package_name))
         organization = normalize_bundle_prefix(
           first_present(app["org"], app["organization"], config["org"], config["organization"], "com.example")
         )
         bundle_identifier = normalize_bundle_identifier(
           first_present(app["bundle_identifier"], config["bundle_identifier"], "#{organization}.#{package_name}")
         )
+        identity_errors = []
+        named = first_present(app["name"], app["app_name"], app["display_name"])
+        identity_errors << "app.name" if named.nil?
+        identity_errors << "app.package_name" if app["package_name"].to_s.strip.empty?
+        identity_errors << "app.organization" if first_present(app["organization"], app["org"]).nil?
 
         {
           package_name: package_name,
@@ -780,15 +1235,28 @@ module Ruflet
           linux_application_id: normalize_bundle_identifier(
             first_present(app["linux_application_id"], config["linux_application_id"], bundle_identifier)
           ),
-          short_name: first_present(app["short_name"], config["short_name"], display_name)
+          short_name: first_present(app["short_name"], config["short_name"], display_name),
+          mobile_identity_errors: identity_errors.uniq
         }
       end
 
+      def validate_mobile_app_identity(metadata, platform:)
+        return true unless %w[apk android aab ios].include?(platform.to_s)
+        return true unless metadata
+
+        errors = Array(metadata[:mobile_identity_errors])
+        return true if errors.empty?
+
+        warn "build config error: ruflet.yaml must define #{errors.join(', ')}"
+        warn "A mobile build needs app.name, app.package_name and app.organization."
+        false
+      end
+
       def load_client_pubspec(client_dir)
         pubspec_path = File.join(client_dir, "pubspec.yaml")
         return {} unless File.file?(pubspec_path)
 
-        YAML.safe_load(File.read(pubspec_path), aliases: true) || {}
+        YAML.safe_load(read_text_file(pubspec_path), aliases: true) || {}
       rescue StandardError
         {}
       end
@@ -797,7 +1265,7 @@ module Ruflet
         pubspec_path = File.join(client_dir, "pubspec.yaml")
         return unless File.file?(pubspec_path)
 
-        data = YAML.safe_load(File.read(pubspec_path), aliases: true) || {}
+        data = YAML.safe_load(read_text_file(pubspec_path), aliases: true) || {}
         data["name"] = metadata[:package_name]
         data["description"] = metadata[:description]
         data["version"] = metadata[:version]
@@ -805,28 +1273,6 @@ module Ruflet
       end
 
       def apply_android_metadata(client_dir, metadata)
-        gradle_path = File.join(client_dir, "android", "app", "build.gradle.kts")
-        replace_in_file(
-          gradle_path,
-          /^\s*namespace = ".*"$/,
-          %(    namespace = "#{metadata[:android_application_id]}")
-        )
-        replace_in_file(
-          gradle_path,
-          /^\s*applicationId = ".*"$/,
-          %(        applicationId = "#{metadata[:android_application_id]}")
-        )
-
-        Dir.glob(
-          File.join(client_dir, "android", "app", "src", "main", "kotlin", "**", "MainActivity.kt")
-        ).each do |activity_path|
-          replace_in_file(
-            activity_path,
-            /^package\s+[^\s]+$/,
-            "package #{metadata[:android_application_id]}"
-          )
-        end
-
         manifest_path = File.join(client_dir, "android", "app", "src", "main", "AndroidManifest.xml")
         replace_in_file(
           manifest_path,
@@ -835,6 +1281,33 @@ module Ruflet
         )
       end
 
+      # The signing team belongs to whoever ships the app, so it comes from the
+      # project rather than being baked into the client.
+      def apply_ios_signing_team(client_dir, config)
+        team = ios_signing_team(config)
+        pbxproj_path = File.join(client_dir, "ios", "Runner.xcodeproj", "project.pbxproj")
+        return unless File.file?(pbxproj_path)
+
+        if team.to_s.strip.empty?
+          build_note("No ios.team_id configured; Xcode will pick the signing team")
+          replace_in_file(pbxproj_path, /DEVELOPMENT_TEAM = [^;]*;/, "DEVELOPMENT_TEAM = \"\";")
+          return
+        end
+
+        replace_in_file(pbxproj_path, /DEVELOPMENT_TEAM = [^;]*;/, "DEVELOPMENT_TEAM = #{team};")
+        build_note("iOS signing team set to #{team}")
+      end
+
+      def ios_signing_team(config)
+        app = config["app"].is_a?(Hash) ? config["app"] : {}
+        first_present(
+          platform_build_config(config, "ios")["team_id"],
+          app["ios_team_id"],
+          app["team_id"],
+          ENV["RUFLET_IOS_TEAM_ID"]
+        )
+      end
+
       def apply_ios_metadata(client_dir, metadata)
         info_plist_path = File.join(client_dir, "ios", "Runner", "Info.plist")
         replace_plist_value(info_plist_path, "CFBundleDisplayName", metadata[:display_name])
@@ -843,17 +1316,37 @@ module Ruflet
         pbxproj_path = File.join(client_dir, "ios", "Runner.xcodeproj", "project.pbxproj")
         return unless File.file?(pbxproj_path)
 
-        content = File.read(pbxproj_path)
+        content = read_text_file(pbxproj_path)
         content.gsub!(/INFOPLIST_KEY_CFBundleDisplayName = "[^"]*";/, %(INFOPLIST_KEY_CFBundleDisplayName = "#{xcode_escape(metadata[:display_name])}";))
-        content.gsub!(/PRODUCT_BUNDLE_IDENTIFIER = ([^;]+);/) do |match|
-          identifier = Regexp.last_match(1).to_s.strip
-          if identifier.include?("RunnerTests")
-            match
-          else
-            "PRODUCT_BUNDLE_IDENTIFIER = #{metadata[:ios_bundle_identifier]};"
-          end
-        end
-        File.write(pbxproj_path, content)
+        write_text_file(pbxproj_path, content)
+      end
+
+      def apply_mobile_package_name(client_dir, metadata, platform:, tools:, verbose: false)
+        return true unless metadata
+
+        package_name, platform_flag = case platform.to_s
+        when "apk", "android", "aab"
+          [metadata[:android_application_id], "--android"]
+        when "ios"
+          [metadata[:ios_bundle_identifier], "--ios"]
+        else
+          return true
+        end
+
+        build_note("Applying #{platform_flag.delete_prefix('--')} package name #{package_name}")
+        build_log(verbose, "running change_app_package_name for #{package_name} #{platform_flag}")
+        ok = run_external_command(
+          tools[:env],
+          tools[:dart],
+          "run",
+          "change_app_package_name:main",
+          package_name,
+          platform_flag,
+          chdir: client_dir,
+          unbundled: true
+        )
+        warn "change_app_package_name failed for #{package_name}" unless ok
+        ok
       end
 
       def apply_macos_metadata(client_dir, metadata)
@@ -878,11 +1371,11 @@ module Ruflet
       def apply_web_metadata(client_dir, metadata)
         manifest_path = File.join(client_dir, "web", "manifest.json")
         if File.file?(manifest_path)
-          data = JSON.parse(File.read(manifest_path))
+          data = JSON.parse(read_text_file(manifest_path))
           data["name"] = metadata[:display_name]
           data["short_name"] = metadata[:short_name]
           data["description"] = metadata[:description]
-          File.write(manifest_path, JSON.pretty_generate(data) + "\n")
+          write_text_file(manifest_path, JSON.pretty_generate(data) + "\n")
         end
 
         index_path = File.join(client_dir, "web", "index.html")
@@ -947,23 +1440,34 @@ module Ruflet
         replace_in_file(cmake_path, /^set\(APPLICATION_ID ".*"\)$/, %(set(APPLICATION_ID "#{metadata[:linux_application_id]}")))
       end
 
+      # Native project files are UTF-8 and the values written into them are too
+      # (the macOS copyright line carries a ©). Reading them with the default
+      # external encoding fails outright under a non-UTF-8 locale, so pin it.
+      def read_text_file(path)
+        File.read(path, encoding: Encoding::UTF_8)
+      end
+
+      def write_text_file(path, content)
+        File.write(path, content, encoding: Encoding::UTF_8)
+      end
+
       def replace_plist_value(path, key, value)
         return unless File.file?(path)
 
-        content = File.read(path)
+        content = read_text_file(path)
         pattern = %r{(<key>#{Regexp.escape(key)}</key>\s*<string>)(.*?)(</string>)}m
         updated = content.gsub(pattern) do
           "#{Regexp.last_match(1)}#{xml_escape(value)}#{Regexp.last_match(3)}"
         end
-        File.write(path, updated) unless updated == content
+        write_text_file(path, updated) unless updated == content
       end
 
       def replace_in_file(path, pattern, replacement)
         return unless File.file?(path)
 
-        content = File.read(path)
+        content = read_text_file(path)
         updated = content.gsub(pattern) { replacement }
-        File.write(path, updated) unless updated == content
+        write_text_file(path, updated) unless updated == content
       end
 
       def first_present(*values)
@@ -1041,17 +1545,109 @@ module Ruflet
         extension_packages = extension_keys.filter_map { |key| CLIENT_EXTENSION_MAP[key]&.fetch(:package) }.uniq
         extension_aliases = extension_keys.filter_map { |key| CLIENT_EXTENSION_MAP[key]&.fetch(:alias) }.uniq
 
+        external = external_extension_entries(config)
+
         pubspec_path = File.join(client_dir, "pubspec.yaml")
         if File.file?(pubspec_path)
           sync_client_extension_dependencies(pubspec_path, extension_packages)
           prune_client_pubspec(pubspec_path, extension_packages)
+          sync_external_extension_dependencies(pubspec_path, external)
         end
         client_entrypoint_paths(client_dir).each do |entrypoint|
-          sync_client_main_extensions(entrypoint, extension_aliases) if File.file?(entrypoint)
-          prune_client_main(entrypoint, extension_aliases) if File.file?(entrypoint)
+          next unless File.file?(entrypoint)
+
+          sync_client_main_extensions(entrypoint, extension_aliases)
+          prune_client_main(entrypoint, extension_aliases)
+          sync_external_extension_registrations(entrypoint, external)
         end
       end
 
+      # An extension may name a package the template does not bundle, declared
+      # with the source to fetch it from:
+      #
+      #   extensions:
+      #     - charts
+      #     - my_package:
+      #         git:
+      #           url: https://github.com/owner/my_package
+      #           ref: main
+      #
+      # `branch` is accepted for `ref`, and `path` for a local checkout.
+      def external_extension_entries(config)
+        Array(config["extensions"]).filter_map do |entry|
+          next unless entry.is_a?(Hash)
+          next unless entry.size == 1
+
+          name, source = entry.first
+          package = name.to_s.strip
+          next if package.empty?
+
+          dependency = external_extension_dependency(source)
+          next unless dependency
+
+          { name: package, dependency: dependency }
+        end
+      end
+
+      def external_extension_dependency(source)
+        return nil unless source.is_a?(Hash)
+
+        normalized = source.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+        git = normalized["git"] || normalized["github"] || normalized["repository"]
+        git = normalized if git.nil? && normalized.key?("url")
+
+        if git.is_a?(String)
+          return { "git" => git }
+        elsif git.is_a?(Hash)
+          git = git.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+          url = git["url"].to_s.strip
+          return nil if url.empty?
+
+          spec = { "url" => url }
+          ref = (git["ref"] || git["branch"] || git["tag"]).to_s.strip
+          spec["ref"] = ref unless ref.empty?
+          path = git["path"].to_s.strip
+          spec["path"] = path unless path.empty?
+          return { "git" => spec }
+        end
+
+        local = normalized["path"]
+        return { "path" => local.to_s } if local.is_a?(String) && !local.to_s.strip.empty?
+
+        nil
+      end
+
+      def sync_external_extension_dependencies(pubspec_path, entries)
+        return if entries.empty?
+
+        data = YAML.safe_load(read_text_file(pubspec_path), aliases: true) || {}
+        dependencies = (data["dependencies"] || {}).dup
+        entries.each { |entry| dependencies[entry[:name]] = entry[:dependency] }
+        data["dependencies"] = dependencies
+        write_pubspec_yaml(pubspec_path, data)
+        build_note("Added #{entries.map { |e| e[:name] }.join(', ')} from the extension configuration")
+      end
+
+      # Flet extension packages expose an Extension class from a library named
+      # after the package, so the import and registration can be derived.
+      def sync_external_extension_registrations(path, entries)
+        return if entries.empty?
+
+        content = read_text_file(path)
+        original = content.dup
+
+        entries.each do |entry|
+          name = entry[:name]
+          import_line = %(import 'package:#{name}/#{name}.dart' as #{name};\n)
+          extension_line = "    #{name}.Extension(),\n"
+
+          content = insert_missing_import(content, import_line) unless content.include?("package:#{name}/#{name}.dart")
+          content = insert_missing_extension(content, extension_line) unless content.match?(/^\s*#{Regexp.escape(name)}\.Extension\(\),/)
+        end
+
+        write_text_file(path, content) unless content == original
+      end
+
       def configured_service_entries(config)
         Array(config["services"]).filter_map do |entry|
           case entry
@@ -1069,8 +1665,88 @@ module Ruflet
         end
       end
 
+      ANDROID_SIGNING_KEYS = {
+        "storeFile" => "RUFLET_ANDROID_KEYSTORE",
+        "storePassword" => "RUFLET_ANDROID_KEYSTORE_PASSWORD",
+        "keyAlias" => "RUFLET_ANDROID_KEY_ALIAS",
+        "keyPassword" => "RUFLET_ANDROID_KEY_PASSWORD"
+      }.freeze
+
+      # Release signing is read from the project, never from the managed client,
+      # so nobody has to edit build/client by hand. Either keep an
+      # android/key.properties beside the app, or set the RUFLET_ANDROID_*
+      # variables. Without one of those, Gradle falls back to the debug key.
+      def apply_android_signing_config(client_dir, platform, verbose: false)
+        return unless %w[apk android aab appbundle].include?(platform.to_s)
+
+        android_dir = File.join(client_dir, "android")
+        return unless Dir.exist?(android_dir)
+
+        destination = File.join(android_dir, "key.properties")
+        properties = android_signing_properties
+        if properties.empty?
+          File.delete(destination) if File.file?(destination)
+          build_note("No Android signing configured; the release build will use the debug key")
+          return
+        end
+
+        missing = ANDROID_SIGNING_KEYS.keys - properties.keys
+        unless missing.empty?
+          warn "build config error: Android signing is missing #{missing.join(', ')}"
+          warn "Set them in android/key.properties or the matching RUFLET_ANDROID_* variables."
+          return
+        end
+
+        body = ANDROID_SIGNING_KEYS.keys.map { |key| "#{key}=#{properties.fetch(key)}" }.join("\n")
+        write_text_file(destination, "#{body}\n")
+        build_log(verbose, "wrote #{destination}")
+        build_note("Android release signing configured from #{properties.fetch("_source")}")
+      end
+
+      def android_signing_properties
+        from_env = ANDROID_SIGNING_KEYS.each_with_object({}) do |(key, variable), out|
+          value = ENV[variable].to_s.strip
+          out[key] = value unless value.empty?
+        end
+        unless from_env.empty?
+          from_env["storeFile"] = File.expand_path(from_env["storeFile"]) if from_env["storeFile"]
+          return from_env.merge("_source" => "the RUFLET_ANDROID_* environment")
+        end
+
+        source = project_android_key_properties_path
+        return {} unless source
+
+        parsed = read_text_file(source).each_line.with_object({}) do |line, out|
+          next if line.strip.empty? || line.strip.start_with?("#")
+
+          key, value = line.split("=", 2)
+          out[key.to_s.strip] = value.to_s.strip unless value.nil?
+        end
+        return {} if parsed.empty?
+
+        # storeFile is written relative to the project; the client sits deeper.
+        if parsed["storeFile"] && !Pathname.new(parsed["storeFile"]).absolute?
+          parsed["storeFile"] = File.expand_path(parsed["storeFile"], File.dirname(source))
+        end
+        parsed.merge("_source" => source)
+      end
+
+      def project_android_key_properties_path
+        [
+          File.join(Dir.pwd, "android", "key.properties"),
+          File.join(Dir.pwd, "key.properties")
+        ].find { |path| File.file?(path) }
+      end
+
       def apply_native_service_permissions(client_dir, config)
         entries = configured_service_entries(config)
+        configured_extensions = Array(config["extensions"]).filter_map { |entry| normalize_extension_key(entry) }
+        extension_services = configured_extensions.flat_map do |extension|
+          EXTENSION_REQUIRED_SERVICES.fetch(extension, [])
+        end
+        extension_services.each do |service|
+          entries << { name: service, description: "" } unless entries.any? { |entry| entry[:name] == service }
+        end
         return if entries.empty?
 
         apply_android_service_permissions(client_dir, entries)
@@ -1081,20 +1757,20 @@ module Ruflet
         path = File.join(client_dir, "android", "app", "src", "main", "AndroidManifest.xml")
         return unless File.file?(path)
 
-        content = File.read(path)
+        content = read_text_file(path)
         entries.flat_map { |entry| ANDROID_SERVICE_PERMISSIONS.fetch(entry[:name], []) }.uniq.each do |permission|
           next if content.include?(%(android:name="#{permission}"))
 
           content.sub!(/<manifest\b[^>]*>\s*/, "\\0    <uses-permission android:name=\"#{permission}\"/>\n")
         end
-        File.write(path, content)
+        write_text_file(path, content)
       end
 
       def apply_ios_service_usage_descriptions(client_dir, entries)
         path = File.join(client_dir, "ios", "Runner", "Info.plist")
         return unless File.file?(path)
 
-        content = File.read(path)
+        content = read_text_file(path)
         entries.each do |entry|
           key = IOS_SERVICE_USAGE_KEYS[entry[:name]]
           next unless key
@@ -1110,7 +1786,7 @@ module Ruflet
             content.sub!(%r{</dict>\s*</plist>}m, "#{pair}</dict>\n</plist>")
           end
         end
-        File.write(path, content)
+        write_text_file(path, content)
       end
 
       def clear_flutter_build_state(client_dir, verbose: false)
@@ -1161,11 +1837,11 @@ module Ruflet
         pubspec_path = File.join(client_dir, "pubspec.yaml")
         return unless File.file?(pubspec_path)
 
-        data = YAML.safe_load(File.read(pubspec_path), aliases: true) || {}
+        data = YAML.safe_load(read_text_file(pubspec_path), aliases: true) || {}
         dependencies = data["dependencies"]
         dependencies = data["dependencies"] = {} unless dependencies.is_a?(Hash)
-        spinkit_dependency = template_client_pubspec_dependencies["flutter_spinkit"]
-        dependencies["flutter_spinkit"] = spinkit_dependency if spinkit_dependency
+        spinkit_dependency = template_client_pubspec_dependencies["flet_spinkit"]
+        dependencies["flet_spinkit"] = spinkit_dependency if spinkit_dependency
         flutter = data["flutter"]
         flutter = data["flutter"] = {} unless flutter.is_a?(Hash)
         assets = Array(flutter["assets"]).map(&:to_s)
@@ -1189,11 +1865,16 @@ module Ruflet
         write_pubspec_yaml(pubspec_path, data)
       end
 
+      # A self-contained build needs the embedded VM. Prefer a local checkout so
+      # the runtime under development is the one packaged, and otherwise resolve
+      # the published package.
+      PUBLISHED_RUBY_RUNTIME_CONSTRAINT = "^0.0.9"
+
       def ruby_runtime_dependency(current_dependency = nil)
         local_path = explicit_local_ruby_runtime_path || source_checkout_ruby_runtime_path
         return { "path" => local_path } if local_path
 
-        current_dependency || "^0.0.3"
+        current_dependency || PUBLISHED_RUBY_RUNTIME_CONSTRAINT
       end
 
       def explicit_local_ruby_runtime_path
@@ -1225,12 +1906,14 @@ module Ruflet
           "lib/main.self.dart",
           "lib/main.server.dart",
           "lib/ruflet_file_picker_service.dart",
-          "lib/ruflet_spinkit.dart",
           "lib/connection_probe.dart",
           "lib/connection_probe_io.dart",
           "lib/connection_probe_stub.dart",
           "ios/Podfile",
-          "windows/CMakeLists.txt"
+          "windows/CMakeLists.txt",
+          # Release signing lives here; an existing client would otherwise keep
+          # signing release builds with the debug key.
+          "android/app/build.gradle.kts"
         ]
 
         managed_files.each do |relative_path|
@@ -1250,7 +1933,7 @@ module Ruflet
 
         content = indent_pubspec_sequences(content)
 
-        File.write(path, content)
+        write_text_file(path, content)
       end
 
       def indent_pubspec_sequences(content)
@@ -1352,6 +2035,8 @@ module Ruflet
           .vscode
           build
           coverage
+          credentials
+          fastlane
           log
           node_modules
           pkg
@@ -1364,10 +2049,30 @@ module Ruflet
         end
       end
 
+      # Anything embedded here is readable by anyone who unpacks the shipped
+      # app, so signing keys and local environment files must never be copied
+      # in even when a project keeps them beside its source.
+      SECRET_ASSET_EXTENSIONS = %w[.p8 .p12 .pem .key .jks .keystore .mobileprovision].freeze
+      SECRET_ASSET_BASENAMES = %w[.env .netrc key.properties].freeze
+
+      def secret_project_asset?(relative)
+        basename = File.basename(relative)
+        return true if SECRET_ASSET_BASENAMES.include?(basename)
+        return true if basename.start_with?(".env.") && basename != ".env.example"
+        return true if SECRET_ASSET_EXTENSIONS.include?(File.extname(basename).downcase)
+        return true if basename.match?(/\Agoogle-play.*\.json\z/i)
+
+        false
+      end
+
       def include_project_asset_file?(relative)
         basename = File.basename(relative)
         return false if basename == ".DS_Store"
         return false if %w[Gemfile.lock pubspec.lock Podfile.lock package-lock.json yarn.lock pnpm-lock.yaml].include?(basename)
+        if secret_project_asset?(relative)
+          build_note("Excluded #{relative} from the embedded project; it looks like a credential")
+          return false
+        end
         true
       end
 
@@ -1398,12 +2103,13 @@ module Ruflet
 
         key.tr!("-", "_")
         key.gsub!(/\A(flet_)+/, "")
+        key.gsub!(/\A(ruflet_)+/, "")
         key.gsub!(/\Aservice_/, "")
         key
       end
 
       def prune_client_pubspec(path, selected_packages)
-        data = YAML.safe_load(File.read(path), aliases: true) || {}
+        data = YAML.safe_load(read_text_file(path), aliases: true) || {}
         deps = (data["dependencies"] || {}).dup
         optional_packages = CLIENT_EXTENSION_MAP.values.map { |entry| entry.fetch(:package) }.uniq
 
@@ -1424,7 +2130,7 @@ module Ruflet
         template_deps = template_client_pubspec_dependencies
         return if template_deps.empty?
 
-        data = YAML.safe_load(File.read(path), aliases: true) || {}
+        data = YAML.safe_load(read_text_file(path), aliases: true) || {}
         deps = (data["dependencies"] || {}).dup
         selected_packages.each do |package_name|
           deps[package_name] = template_deps[package_name] if template_deps.key?(package_name)
@@ -1444,7 +2150,7 @@ module Ruflet
         pubspec_path = File.join(template_root, "pubspec.yaml")
         return {} unless File.file?(pubspec_path)
 
-        data = YAML.safe_load(File.read(pubspec_path), aliases: true) || {}
+        data = YAML.safe_load(read_text_file(pubspec_path), aliases: true) || {}
         deps = data["dependencies"]
         deps.is_a?(Hash) ? deps : {}
       rescue StandardError
@@ -1457,8 +2163,8 @@ module Ruflet
         template_path = template_client_entrypoint_path(File.basename(path))
         return unless template_path
 
-        content = File.read(path)
-        template = File.read(template_path)
+        content = read_text_file(path)
+        template = read_text_file(template_path)
 
         selected_aliases.each do |extension_alias|
           import_line = template.lines.find { |line| line.match?(/\sas #{Regexp.escape(extension_alias)};\s*\z/) }
@@ -1470,7 +2176,7 @@ module Ruflet
           content = insert_missing_extension(content, extension_line) if extension_line && !content.include?(extension_line)
         end
 
-        File.write(path, content)
+        write_text_file(path, content)
       end
 
       def template_client_entrypoint_path(name)
@@ -1508,7 +2214,7 @@ module Ruflet
       end
 
       def prune_client_main(path, selected_aliases)
-        content = File.read(path)
+        content = read_text_file(path)
         alias_to_package = {}
         optional_aliases = CLIENT_EXTENSION_MAP.values.map { |entry| entry.fetch(:alias) }.uniq
 
@@ -1547,11 +2253,58 @@ module Ruflet
           end
         end
 
-        File.write(path, content)
+        write_text_file(path, content)
+      end
+
+      # update_pubspec_value only rewrites blocks that already exist. Create the
+      # block first so a template without it still receives the configured values.
+      def ensure_pubspec_block(path, block)
+        return unless File.file?(path)
+
+        content = read_text_file(path)
+        return if content.lines.any? { |line| line.start_with?("#{block}:") }
+
+        content += "\n" unless content.empty? || content.end_with?("\n")
+        write_text_file(path, "#{content}#{block}:\n")
+      end
+
+      # Writes `block: -> section: -> key: value`, creating the block and the
+      # nested section when they are missing (for example flutter_native_splash's
+      # android_12 section).
+      def update_pubspec_nested_value(path, block, section, key, value)
+        return unless File.file?(path)
+
+        ensure_pubspec_block(path, block)
+        lines = read_text_file(path).split("\n", -1)
+        block_start = lines.index { |line| line.start_with?("#{block}:") }
+        return unless block_start
+
+        block_end = block_start + 1
+        block_end += 1 while block_end < lines.length && (lines[block_end].strip.empty? || lines[block_end].start_with?(" ", "\t"))
+        block_end -= 1 while block_end > block_start + 1 && lines[block_end - 1].strip.empty?
+
+        section_index = (block_start + 1...block_end).find do |index|
+          lines[index] =~ /\A\s{2}#{Regexp.escape(section)}:\s*(#.*)?\z/
+        end
+
+        if section_index.nil?
+          lines.insert(block_end, "  #{section}:", "    #{key}: #{value}")
+        else
+          section_end = section_index + 1
+          section_end += 1 while section_end < block_end && lines[section_end] =~ /\A\s{3,}\S/
+          existing = (section_index + 1...section_end).find { |index| lines[index].strip.start_with?("#{key}:") }
+          if existing
+            lines[existing] = "#{lines[existing][/\A\s*/]}#{key}: #{value}"
+          else
+            lines.insert(section_end, "    #{key}: #{value}")
+          end
+        end
+
+        write_text_file(path, indent_pubspec_sequences(lines.join("\n")))
       end
 
       def update_pubspec_value(path, block, key, value, multiple: false)
-        lines = File.read(path).split("\n", -1)
+        lines = read_text_file(path).split("\n", -1)
         out = []
         in_block = false
         replaced = false
@@ -1586,7 +2339,7 @@ module Ruflet
         if in_block && !replaced
           out << "#{block_indent}#{key}: #{value}"
         end
-        File.write(path, indent_pubspec_sequences(out.join("\n")))
+        write_text_file(path, indent_pubspec_sequences(out.join("\n")))
       end
 
       def flutter_build_command(platform)
@@ -1597,6 +2350,8 @@ module Ruflet
           ["build", "appbundle"]
         when "ios"
           ["build", "ios"]
+        when "ipa"
+          ["build", "ipa"]
         when "web"
           ["build", "web"]
         when "macos"