ruflet 0.0.20 → 0.0.22

data/lib/ruflet/cli/build_command.rb

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require "find"
+require "digest"
 require "json"
 require "open3"
 require "pathname"
@@ -14,23 +15,49 @@ module Ruflet
     module BuildCommand
       include FlutterSdk
       CLIENT_EXTENSION_MAP = {
-        "audio" => { package: "flet_audio", alias: "ruflet_audio" },
-        "audio_recorder" => { package: "flet_audio_recorder", alias: "ruflet_audio_recorder" },
-        "camera" => { package: "flet_camera", alias: "ruflet_camera" },
-        "charts" => { package: "flet_charts", alias: "ruflet_charts" },
-        "code_editor" => { package: "flet_code_editor", alias: "ruflet_code_editor" },
-        "color_pickers" => { package: "flet_color_pickers", alias: "ruflet_color_picker" },
-        "datatable2" => { package: "flet_datatable2", alias: "ruflet_datatable2" },
-        "flashlight" => { package: "flet_flashlight", alias: "ruflet_flashlight" },
-        "geolocator" => { package: "flet_geolocator", alias: "ruflet_geolocator" },
-        "lottie" => { package: "flet_lottie", alias: "ruflet_lottie" },
-        "map" => { package: "flet_map", alias: "ruflet_map" },
-        "permission_handler" => { package: "flet_permission_handler", alias: "ruflet_permission_handler" },
+        "ads" => { package: "ruflet_ads", alias: "ruflet_ads" },
+        "audio" => { package: "ruflet_audio", alias: "ruflet_audio" },
+        "audio_recorder" => { package: "ruflet_audio_recorder", alias: "ruflet_audio_recorder" },
+        "camera" => { package: "ruflet_camera", alias: "ruflet_camera" },
+        "charts" => { package: "ruflet_charts", alias: "ruflet_charts" },
+        "code_editor" => { package: "ruflet_code_editor", alias: "ruflet_code_editor" },
+        "color_pickers" => { package: "ruflet_color_pickers", alias: "ruflet_color_picker" },
+        "datatable2" => { package: "ruflet_datatable2", alias: "ruflet_datatable2" },
+        "flashlight" => { package: "ruflet_flashlight", alias: "ruflet_flashlight" },
+        "geolocator" => { package: "ruflet_geolocator", alias: "ruflet_geolocator" },
+        "lottie" => { package: "ruflet_lottie", alias: "ruflet_lottie" },
+        "map" => { package: "ruflet_map", alias: "ruflet_map" },
+        "permission_handler" => { package: "ruflet_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" },
-        "webview" => { package: "flet_webview", alias: "ruflet_webview" }
+        "rive" => { package: "ruflet_rive", alias: "ruflet_rive" },
+        "secure_storage" => { package: "ruflet_secure_storage", alias: "ruflet_secure_storage" },
+        "spinkit" => { package: "ruflet_spinkit", alias: "ruflet_spinkit" },
+        "video" => { package: "ruflet_video", alias: "ruflet_video" },
+        "webview" => { package: "ruflet_webview", alias: "ruflet_webview" }
+      }.freeze
+      # Native Swift products matching the Ruflet extensions selected by the
+      # ordinary Ruflet build configuration. The same resolved extension keys
+      # drive Dart imports, Swift imports/registration, and Xcode linkage.
+      NATIVE_APPLE_EXTENSION_MAP = {
+        "ads" => { module: "RufletAds", initializer: "RufletAds.Extension()" },
+        "audio" => { module: "RufletAudio", initializer: "RufletAudioExtension()" },
+        "audio_recorder" => { module: "RufletAudioRecorder", initializer: "RufletAudioRecorderExtension()" },
+        "camera" => { module: "RufletCamera", initializer: "RufletCameraExtension()" },
+        "charts" => { module: "RufletCharts", initializer: "RufletChartsExtension()" },
+        "code_editor" => { module: "RufletCodeEditor", initializer: "RufletCodeEditorExtension()" },
+        "color_pickers" => { module: "RufletColorPickers", initializer: "RufletColorPickersExtension()" },
+        "datatable2" => { module: "RufletDataTable2", initializer: "RufletDataTable2Extension()" },
+        "flashlight" => { module: "RufletFlashlight", initializer: "RufletFlashlightExtension()" },
+        "geolocator" => { module: "RufletGeolocator", initializer: "RufletGeolocatorExtension()" },
+        "lottie" => { module: "RufletLottie", initializer: "RufletLottieExtension()" },
+        "map" => { module: "RufletMap", initializer: "RufletMap.Extension()" },
+        "permission_handler" => { module: "RufletPermissionHandler", initializer: "RufletPermissionHandlerExtension()" },
+        "qrcode_scanner" => { module: "RufletQRScanner", initializer: "RufletQRScannerExtension()" },
+        "rive" => { module: "RufletRive", initializer: "RufletRiveExtension()" },
+        "secure_storage" => { module: "RufletSecureStorage", initializer: "RufletSecureStorageExtension()" },
+        "spinkit" => { module: "RufletSpinKit", initializer: "RufletSpinKitExtension()" },
+        "video" => { module: "RufletVideo", initializer: "RufletVideoExtension()" },
+        "webview" => { module: "RufletWebView", initializer: "RufletWebViewExtension()" }
       }.freeze
       PROTECTED_SERVICE_EXTENSIONS = {
         "camera" => %w[camera permission_handler],
@@ -39,8 +66,22 @@ module Ruflet
         "motion" => %w[permission_handler]
       }.freeze
       EXTENSION_REQUIRED_SERVICES = {
+        "audio_recorder" => %w[microphone],
+        "camera" => %w[camera],
+        "flashlight" => %w[camera],
+        "geolocator" => %w[location],
         "qrcode_scanner" => %w[camera]
       }.freeze
+      MANAGED_EXTENSION_STATE_PATH = File.join(".ruflet", "extension_dependencies.json")
+      RUFLET_SOURCE_INTEGRITY_PATH = File.join(
+        "tool", "conformance", "ruflet_source_integrity.json"
+      ).freeze
+      RUFLET_SOURCE_IGNORED_DIRECTORIES = %w[
+        .git .dart_tool .cache build .pub-cache .idea .vscode coverage
+      ].freeze
+      RUFLET_SOURCE_IGNORED_FILES = %w[
+        pubspec.lock .DS_Store .flutter-plugins .flutter-plugins-dependencies
+      ].freeze
       ANDROID_SERVICE_PERMISSIONS = {
         "camera" => %w[android.permission.CAMERA],
         "microphone" => %w[android.permission.RECORD_AUDIO],
@@ -50,9 +91,34 @@ module Ruflet
       IOS_SERVICE_USAGE_KEYS = {
         "camera" => "NSCameraUsageDescription",
         "microphone" => "NSMicrophoneUsageDescription",
-        "location" => "NSLocationWhenInUseUsageDescription",
+        "location" => %w[
+          NSLocationWhenInUseUsageDescription
+          NSLocationAlwaysAndWhenInUseUsageDescription
+        ],
+        "motion" => "NSMotionUsageDescription",
+        "photo_library" => "NSPhotoLibraryUsageDescription"
+      }.freeze
+      MACOS_SERVICE_USAGE_KEYS = {
+        "camera" => "NSCameraUsageDescription",
+        "microphone" => "NSMicrophoneUsageDescription",
+        "location" => "NSLocationUsageDescription",
         "motion" => "NSMotionUsageDescription"
       }.freeze
+      MACOS_SERVICE_ENTITLEMENTS = {
+        "camera" => "com.apple.security.device.camera",
+        "microphone" => "com.apple.security.device.audio-input",
+        "location" => "com.apple.security.personal-information.location"
+      }.freeze
+      MANAGED_ANDROID_PERMISSIONS = (
+        ANDROID_SERVICE_PERMISSIONS.values.flatten +
+        %w[android.permission.FLASHLIGHT android.permission.MODIFY_AUDIO_SETTINGS]
+      ).uniq.freeze
+      MANAGED_IOS_USAGE_KEYS = (
+        IOS_SERVICE_USAGE_KEYS.values.flatten +
+        %w[NSLocationAlwaysAndWhenInUseUsageDescription NSPhotoLibraryUsageDescription]
+      ).uniq.freeze
+      MANAGED_MACOS_USAGE_KEYS = MACOS_SERVICE_USAGE_KEYS.values.uniq.freeze
+      MANAGED_MACOS_SERVICE_ENTITLEMENTS = MACOS_SERVICE_ENTITLEMENTS.values.uniq.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
@@ -68,12 +134,36 @@ module Ruflet
         "linux" => { splash: false, icon: false }
       }.freeze
 
+      EMBEDDED_RUNTIME_PROFILES = %i[lite full].freeze
+      FULL_RUNTIME_MANIFEST = "ruflet-full-runtime.json"
+      FULL_RUNTIME_BUNDLE_SCHEMA = 3
+
       def command_build(args)
-        self_contained = args.delete("--self")
+        self_contained_flag = args.delete("--self")
+        lite = args.delete("--lite")
+        full = args.delete("--full")
+        if lite && full
+          warn "build config error: --lite and --full are mutually exclusive"
+          return 1
+        end
+        # --self enables the embedded runtime and defaults its profile to lite.
+        # An explicit profile still wins, so --self --full selects full CRuby.
+        self_contained = self_contained_flag || lite || full
+        runtime_profile = full ? :full : :lite
+        @ruflet_runtime_profile = self_contained ? runtime_profile : :server
+        @ruflet_runtime_profile_explicit = !!(lite || full)
+        experimental = args.delete("--experimental")
+        experimental_alias = args.delete("--exp")
+        experimental ||= experimental_alias
         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> [--lite|--full|--self] [--experimental|--exp] [--verbose]"
+          return 1
+        end
+
+        if experimental && !%w[ios ipa macos].include?(platform)
+          warn "build config error: --experimental is supported only for ios and macos"
           return 1
         end
 
@@ -83,11 +173,19 @@ 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"
+        @ruflet_build_platform = platform
+        @ruflet_experimental_native_renderer = !!experimental
+
         # 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"
+          profile_flag = @ruflet_runtime_profile_explicit ? "--#{runtime_profile}" : "--self"
+          warn "build config error: #{profile_flag} is not supported for web"
           warn "A web client runs no embedded Ruby; build it with `ruflet build web`."
           return 1
         end
@@ -100,8 +198,13 @@ module Ruflet
           return 1
         end
 
-        build_note("Preparing #{platform} build (#{self_contained ? 'self-contained' : 'server-driven'})")
+        renderer = experimental ? ", experimental native renderer" : ""
+        mode = self_contained ? "self-contained #{runtime_profile}" : "server-driven"
+        build_note("Preparing #{platform} build (#{mode}#{renderer})")
         config = load_ruflet_config
+        if runtime_profile == :full && self_contained
+          return 1 unless configure_full_runtime_distribution(config, platform, verbose: !!verbose)
+        end
         tools = ensure_flutter!("build", client_dir: client_dir)
         command_env = build_tool_env(tools[:env], platform, client_dir)
         ok = prepare_flutter_client(
@@ -115,16 +218,18 @@ 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)
         if self_contained
-          build_args += ["--dart-define", "RUFLET_BACKEND_URL=#{backend_url}"] if backend_url
-          # Pin the embedded project so main.self.dart extracts assets/<name>/
-          # deterministically instead of inferring from a single main.rb — the
-          # app tree now ships many main.rb files (standalone_apps/*/main.rb).
+          # Pin the embedded project for platform autostart instead of asking
+          # the native layer to infer it from every main.rb/main.mrb in the
+          # bundled asset tree.
           build_args += ["--dart-define", "RUFLET_EMBEDDED_PROJECT=#{self_contained_project_name}"]
+          if @ruflet_runtime_profile_explicit
+            build_args += ["--dart-define", "RUFLET_RUNTIME_PROFILE=#{runtime_profile}"]
+          end
         elsif backend_url
           build_args += ["--dart-define", "RUFLET_BACKEND_URL=#{backend_url}"]
         elsif RUNTIME_RESOLVED_BACKEND_PLATFORMS.include?(platform)
@@ -138,10 +243,18 @@ module Ruflet
           warn "Set app.backend_url or backend_url in ruflet.yaml"
           return 1
         end
+        if experimental
+          build_args += ["--dart-define", "RUFLET_EXPERIMENTAL_NATIVE_RENDERER=true"]
+        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'}")
+        logged_mode = if self_contained
+          @ruflet_runtime_profile_explicit ? runtime_profile : "self"
+        else
+          "server"
+        end
+        build_log(verbose, "mode=#{logged_mode}")
         build_log(verbose, "client_dir=#{client_dir}")
         build_log(verbose, "flutter=#{tools[:flutter]}")
         build_log(verbose, "dart=#{tools[:dart]}")
@@ -150,6 +263,26 @@ module Ruflet
 
         build_note("Running Flutter #{build_args.join(' ')}")
         ok = run_external_command(command_env, tools[:flutter], *build_args, chdir: client_dir, unbundled: true)
+
+        # A physical iPhone app and a simulator app are different Apple
+        # products, but Ruflet users should not have to learn that distinction.
+        # Keep both outputs behind the ordinary self-contained iOS build so the
+        # following `ruflet install` can target whichever mobile device is
+        # connected. An explicit --simulator remains a simulator-only build.
+        if ok && self_contained && requested_platform == "ios" &&
+            !build_args.include?("--simulator") && !full_runtime_device_only?
+          simulator_args = build_args.dup
+          simulator_args.delete("--codesign")
+          simulator_args.insert(simulator_args.index("ios") + 1, "--simulator")
+          stage_ios_simulator_ruby_runtime(client_dir, simulator_args, verbose: !!verbose)
+          build_log(verbose, "command=#{([tools[:flutter]] + simulator_args).join(' ')}")
+          build_note("Running Flutter #{simulator_args.join(' ')}")
+          ok = run_external_command(
+            command_env, tools[:flutter], *simulator_args,
+            chdir: client_dir, unbundled: true
+          )
+        end
+
         export_platform_build_outputs(client_dir, platform, verbose: !!verbose) if ok
         ok ? 0 : 1
       end
@@ -193,6 +326,10 @@ module Ruflet
 
       private
 
+      def experimental_native_renderer?
+        @ruflet_experimental_native_renderer == true
+      end
+
       def extract_option_value!(args, *flags)
         flags.each do |flag|
           index = args.index(flag)
@@ -208,6 +345,15 @@ module Ruflet
       def ensure_flutter_client_dir(verbose: false)
         client_dir = detect_flutter_client_dir
         if client_dir
+          if File.expand_path(client_dir) == File.expand_path(hidden_flutter_client_dir) &&
+              !valid_flutter_client_root?(client_dir) &&
+              !File.file?(File.join(client_dir, ".metadata"))
+            if Ruflet::CLI.respond_to?(:copy_ruflet_client_template, true)
+              Ruflet::CLI.send(:copy_ruflet_client_template, Dir.pwd)
+              client_dir = hidden_flutter_client_dir
+              build_log(verbose, "repaired invalid managed Flutter client root")
+            end
+          end
           refresh_hidden_flutter_client_template(client_dir, verbose: verbose)
           return client_dir
         end
@@ -217,6 +363,11 @@ module Ruflet
         bootstrapped
       end
 
+      def valid_flutter_client_root?(path)
+        File.file?(File.join(path, "pubspec.yaml")) &&
+          File.file?(File.join(path, "lib", "main.dart"))
+      end
+
       def refresh_hidden_flutter_client_template(client_dir, verbose: false)
         return unless File.expand_path(client_dir) == File.expand_path(hidden_flutter_client_dir)
         return unless File.file?(File.join(client_dir, ".metadata"))
@@ -432,15 +583,42 @@ module Ruflet
       end
 
       def prepare_flutter_client(client_dir, platform:, tools:, config:, self_contained: false, verbose: false)
-        refresh_managed_client_template_files(client_dir, verbose: verbose)
+        refreshed = refresh_managed_client_template_files(
+          client_dir, platform: platform, verbose: verbose)
+        return false if refreshed == false
+        unless configure_apple_renderer_integration(
+          client_dir, platform: platform, enabled: experimental_native_renderer?,
+          verbose: verbose)
+          return false
+        end
+        if experimental_native_renderer?
+          sync_application_apple_extensions(
+            client_dir, platform: platform, verbose: verbose)
+        end
         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
+        configure_native_apple_runtime(
+          client_dir, platform: platform, self_contained: self_contained,
+          config: config, experimental: experimental_native_renderer?, verbose: verbose)
+        configure_android_runtime(
+          client_dir, platform: platform, self_contained: self_contained,
+          verbose: verbose)
         @ruflet_self_contained_build = self_contained
-        apply_service_extension_config(client_dir, config)
+        extension_keys = apply_service_extension_config(client_dir, config)
+        if @ruflet_extension_selection_applied && !validate_flutter_extension_selection(client_dir)
+          return false
+        end
+        if experimental_native_renderer?
+          apply_native_apple_extension_config(
+            client_dir, platform: platform, extension_keys: extension_keys,
+            verbose: verbose)
+        end
         asset_flags = apply_build_config(client_dir, config)
         if asset_flags[:error]
           warn asset_flags[:error]
@@ -458,6 +636,9 @@ module Ruflet
           warn "flutter pub get failed"
           return false
         end
+        if @ruflet_extension_selection_applied && !validate_local_ruflet_packages(client_dir)
+          return false
+        end
 
         unless apply_mobile_package_name(client_dir, metadata, platform: platform, tools: tools, verbose: verbose)
           return false
@@ -594,7 +775,11 @@ module Ruflet
         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
+        runtime_root = if embedded_runtime_profile == :full
+          @ruflet_full_runtime_path
+        else
+          explicit_local_ruby_runtime_path || source_checkout_ruby_runtime_path
+        end
         return true unless runtime_root
 
         source = File.join(
@@ -740,8 +925,11 @@ module Ruflet
         if File.file?(services_path)
           service_config = YAML.safe_load(read_text_file(services_path), aliases: true) || {}
           if service_config["app"].is_a?(Hash)
-            config["app"] = (config["app"].is_a?(Hash) ? config["app"] : {}).merge(service_config["app"])
-            config["_app_identity_source"] = "services.yaml"
+            # 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
@@ -1200,10 +1388,10 @@ module Ruflet
           first_present(app["bundle_identifier"], config["bundle_identifier"], "#{organization}.#{package_name}")
         )
         identity_errors = []
-        identity_errors << "app.app_name" if app["app_name"].to_s.strip.empty?
+        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 app["organization"].to_s.strip.empty?
-        identity_errors << "services.yaml app section" unless config["_app_identity_source"] == "services.yaml"
+        identity_errors << "app.organization" if first_present(app["organization"], app["org"]).nil?
 
         {
           package_name: package_name,
@@ -1216,10 +1404,10 @@ module Ruflet
           android_application_id: normalize_bundle_identifier(
             first_present(app["android_application_id"], config["android_application_id"], bundle_identifier)
           ),
-          ios_bundle_identifier: normalize_bundle_identifier(
+          ios_bundle_identifier: normalize_apple_bundle_identifier(
             first_present(app["ios_bundle_identifier"], config["ios_bundle_identifier"], bundle_identifier)
           ),
-          macos_bundle_identifier: normalize_bundle_identifier(
+          macos_bundle_identifier: normalize_apple_bundle_identifier(
             first_present(app["macos_bundle_identifier"], config["macos_bundle_identifier"], bundle_identifier)
           ),
           linux_application_id: normalize_bundle_identifier(
@@ -1237,8 +1425,8 @@ module Ruflet
         errors = Array(metadata[:mobile_identity_errors])
         return true if errors.empty?
 
-        warn "build config error: services.yaml must define #{errors.join(', ')}"
-        warn "Set app.app_name, app.package_name, and app.organization before building a mobile app."
+        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
 
@@ -1271,6 +1459,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])
@@ -1471,6 +1686,20 @@ module Ruflet
         segments.join(".")
       end
 
+      def normalize_apple_bundle_identifier(value)
+        segments = value.to_s.strip.downcase.split(".").map do |segment|
+          normalized = segment.gsub(/[^a-z0-9-]+/, "-")
+          normalized.gsub!(/\A-+|-+\z/, "")
+          normalized.gsub!(/-+/, "-")
+          normalized = "app" if normalized.empty?
+          normalized = "app-#{normalized}" if normalized.match?(/\A\d/)
+          normalized
+        end
+        segments.reject!(&:empty?)
+        segments = %w[com example app] if segments.empty?
+        segments.join(".")
+      end
+
       def humanize_name(name)
         name.to_s.gsub(/[_-]+/, " ").split.map(&:capitalize).join(" ")
       end
@@ -1501,22 +1730,218 @@ module Ruflet
       end
 
       def apply_service_extension_config(client_dir, config = {}, self_contained: @ruflet_self_contained_build)
-        services = configured_service_entries(config).map { |entry| entry[:name] }
-        requested_extensions = Array(config["extensions"]).map { |value| normalize_extension_key(value) }.compact
-        protected_extensions = services.flat_map { |name| PROTECTED_SERVICE_EXTENSIONS.fetch(name, []) }
-        extension_keys = (requested_extensions + protected_extensions + services).uniq
-        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
+        extension_keys = configured_extension_keys(config)
+        # The experimental Apple host renders these extensions in Swift. Keep
+        # the resolved keys for native registration, but do not also ship the
+        # equivalent Dart plugins and their native Flutter frameworks.
+        flutter_extension_keys = experimental_native_renderer? ? [] : extension_keys
+        extension_packages = flutter_extension_keys.filter_map { |key| CLIENT_EXTENSION_MAP[key]&.fetch(:package) }.uniq
+        extension_aliases = flutter_extension_keys.filter_map { |key| CLIENT_EXTENSION_MAP[key]&.fetch(:alias) }.uniq
+
+        configured_external = external_extension_entries(config)
+        external = experimental_native_renderer? ? [] : configured_external
+        previous_external_names = managed_external_extension_names(client_dir)
+        discovered_external_names = discover_registered_external_extension_names(client_dir)
+        removable_external_names = (
+          previous_external_names + discovered_external_names + configured_external.map { |entry| entry[:name] }
+        ).uniq
 
         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,
+            managed_names: removable_external_names
+          )
         end
+        sync_client_package_directories(client_dir, extension_packages)
         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)
+          prune_external_extension_registrations(
+            entrypoint,
+            removable_external_names - external.map { |entry| entry[:name] }
+          )
+          sync_external_extension_registrations(entrypoint, external)
         end
+        write_managed_external_extension_names(client_dir, external.map { |entry| entry[:name] })
+        @ruflet_selected_flutter_extension_packages = extension_packages
+        @ruflet_selected_external_extension_packages = external.map { |entry| entry[:name] }
+        @ruflet_managed_external_extension_packages = removable_external_names
+        @ruflet_extension_selection_applied = true
+        if experimental_native_renderer? && (!extension_keys.empty? || !configured_external.empty?)
+          build_note("Native Apple extensions selected; excluded equivalent Flutter plugins from the app bundle")
+        end
+        extension_keys
+      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, managed_names: [])
+        data = YAML.safe_load(read_text_file(pubspec_path), aliases: true) || {}
+        dependencies = (data["dependencies"] || {}).dup
+        selected_names = entries.map { |entry| entry[:name] }
+        Array(managed_names).each do |name|
+          dependencies.delete(name) unless selected_names.include?(name)
+        end
+        entries.each { |entry| dependencies[entry[:name]] = entry[:dependency] }
+        data["dependencies"] = dependencies
+        write_pubspec_yaml(pubspec_path, data)
+        build_note("Added #{selected_names.join(', ')} from the extension configuration") unless selected_names.empty?
+      end
+
+      def managed_extension_state_path(client_dir)
+        File.join(client_dir, MANAGED_EXTENSION_STATE_PATH)
+      end
+
+      def managed_external_extension_names(client_dir)
+        path = managed_extension_state_path(client_dir)
+        return [] unless File.file?(path)
+
+        data = JSON.parse(read_text_file(path))
+        Array(data["external_packages"]).map(&:to_s).reject(&:empty?).uniq
+      rescue StandardError
+        []
+      end
+
+      def write_managed_external_extension_names(client_dir, names)
+        path = managed_extension_state_path(client_dir)
+        FileUtils.mkdir_p(File.dirname(path))
+        write_text_file(path, JSON.pretty_generate("external_packages" => Array(names).map(&:to_s).uniq.sort))
+      end
+
+      def discover_registered_external_extension_names(client_dir)
+        known_packages = CLIENT_EXTENSION_MAP.values.map { |entry| entry.fetch(:package) }.uniq
+        client_entrypoint_paths(client_dir).flat_map do |path|
+          next [] unless File.file?(path)
+
+          content = read_text_file(path)
+          content.scan(%r{import 'package:([^/]+)/[^']+'\s+as\s+([A-Za-z0-9_]+);}).filter_map do |package, import_alias|
+            next if known_packages.include?(package)
+            next unless content.match?(/^\s*#{Regexp.escape(import_alias)}\.Extension\(\),\s*$/)
+
+            package
+          end
+        end.uniq
+      end
+
+      def prune_external_extension_registrations(path, package_names)
+        return if package_names.empty?
+
+        content = read_text_file(path)
+        original = content.dup
+        package_names.each do |package|
+          escaped = Regexp.escape(package)
+          aliases = content.scan(%r{^import 'package:#{escaped}/[^']+'\s+as\s+([A-Za-z0-9_]+);\s*$}).flatten
+          content.gsub!(%r{^import 'package:#{escaped}/[^']+'\s+as\s+[A-Za-z0-9_]+;\s*\n}, "")
+          aliases.each do |import_alias|
+            content.gsub!(/^\s*#{Regexp.escape(import_alias)}\.Extension\(\),\s*\n/, "")
+          end
+        end
+        write_text_file(path, content) unless content == original
+      end
+
+      def validate_flutter_extension_selection(client_dir)
+        selected = Array(@ruflet_selected_flutter_extension_packages)
+        selected_external = Array(@ruflet_selected_external_extension_packages)
+        pubspec_path = File.join(client_dir, "pubspec.yaml")
+        return true unless File.file?(pubspec_path)
+
+        data = YAML.safe_load(read_text_file(pubspec_path), aliases: true) || {}
+        dependencies = data["dependencies"].is_a?(Hash) ? data["dependencies"].keys.map(&:to_s) : []
+        optional = CLIENT_EXTENSION_MAP.values.map { |entry| entry.fetch(:package) }.uniq
+        unexpected = (dependencies & optional) - selected
+        missing = selected - dependencies
+        managed_external = Array(@ruflet_managed_external_extension_packages)
+        unexpected_external = (dependencies & managed_external) - selected_external
+        errors = []
+        errors << "unused Flutter extensions remain: #{unexpected.join(', ')}" unless unexpected.empty?
+        errors << "selected Flutter extensions are missing: #{missing.join(', ')}" unless missing.empty?
+        errors << "unused external Flutter extensions remain: #{unexpected_external.join(', ')}" unless unexpected_external.empty?
+        return true if errors.empty?
+
+        errors.each { |message| warn "build config error: #{message}" }
+        false
+      rescue StandardError => e
+        warn "build config error: could not verify Flutter extension pruning: #{e.message}"
+        false
+      end
+
+      # Ruflet 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)
@@ -1536,19 +1961,106 @@ module Ruflet
         end
       end
 
-      def apply_native_service_permissions(client_dir, config)
+      def configured_service_entries_with_requirements(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, [])
+        configured_extensions = Array(config["extensions"]).filter_map do |entry|
+          normalize_extension_key(entry) unless entry.is_a?(Hash)
         end
-        extension_services.each do |service|
+        configured_extensions.flat_map do |extension|
+          EXTENSION_REQUIRED_SERVICES.fetch(extension, [])
+        end.each do |service|
           entries << { name: service, description: "" } unless entries.any? { |entry| entry[:name] == service }
         end
-        return if entries.empty?
+        entries
+      end
+
+      def configured_extension_keys(config)
+        services = configured_service_entries(config).map { |entry| entry[:name] }
+        requested_extensions = Array(config["extensions"]).filter_map do |value|
+          normalize_extension_key(value) unless value.is_a?(Hash)
+        end
+        protected_extensions = services.flat_map { |name| PROTECTED_SERVICE_EXTENSIONS.fetch(name, []) }
+        (requested_extensions + protected_extensions + services).uniq
+      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_with_requirements(config)
         apply_android_service_permissions(client_dir, entries)
         apply_ios_service_usage_descriptions(client_dir, entries)
+        apply_macos_service_permissions(client_dir, entries)
       end
 
       def apply_android_service_permissions(client_dir, entries)
@@ -1556,6 +2068,12 @@ module Ruflet
         return unless File.file?(path)
 
         content = read_text_file(path)
+        MANAGED_ANDROID_PERMISSIONS.each do |permission|
+          content.gsub!(
+            %r{^\s*<uses-permission\b[^>]*android:name="#{Regexp.escape(permission)}"[^>]*/>\s*\n?},
+            ""
+          )
+        end
         entries.flat_map { |entry| ANDROID_SERVICE_PERMISSIONS.fetch(entry[:name], []) }.uniq.each do |permission|
           next if content.include?(%(android:name="#{permission}"))
 
@@ -1566,22 +2084,56 @@ module Ruflet
 
       def apply_ios_service_usage_descriptions(client_dir, entries)
         path = File.join(client_dir, "ios", "Runner", "Info.plist")
+        apply_apple_service_usage_descriptions(
+          path, entries, IOS_SERVICE_USAGE_KEYS, MANAGED_IOS_USAGE_KEYS)
+      end
+
+      def apply_macos_service_permissions(client_dir, entries)
+        plist = File.join(client_dir, "macos", "Runner", "Info.plist")
+        apply_apple_service_usage_descriptions(
+          plist, entries, MACOS_SERVICE_USAGE_KEYS, MANAGED_MACOS_USAGE_KEYS)
+
+        %w[DebugProfile.entitlements Release.entitlements].each do |name|
+          path = File.join(client_dir, "macos", "Runner", name)
+          next unless File.file?(path)
+
+          content = read_text_file(path)
+          MANAGED_MACOS_SERVICE_ENTITLEMENTS.each do |key|
+            content.gsub!(
+              %r{\s*<key>#{Regexp.escape(key)}</key>\s*<(?:true|false)\s*/>}m,
+              ""
+            )
+          end
+          entries.filter_map { |entry| MACOS_SERVICE_ENTITLEMENTS[entry[:name]] }.uniq.each do |key|
+            pair = "\t<key>#{key}</key>\n\t<true/>\n"
+            content.sub!(%r{</dict>\s*</plist>}m, "#{pair}</dict>\n</plist>")
+          end
+          write_text_file(path, content)
+        end
+      end
+
+      def apply_apple_service_usage_descriptions(path, entries, usage_keys, managed_keys)
         return unless File.file?(path)
 
         content = read_text_file(path)
+        managed_keys.each do |key|
+          content.gsub!(
+            %r{\s*<key>#{Regexp.escape(key)}</key>\s*<string>.*?</string>}m,
+            ""
+          )
+        end
         entries.each do |entry|
-          key = IOS_SERVICE_USAGE_KEYS[entry[:name]]
-          next unless key
-
           description = entry[:description]
           description = "This app uses #{entry[:name]} access for its Ruflet features." if description.empty?
           escaped_description = xml_escape(description)
-          pair = "\t<key>#{key}</key>\n\t<string>#{escaped_description}</string>\n"
+          Array(usage_keys[entry[:name]]).each do |key|
+            pair = "\t<key>#{key}</key>\n\t<string>#{escaped_description}</string>\n"
 
-          if content.match?(%r{<key>#{Regexp.escape(key)}</key>})
-            content.sub!(%r{<key>#{Regexp.escape(key)}</key>\s*<string>.*?</string>}m, "<key>#{key}</key>\n\t<string>#{escaped_description}</string>")
-          else
-            content.sub!(%r{</dict>\s*</plist>}m, "#{pair}</dict>\n</plist>")
+            if content.match?(%r{<key>#{Regexp.escape(key)}</key>})
+              content.sub!(%r{<key>#{Regexp.escape(key)}</key>\s*<string>.*?</string>}m, "<key>#{key}</key>\n\t<string>#{escaped_description}</string>")
+            else
+              content.sub!(%r{</dict>\s*</plist>}m, "#{pair}</dict>\n</plist>")
+            end
           end
         end
         write_text_file(path, content)
@@ -1596,12 +2148,25 @@ module Ruflet
       end
 
       def clear_stale_platform_outputs(client_dir, platform, verbose: false)
-        return unless platform == "ios"
-
-        stale_paths = %w[
-          build/ios/Debug-iphonesimulator
-          build/ios/iphonesimulator
-        ]
+        stale_paths = case platform
+        when "ios"
+          %w[
+            build/ios/Debug-iphonesimulator
+            build/ios/iphonesimulator
+          ]
+        when "android", "apk", "aab"
+          # Flutter and Gradle merge assets incrementally. When a build switches
+          # from full to lite, removed project gems can otherwise survive in the
+          # next APK even though pubspec.yaml and the source asset tree are clean.
+          %w[
+            build/app/intermediates/flutter
+            build/app/intermediates/assets
+            build/app/intermediates/compressed_assets
+            build/app/intermediates/incremental/mergeReleaseAssets
+          ]
+        else
+          []
+        end
 
         stale_paths.each do |relative_path|
           path = File.join(client_dir, relative_path)
@@ -1610,6 +2175,23 @@ module Ruflet
           FileUtils.rm_rf(path)
           build_log(verbose, "cleared stale #{relative_path}")
         end
+
+        return unless platform == "ios"
+
+        # Xcode's incremental App.framework copy does not remove files that
+        # disappeared from a Flutter asset directory. Clear only the generated
+        # embedded project tree so a removed gem/archive cannot survive the
+        # next signed build; native compilation outputs remain reusable.
+        asset_pattern = File.join(
+          client_dir, "build", "ios", "**", "flutter_assets", "assets",
+          self_contained_project_name)
+        Dir.glob(asset_pattern).each do |asset_root|
+          next unless Dir.exist?(asset_root)
+
+          FileUtils.rm_rf(asset_root)
+          relative_path = Pathname.new(asset_root).relative_path_from(Pathname.new(client_dir))
+          build_log(verbose, "cleared stale #{relative_path}")
+        end
       end
 
       def client_entrypoint_paths(client_dir)
@@ -1620,14 +2202,14 @@ module Ruflet
 
       def configure_client_runtime_mode(client_dir, self_contained:, verbose: false)
         build_log(verbose, "configuring #{self_contained ? 'self-contained' : 'server-driven'} runtime")
-        sync_client_pubspec_for_runtime_mode(client_dir, self_contained: self_contained)
         if self_contained
-          sync_self_contained_project_assets(client_dir, verbose: verbose)
+          return false unless sync_self_contained_project_assets(client_dir, verbose: verbose)
           remove_local_ruby_runtime_override(client_dir, verbose: verbose)
         else
           remove_self_contained_project_assets(client_dir, verbose: verbose)
           remove_local_ruby_runtime_override(client_dir, verbose: verbose)
         end
+        sync_client_pubspec_for_runtime_mode(client_dir, self_contained: self_contained)
         true
       end
 
@@ -1638,24 +2220,25 @@ module Ruflet
         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["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)
+        project_prefix = "assets/#{self_contained_project_name}/"
+        # The exact directory list changes between lite and full (most notably
+        # vendor/bundle). Remove the previous profile's generated entries
+        # before adding the directories that exist in this build.
+        assets.reject! { |asset| asset == project_prefix || asset.start_with?(project_prefix) }
 
         if self_contained
           dependencies["ruby_runtime"] = ruby_runtime_dependency(dependencies["ruby_runtime"])
           # Flutter does not recurse into asset directories, so every subdirectory
           # of the embedded project (e.g. standalone_apps/<slug>/) must be listed
           # explicitly or its files never reach the bundle/manifest on device.
-          self_contained_project_asset_dirs.each do |dir_entry|
+          self_contained_project_asset_dirs(client_dir).each do |dir_entry|
             assets << dir_entry unless assets.include?(dir_entry)
           end
         else
           dependencies.delete("ruby_runtime")
-          project_prefix = "assets/#{self_contained_project_name}/"
-          assets.reject! { |a| a.to_s == project_prefix || a.to_s.start_with?(project_prefix) }
         end
 
         flutter["assets"] = assets unless assets.empty?
@@ -1669,12 +2252,69 @@ module Ruflet
       PUBLISHED_RUBY_RUNTIME_CONSTRAINT = "^0.0.9"
 
       def ruby_runtime_dependency(current_dependency = nil)
+        if embedded_runtime_profile == :full && @ruflet_full_runtime_path
+          return { "path" => @ruflet_full_runtime_path }
+        end
+
         local_path = explicit_local_ruby_runtime_path || source_checkout_ruby_runtime_path
         return { "path" => local_path } if local_path
 
         current_dependency || PUBLISHED_RUBY_RUNTIME_CONSTRAINT
       end
 
+      def configure_full_runtime_distribution(config, platform, verbose: false)
+        configured = ENV["RUFLET_FULL_RUNTIME_PATH"].to_s.strip
+        build_config = config["build"].is_a?(Hash) ? config["build"] : {}
+        configured = build_config["full_runtime_path"].to_s.strip if configured.empty?
+        candidates = []
+        candidates << File.expand_path(configured, Dir.pwd) unless configured.empty?
+        local_runtime = explicit_local_ruby_runtime_path || source_checkout_ruby_runtime_path
+        candidates << local_runtime if local_runtime
+
+        candidates.compact.uniq.each do |root|
+          manifest_path = File.join(root, FULL_RUNTIME_MANIFEST)
+          pubspec_path = File.join(root, "pubspec.yaml")
+          next unless File.file?(manifest_path) && File.file?(pubspec_path)
+
+          manifest = JSON.parse(read_text_file(manifest_path))
+          next unless manifest["engine"] == "cruby"
+          platforms = Array(manifest["platforms"]).map(&:to_s)
+          target = normalized_runtime_platform(platform)
+          next unless platforms.include?(target)
+
+          pubspec = YAML.safe_load(read_text_file(pubspec_path), aliases: true) || {}
+          next unless pubspec["name"] == "ruby_runtime"
+
+          @ruflet_full_runtime_path = File.expand_path(root)
+          @ruflet_full_runtime_manifest = manifest
+          build_log(
+            verbose,
+            "full CRuby runtime=#{@ruflet_full_runtime_path} ruby=#{manifest['ruby_version']}"
+          )
+          return true
+        rescue JSON::ParserError, Psych::SyntaxError => e
+          build_log(verbose, "ignored invalid full runtime at #{root}: #{e.message}")
+        end
+
+        warn "build config error: --full needs a CRuby runtime distribution for #{normalized_runtime_platform(platform)}"
+        warn "Set RUFLET_FULL_RUNTIME_PATH to a ruby_runtime Flutter package containing #{FULL_RUNTIME_MANIFEST}."
+        warn "The bundled ruby_runtime is the lite mruby engine and will not be mislabeled as CRuby."
+        false
+      end
+
+      def full_runtime_device_only?
+        embedded_runtime_profile == :full &&
+          @ruflet_full_runtime_manifest.is_a?(Hash) &&
+          @ruflet_full_runtime_manifest["device_only"] == true
+      end
+
+      def normalized_runtime_platform(platform)
+        return "android" if %w[apk android aab appbundle].include?(platform.to_s)
+        return "ios" if %w[ios ipa].include?(platform.to_s)
+
+        platform.to_s
+      end
+
       def explicit_local_ruby_runtime_path
         env_path = ENV["RUFLET_RUBY_RUNTIME_PATH"].to_s.strip
         return nil if env_path.empty?
@@ -1692,25 +2332,59 @@ module Ruflet
         nil
       end
 
-      def refresh_managed_client_template_files(client_dir, verbose: false)
+      def refresh_managed_client_template_files(client_dir, platform: nil, verbose: false)
         template_root =
           if Ruflet::CLI.respond_to?(:resolve_ruflet_client_template_root, true)
             Ruflet::CLI.send(:resolve_ruflet_client_template_root)
           end
         return unless template_root && Dir.exist?(template_root)
+        return false unless validate_template_ruflet_source_integrity(
+          template_root, verbose: verbose)
+
+        if experimental_native_renderer? && %w[ios ipa macos].include?(platform.to_s)
+          return false unless validate_native_apple_renderer_distribution(
+            template_root, verbose: verbose)
+        end
 
         managed_files = [
           "lib/main.dart",
           "lib/main.self.dart",
           "lib/main.server.dart",
-          "lib/ruflet_file_picker_service.dart",
+          "lib/native_renderer.dart",
           "lib/connection_probe.dart",
           "lib/connection_probe_io.dart",
           "lib/connection_probe_stub.dart",
           "ios/Podfile",
-          "windows/CMakeLists.txt"
+          # Carries the usage descriptions and the local-network/ATS policy a
+          # preview client needs. Without refreshing it, a client generated
+          # before those keys existed keeps a plist that silently blocks
+          # connections to a development server on the local network.
+          "ios/Runner/Info.plist",
+          "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"
         ]
 
+        case platform.to_s
+        when "ios", "ipa"
+          managed_files.concat(
+            [
+              "ios/Runner/AppDelegate.swift",
+              "ios/Runner/RufletEngineChoice.swift",
+              "ios/Runner.xcodeproj/project.pbxproj"
+            ]
+          )
+        when "macos"
+          managed_files.concat(
+            [
+              "macos/Runner/MainFlutterWindow.swift",
+              "macos/Runner/RufletEngineChoice.swift",
+              "macos/Runner.xcodeproj/project.pbxproj"
+            ]
+          )
+        end
+
         managed_files.each do |relative_path|
           source = File.join(template_root, relative_path)
           next unless File.file?(source)
@@ -1720,6 +2394,494 @@ module Ruflet
           FileUtils.cp(source, destination)
           build_log(verbose, "refreshed template file #{relative_path}")
         end
+
+        if experimental_native_renderer? && %w[ios ipa macos].include?(platform.to_s)
+          sync_managed_template_tree(
+            template_root, client_dir, "apple_packages/ruflet_apple", verbose: verbose)
+        end
+
+        # Older managed clients carried a macOS-only FilePicker override. Ruflet's
+        # core service owns FilePicker now, so this duplicate must not survive a
+        # template refresh.
+        FileUtils.rm_f(File.join(client_dir, "lib", "ruflet_file_picker_service.dart"))
+        true
+      end
+
+      # Every application build copies its engine and extension packages out of
+      # the template. Validate the pinned inventory before that copy so a stale,
+      # partially updated, or locally contaminated template can never become an
+      # application dependency by accident.
+      def validate_template_ruflet_source_integrity(template_root, verbose: false)
+        packages_root = File.join(template_root, "ruflet_packages")
+        return true unless Dir.exist?(packages_root)
+
+        manifest_path = File.join(template_root, RUFLET_SOURCE_INTEGRITY_PATH)
+        raise "missing #{RUFLET_SOURCE_INTEGRITY_PATH}" unless File.file?(manifest_path)
+
+        manifest = JSON.parse(read_text_file(manifest_path))
+        raise "unsupported source manifest version" unless manifest["manifest_version"] == 5
+        raise "unexpected source package" unless manifest["package_name"] == "ruflet-engine"
+        raise "invalid source revision" unless manifest["source_ref"].to_s.match?(/\A[0-9a-f]{40}\z/)
+
+        files = manifest.fetch("files")
+        raise "empty source inventory" unless files.is_a?(Hash) && !files.empty?
+
+        actual = []
+        Find.find(packages_root) do |path|
+          next if path == packages_root
+
+          relative = path.delete_prefix("#{packages_root}#{File::SEPARATOR}")
+          if RUFLET_SOURCE_IGNORED_DIRECTORIES.include?(File.basename(path))
+            Find.prune if File.directory?(path)
+            next
+          end
+          next if RUFLET_SOURCE_IGNORED_FILES.include?(File.basename(path))
+          next if File.directory?(path)
+          raise "symbolic link in engine source: #{path}" if File.symlink?(path)
+
+          actual << relative
+        end
+        expected = files.keys.sort
+        unless actual.sort == expected
+          missing = expected - actual
+          unexpected = actual - expected
+          details = []
+          details << "missing: #{missing.first(5).join(', ')}" unless missing.empty?
+          details << "unexpected: #{unexpected.first(5).join(', ')}" unless unexpected.empty?
+          raise "source inventory mismatch (#{details.join('; ')})"
+        end
+
+        files.each do |relative, entry|
+          path = File.expand_path(relative, packages_root)
+          prefix = "#{File.expand_path(packages_root)}#{File::SEPARATOR}"
+          raise "unsafe source path: #{relative}" unless path.start_with?(prefix)
+          raise "source path mismatch: #{relative}" unless entry["source_path"] == relative
+          raise "non-exact source entry: #{relative}" unless entry["classification"] == "exact_source"
+
+          expected_sha = entry["vendored_sha256"].to_s
+          raise "invalid source digest: #{relative}" unless expected_sha.match?(/\A[0-9a-f]{64}\z/)
+          actual_sha = Digest::SHA256.file(path).hexdigest
+          raise "source content drift: #{relative}" unless actual_sha == expected_sha
+        end
+
+        build_note(
+          "Verified #{files.length} pinned Ruflet engine and extension source files " \
+          "at #{manifest.fetch('source_ref')}"
+        )
+        true
+      rescue StandardError => e
+        warn "build config error: Ruflet template source verification failed: #{e.message}"
+        build_log(verbose, "template source integrity failure at #{template_root}")
+        false
+      end
+
+      # The standalone client template owns the editable Apple renderer. Build
+      # clients receive an exact managed copy from that package; there is no
+      # second renderer in this repository and no fallback implementation.
+      def validate_native_apple_renderer_distribution(template_root, verbose: false)
+        package_root = File.join(template_root, "apple_packages", "ruflet_apple")
+        required = [
+          "Package.swift",
+          "Sources/RufletEngine/RufletApp.swift",
+          "Sources/RufletEngine/RufletAppView.swift"
+        ]
+        missing = required.reject { |relative| File.file?(File.join(package_root, relative)) }
+        return true if missing.empty?
+
+        warn "build config error: the authoritative Apple renderer is incomplete"
+        missing.each { |relative| warn "  missing: apple_packages/ruflet_apple/#{relative}" }
+        false
+      end
+
+      def configure_apple_renderer_integration(client_dir, platform:, enabled:, verbose: false)
+        apple_platform = case platform.to_s
+        when "ios", "ipa" then "ios"
+        when "macos" then "macos"
+        end
+        return true unless apple_platform
+
+        if enabled
+          package = File.join(client_dir, "apple_packages", "ruflet_apple", "Package.swift")
+          choice = File.join(client_dir, apple_platform, "Runner", "RufletEngineChoice.swift")
+          unless File.file?(package) && File.file?(choice)
+            warn "build config error: the Ruflet client template does not contain the native Apple renderer"
+            warn "Refresh the Ruflet template, then run the build again."
+            return false
+          end
+          configure_ios_scene_delegate(client_dir, native: true) if apple_platform == "ios"
+          build_log(verbose, "enabled experimental native Apple renderer")
+          return true
+        end
+
+        unless restore_flutter_apple_host(client_dir, apple_platform, verbose: verbose)
+          return false
+        end
+        strip_native_apple_xcode_project(client_dir, apple_platform)
+        FileUtils.rm_f(File.join(client_dir, apple_platform, "Runner", "RufletEngineChoice.swift"))
+        FileUtils.rm_rf(File.join(client_dir, "apple_packages"))
+        FileUtils.rm_rf(File.join(client_dir, "apple_extensions"))
+        configure_ios_scene_delegate(client_dir, native: false) if apple_platform == "ios"
+        apple_info_plist_paths(client_dir).each do |path|
+          remove_plist_value(path, "RufletExperimentalNativeRenderer")
+          remove_plist_value(path, "GADApplicationIdentifier")
+        end
+        build_log(verbose, "using Flutter renderer; removed native Apple package integration")
+        true
+      end
+
+      def restore_flutter_apple_host(client_dir, platform, verbose: false)
+        template_root = if Ruflet::CLI.respond_to?(:resolve_ruflet_client_template_root, true)
+          Ruflet::CLI.send(:resolve_ruflet_client_template_root)
+        end
+        filename = platform == "ios" ? "AppDelegate.swift" : "MainFlutterWindow.swift"
+        source = template_root && File.join(template_root, "flutter_hosts", platform, "Runner", filename)
+        unless source && File.file?(source)
+          warn "build config error: the Ruflet client template is missing the Flutter-only #{platform} host"
+          return false
+        end
+
+        destination = File.join(client_dir, platform, "Runner", filename)
+        FileUtils.mkdir_p(File.dirname(destination))
+        FileUtils.cp(source, destination)
+        build_log(verbose, "restored Flutter-only #{platform} host")
+        true
+      end
+
+      def strip_native_apple_xcode_project(client_dir, platform)
+        path = File.join(client_dir, platform, "Runner.xcodeproj", "project.pbxproj")
+        return unless File.file?(path)
+
+        content = read_text_file(path)
+        content.gsub!(
+          %r{^\s*[A-F0-9]+ /\* XCLocalSwiftPackageReference "\.\./apple_(?:extensions|packages/ruflet_apple)" \*/ = \{.*?^\s*\};\n}m,
+          ""
+        )
+        content = content.lines.reject do |line|
+          line.include?("Ruflet") ||
+            line.include?("../apple_extensions") ||
+            line.include?("../apple_packages/ruflet_apple")
+        end.join
+        write_text_file(path, content)
+      end
+
+      def configure_ios_scene_delegate(client_dir, native:)
+        path = File.join(client_dir, "ios", "Runner", "Info.plist")
+        return unless File.file?(path)
+
+        content = read_text_file(path)
+        delegate = native ? "RufletSceneDelegate" : "SceneDelegate"
+        content.gsub!(
+          %r{(<key>UISceneDelegateClassName</key>\s*<string>)\$\(PRODUCT_MODULE_NAME\)\.(?:RufletSceneDelegate|FlutterSceneDelegate|SceneDelegate)(</string>)}m,
+          "\\1$(PRODUCT_MODULE_NAME).#{delegate}\\2"
+        )
+        write_text_file(path, content)
+      end
+
+      def apple_info_plist_paths(client_dir)
+        [
+          File.join(client_dir, "ios", "Runner", "Info.plist"),
+          File.join(client_dir, "macos", "Runner", "Info.plist")
+        ].select { |path| File.file?(path) }
+      end
+
+      def remove_plist_value(path, key)
+        content = read_text_file(path)
+        content.gsub!(
+          %r{\s*<key>#{Regexp.escape(key)}</key>\s*(?:<string>.*?</string>|<(?:true|false)\s*/>)}m,
+          ""
+        )
+        write_text_file(path, content)
+      end
+
+      def remove_plist_dictionary_boolean(path, dictionary_key, key)
+        content = read_text_file(path)
+        dictionary = content.match(
+          %r{<key>#{Regexp.escape(dictionary_key)}</key>\s*<dict>}m)
+        return unless dictionary
+
+        opening = content.index("<dict>", dictionary.begin(0))
+        return unless opening
+
+        depth = 0
+        closing = nil
+        content.to_enum(:scan, %r{</?dict>}).each do
+          token = Regexp.last_match
+          next if token.begin(0) < opening
+
+          depth += token[0] == "<dict>" ? 1 : -1
+          if depth.zero?
+            closing = token
+            break
+          end
+        end
+        return unless closing
+
+        body_start = opening + "<dict>".length
+        body = content[body_start...closing.begin(0)]
+        updated_body = body.gsub(
+          %r{\s*<key>#{Regexp.escape(key)}</key>\s*<(?:true|false)\s*/>}m,
+          ""
+        )
+        return if updated_body == body
+
+        if updated_body.strip.empty?
+          pair_start = dictionary.begin(0)
+          line_start = content.rindex("\n", pair_start - 1)
+          if line_start && content[(line_start + 1)...pair_start].strip.empty?
+            pair_start = line_start + 1
+          end
+          content[pair_start...closing.end(0)] = ""
+        else
+          content[body_start...closing.begin(0)] = updated_body
+        end
+        write_text_file(path, content)
+      end
+
+      def apply_native_apple_extension_config(
+        client_dir, platform:, extension_keys:, verbose: false
+      )
+        apple_platform = %w[ios ipa].include?(platform.to_s) ? "ios" : platform.to_s
+        return unless %w[ios macos].include?(apple_platform)
+
+        selected = Array(extension_keys).filter_map do |key|
+          spec = NATIVE_APPLE_EXTENSION_MAP[key]
+          [key, spec] if spec
+        end
+        selected_modules = selected.map { |_key, spec| spec.fetch(:module) }
+        unselected_modules = NATIVE_APPLE_EXTENSION_MAP.values
+          .map { |spec| spec.fetch(:module) }
+          .uniq - selected_modules
+
+        choice_path = File.join(client_dir, apple_platform, "Runner", "RufletEngineChoice.swift")
+        if File.file?(choice_path)
+          imports = selected_modules.map { |name| "import #{name}" }.join("\n")
+          registrations = selected.map do |_key, spec|
+            "    result.append(#{spec.fetch(:initializer)})"
+          end.join("\n")
+          source = <<~SWIFT
+            import Foundation
+            import RufletApple
+            import RufletAppExtensions
+            #{imports}
+
+            /// Generated by `ruflet build --experimental` from the same
+            /// services/extensions configuration used by the Flutter client.
+            enum RufletEngineChoice {
+              static var usesNativeRenderer: Bool {
+                let value = Bundle.main.object(
+                  forInfoDictionaryKey: "RufletExperimentalNativeRenderer")
+                if let flag = value as? Bool { return flag }
+                if let flag = value as? NSNumber { return flag.boolValue }
+                return false
+              }
+
+              static func pageURL(from raw: String) -> URL? {
+                RufletPageAddress.parse(raw)
+              }
+
+              @MainActor static var extensions: [any RufletExtension] {
+                var result = RufletAppExtensionRegistry.extensions
+            #{registrations}
+                return result
+              }
+            }
+          SWIFT
+          write_text_file(choice_path, source)
+        end
+
+        pbxproj = File.join(client_dir, apple_platform, "Runner.xcodeproj", "project.pbxproj")
+        if File.file?(pbxproj)
+          content = read_text_file(pbxproj)
+          content = content.lines.reject do |line|
+            unselected_modules.any? do |name|
+              line.match?(/\/\* #{Regexp.escape(name)}(?: in Frameworks)? \*\//)
+            end
+          end.join
+          write_text_file(pbxproj, content)
+        end
+
+        unless selected_modules.include?("RufletAds")
+          remove_plist_value(
+            File.join(client_dir, "ios", "Runner", "Info.plist"),
+            "GADApplicationIdentifier") if apple_platform == "ios"
+        end
+        build_log(
+          verbose,
+          "native Apple extensions=#{selected.empty? ? 'core only' : selected.map(&:first).join(',')}"
+        )
+      end
+
+      def sync_managed_template_tree(template_root, client_dir, relative_path, verbose: false)
+        source = File.join(template_root, relative_path)
+        return unless Dir.exist?(source)
+
+        destination = File.join(client_dir, relative_path)
+        sync_apple_source_tree(source, destination)
+        build_log(verbose, "refreshed template tree #{relative_path}")
+      end
+
+      # Application-defined RufletExtension implementations live outside the
+      # generated Flutter client. New projects own <project>/apple_extensions;
+      # existing projects receive the empty template registry until they opt
+      # in. Both server-driven and self-contained builds use the same package.
+      def sync_application_apple_extensions(client_dir, platform:, verbose: false)
+        return unless %w[ios ipa macos].include?(platform.to_s)
+
+        template_root = if Ruflet::CLI.respond_to?(:resolve_ruflet_client_template_root, true)
+          Ruflet::CLI.send(:resolve_ruflet_client_template_root)
+        end
+        project_source = File.join(Dir.pwd, "apple_extensions")
+        template_source = template_root && File.join(template_root, "apple_extensions")
+        source = if File.file?(File.join(project_source, "Package.swift"))
+          project_source
+        elsif template_source && File.file?(File.join(template_source, "Package.swift"))
+          template_source
+        end
+        return unless source
+
+        destination = File.join(client_dir, "apple_extensions")
+        sync_apple_source_tree(source, destination)
+        owner = source == project_source ? "project" : "template default"
+        build_log(verbose, "refreshed #{owner} Apple extensions")
+      end
+
+      def sync_apple_source_tree(source, destination)
+        FileUtils.rm_rf(destination)
+        FileUtils.mkdir_p(destination)
+        # SwiftPM and Dart create mutable caches directly inside the package.
+        # Copying the whole directory and deleting those caches afterwards is
+        # too late: framework resource symlinks inside `.build` can collide or
+        # escape while FileUtils is still traversing them. Treat only the
+        # package's source tree as managed template input from the outset.
+        generated_entries = %w[
+          .swiftpm .dart_tool .claude DerivedData xcuserdata
+        ]
+        Dir.children(source).each do |entry|
+          next if generated_entries.include?(entry) || entry == ".build" || entry.start_with?(".build-")
+
+          FileUtils.cp_r(
+            File.join(source, entry), File.join(destination, entry),
+            preserve: true)
+        end
+      end
+
+      def configure_native_apple_runtime(
+        client_dir, platform:, self_contained:, config: {}, experimental: true, verbose: false
+      )
+        plist_paths = case platform.to_s
+        when "ios", "ipa"
+          [File.join(client_dir, "ios", "Runner", "Info.plist")]
+        when "macos"
+          [File.join(client_dir, "macos", "Runner", "Info.plist")]
+        else
+          []
+        end
+
+        plist_paths.each do |path|
+          next unless File.file?(path)
+
+          upsert_plist_string(
+            path, "RufletEmbeddedProject",
+            self_contained ? self_contained_project_name : "")
+          upsert_plist_boolean(path, "RufletRuntimeAutostart", self_contained)
+          upsert_plist_string(
+            path, "RufletRuntimeProfile",
+            self_contained ? embedded_runtime_profile.to_s : "")
+          upsert_plist_boolean(
+            path, "RufletExperimentalNativeRenderer",
+            experimental)
+          apple_platform = platform.to_s == "ipa" ? "ios" : platform.to_s
+          platform_config = platform_build_config(config, apple_platform)
+          if platform_config["local_network"] == true
+            # The embedded VM is in-process, but the application can still
+            # explicitly connect to LAN services (for example RufletApp).
+            description = platform_config["local_network_usage_description"].to_s.strip
+            description = "Connect to Ruflet applications and services on your local network." if description.empty?
+            upsert_plist_string(path, "NSLocalNetworkUsageDescription", description)
+            upsert_plist_dictionary_boolean(
+              path, "NSAppTransportSecurity", "NSAllowsLocalNetworking", true)
+          elsif self_contained
+            remove_plist_value(path, "NSLocalNetworkUsageDescription")
+            remove_plist_dictionary_boolean(
+              path, "NSAppTransportSecurity", "NSAllowsLocalNetworking")
+          end
+          message = if self_contained
+            "native Apple runtime autostarts #{self_contained_project_name}"
+          else
+            "native Apple runtime uses the server URL resolved by Dart"
+          end
+          build_log(verbose, message)
+        end
+      end
+
+      def configure_android_runtime(client_dir, platform:, self_contained:, verbose: false)
+        return unless %w[apk android aab appbundle].include?(platform.to_s)
+
+        path = File.join(client_dir, "android", "app", "src", "main", "AndroidManifest.xml")
+        return unless File.file?(path)
+
+        upsert_android_metadata(path, "ruflet.runtime.autostart", self_contained.to_s)
+        upsert_android_metadata(
+          path, "ruflet.runtime.project",
+          self_contained ? self_contained_project_name : "")
+        upsert_android_metadata(
+          path, "ruflet.runtime.profile",
+          self_contained ? embedded_runtime_profile.to_s : "")
+        build_log(
+          verbose,
+          self_contained ? "android runtime autostarts #{self_contained_project_name} (#{embedded_runtime_profile})" : "android embedded runtime autostart disabled"
+        )
+      end
+
+      def upsert_android_metadata(path, name, value)
+        content = read_text_file(path)
+        escaped_value = xml_escape(value)
+        tag = %(        <meta-data android:name="#{name}" android:value="#{escaped_value}" />)
+        pattern = %r{\s*<meta-data\s+android:name=["']#{Regexp.escape(name)}["'][^>]*/>}m
+        if content.match?(pattern)
+          content.sub!(pattern, "\n#{tag}")
+        else
+          content.sub!(%r{(<application\b[^>]*>)}, "\\1\n#{tag}")
+        end
+        write_text_file(path, content)
+      end
+
+      def upsert_plist_string(path, key, value)
+        content = read_text_file(path)
+        pair = "\t<key>#{key}</key>\n\t<string>#{xml_escape(value)}</string>"
+        pattern = %r{<key>#{Regexp.escape(key)}</key>\s*<string>.*?</string>}m
+        if content.match?(pattern)
+          content.sub!(pattern, pair.strip)
+        else
+          content.sub!(%r{</dict>\s*</plist>}m, "#{pair}\n</dict>\n</plist>")
+        end
+        write_text_file(path, content)
+      end
+
+      def upsert_plist_boolean(path, key, value)
+        content = read_text_file(path)
+        pair = "\t<key>#{key}</key>\n\t<#{value ? 'true' : 'false'}/>"
+        pattern = %r{<key>#{Regexp.escape(key)}</key>\s*<(?:true|false)\s*/>}m
+        if content.match?(pattern)
+          content.sub!(pattern, pair.strip)
+        else
+          content.sub!(%r{</dict>\s*</plist>}m, "#{pair}\n</dict>\n</plist>")
+        end
+        write_text_file(path, content)
+      end
+
+      def upsert_plist_dictionary_boolean(path, dictionary_key, key, value)
+        remove_plist_dictionary_boolean(path, dictionary_key, key)
+        content = read_text_file(path)
+        entry = "<key>#{key}</key>\n\t\t<#{value ? 'true' : 'false'}/>"
+        opening = %r{(<key>#{Regexp.escape(dictionary_key)}</key>\s*<dict>)}m
+        if content.match?(opening)
+          content.sub!(opening) { "#{Regexp.last_match(1)}\n\t\t#{entry}" }
+        else
+          pair = "\t<key>#{dictionary_key}</key>\n\t<dict>\n\t\t#{entry}\n\t</dict>\n"
+          content.sub!(%r{</dict>\s*</plist>}m, "#{pair}</dict>\n</plist>")
+        end
+        write_text_file(path, content)
       end
 
       def write_pubspec_yaml(path, data)
@@ -1747,11 +2909,24 @@ module Ruflet
       # Flutter asset directory entries for every folder of the embedded project
       # that contains packaged files. Derived from the exact copy list so the
       # pubspec asset dirs match what sync_self_contained_project_assets writes.
-      def self_contained_project_asset_dirs
+      def self_contained_project_asset_dirs(client_dir = nil)
         prefix = "assets/#{self_contained_project_name}"
         dirs = project_asset_relative_paths.map { |rel| File.dirname(rel) }.uniq
+        if client_dir
+          packaged_root = File.join(client_dir, prefix)
+          if Dir.exist?(packaged_root)
+            Find.find(packaged_root) do |path|
+              next unless File.file?(path)
+
+              relative = Pathname.new(path).relative_path_from(Pathname.new(packaged_root)).to_s
+              dirs << File.dirname(relative)
+            end
+          end
+        end
         project_dirs = dirs.map { |dir| dir == "." ? "#{prefix}/" : "#{prefix}/#{dir}/" }
-        project_dirs.sort
+        manifest = File.join(client_dir.to_s, prefix, ".ruflet-runtime.json")
+        project_dirs << "#{prefix}/.ruflet-runtime.json" if client_dir && File.file?(manifest)
+        project_dirs.uniq.sort
       end
 
       def sync_self_contained_project_assets(client_dir, verbose: false)
@@ -1772,7 +2947,329 @@ module Ruflet
           copied += 1
         end
 
+        profile = embedded_runtime_profile
+        if profile == :full
+          return false unless package_full_runtime_gems(
+            project_root, destination_root, client_dir, verbose: verbose)
+        else
+          return false unless precompile_lite_runtime_project(
+            destination_root, verbose: verbose)
+        end
+        write_embedded_runtime_manifest(
+          project_root, destination_root, profile: profile,
+          platform: @ruflet_build_platform)
+
         build_log(verbose, "copied #{copied} project file#{copied == 1 ? '' : 's'} to assets/#{self_contained_project_name}")
+        true
+      end
+
+      def precompile_lite_runtime_project(destination_root, verbose: false)
+        compiler = embedded_mrbc_path
+        unless compiler
+          build_log(verbose, "mrbc unavailable; packaging lite Ruby source")
+          return true
+        end
+
+        sources = Dir.glob(File.join(destination_root, "**", "*.rb")).sort
+        compiled = []
+        sources.each do |source|
+          output = source.sub(/\.rb\z/, ".mrb")
+          ok = run_external_command(
+            {}, compiler, "-g", "-o", output, source,
+            chdir: destination_root, unbundled: true)
+          unless ok
+            warn "Could not precompile #{Pathname.new(source).relative_path_from(Pathname.new(destination_root))} for --lite"
+            return false
+          end
+          compiled << [source, output]
+        end
+        compiled.each { |source, _output| FileUtils.rm_f(source) }
+        build_log(verbose, "precompiled #{compiled.length} Ruby file#{compiled.length == 1 ? '' : 's'} for fast lite startup")
+        true
+      end
+
+      def embedded_mrbc_path
+        explicit = ENV["RUFLET_MRBC"].to_s.strip
+        return explicit if !explicit.empty? && File.executable?(explicit)
+
+        runtime_root = explicit_local_ruby_runtime_path || source_checkout_ruby_runtime_path
+        candidates = []
+        if runtime_root
+          candidates.concat(
+            %w[host_vm host].map do |build|
+              File.join(runtime_root, "third_party", "mruby", "build", build, "bin", "mrbc")
+            end
+          )
+          candidates << File.join(runtime_root, "bin", "mrbc")
+        end
+        candidates.find { |path| File.executable?(path) }
+      end
+
+      def embedded_runtime_profile
+        profile = @ruflet_runtime_profile
+        EMBEDDED_RUNTIME_PROFILES.include?(profile) ? profile : :lite
+      end
+
+      # A full build carries the locked application bundle alongside the
+      # project. Bundler is isolated under build/client so this never creates or
+      # rewrites .bundle state in the user's project. The cache key makes repeat
+      # builds cheap: unchanged locks reuse the installed bundle and only copy
+      # it into the Flutter asset tree.
+      def package_full_runtime_gems(project_root, destination_root, client_dir, verbose: false)
+        gemfile = project_root.join("Gemfile")
+        return true unless gemfile.file?
+
+        lockfile = project_root.join("Gemfile.lock")
+        unless lockfile.file?
+          warn "full runtime build requires Gemfile.lock"
+          warn "Run `bundle install` once so Ruflet can package a reproducible gem set."
+          return false
+        end
+
+        cache_key = Digest::SHA256.hexdigest(
+          [
+            gemfile.read,
+            lockfile.read,
+            RUBY_ENGINE,
+            RUBY_VERSION,
+            @ruflet_build_platform.to_s,
+            FULL_RUNTIME_BUNDLE_SCHEMA,
+            JSON.generate(@ruflet_full_runtime_manifest || {})
+          ].join("\0")
+        )
+        cache_root = File.join(client_dir, ".ruflet", "full-bundle", cache_key)
+        bundle_path = File.join(cache_root, "vendor", "bundle")
+        complete_marker = File.join(cache_root, ".complete")
+
+        unless File.file?(complete_marker) && Dir.exist?(bundle_path)
+          FileUtils.rm_rf(cache_root)
+          FileUtils.mkdir_p(cache_root)
+          bundle_env = {
+            "BUNDLE_GEMFILE" => gemfile.to_s,
+            "BUNDLE_PATH" => bundle_path,
+            "BUNDLE_APP_CONFIG" => File.join(cache_root, "config"),
+            "BUNDLE_WITHOUT" => "development:test",
+            "BUNDLE_FROZEN" => "true",
+            "BUNDLE_DEPLOYMENT" => "true"
+          }
+          build_note("Packaging locked project gems for the full CRuby runtime")
+          build_log(verbose, "bundle cache=#{cache_root}")
+          ok = run_full_runtime_gem_packager(
+            bundle_env, gemfile: gemfile, lockfile: lockfile,
+            bundle_path: bundle_path, project_root: project_root)
+          unless ok
+            warn "Could not package the locked project gems for --full"
+            return false
+          end
+          unless vendor_full_runtime_path_gems(
+            bundle_env, bundle_path: bundle_path, project_root: project_root)
+            return false
+          end
+          prune_full_runtime_bundle_cache(bundle_path)
+          return false unless validate_full_runtime_in_process_transport(bundle_path)
+          File.write(complete_marker, "#{cache_key}\n")
+        else
+          build_log(verbose, "reusing full runtime gem cache #{cache_key[0, 12]}")
+          return false unless validate_full_runtime_in_process_transport(bundle_path)
+        end
+
+        packaged_bundle = File.join(destination_root, "vendor", "bundle")
+        FileUtils.mkdir_p(File.dirname(packaged_bundle))
+        FileUtils.cp_r(bundle_path, packaged_bundle)
+        FileUtils.cp(gemfile.to_s, File.join(destination_root, "Gemfile"))
+        FileUtils.cp(lockfile.to_s, File.join(destination_root, "Gemfile.lock"))
+        true
+      rescue StandardError => e
+        warn "Could not package project gems for --full: #{e.class}: #{e.message}"
+        false
+      end
+
+      def run_full_runtime_gem_packager(bundle_env, gemfile:, lockfile:, bundle_path:, project_root:)
+        packager = @ruflet_full_runtime_manifest && @ruflet_full_runtime_manifest["gem_packager"]
+        unless packager.to_s.strip.empty?
+          executable = File.expand_path(packager.to_s, @ruflet_full_runtime_path)
+          unless File.executable?(executable)
+            warn "Full runtime gem packager is not executable: #{executable}"
+            return false
+          end
+          return run_external_command(
+            bundle_env,
+            executable,
+            "--gemfile", gemfile.to_s,
+            "--lockfile", lockfile.to_s,
+            "--path", bundle_path,
+            "--platform", normalized_runtime_platform(@ruflet_build_platform),
+            chdir: project_root.to_s,
+            unbundled: true
+          )
+        end
+
+        run_external_command(
+          bundle_env, RbConfig.ruby, "-S", "bundle", "install",
+          "--jobs", "4", "--retry", "3",
+          chdir: project_root.to_s, unbundled: true
+        )
+      end
+
+      # Bundler intentionally leaves `path:` gems at their source location,
+      # even when BUNDLE_PATH is set. A self-contained app cannot retain those
+      # workstation paths. Materialize every resolved spec that sits outside
+      # vendor/bundle so the runtime sees the exact locked source tree.
+      def vendor_full_runtime_path_gems(bundle_env, bundle_path:, project_root:)
+        script = <<~'RUBY'
+          require "bundler"
+          require "json"
+          puts JSON.generate(Bundler.load.specs.map { |spec|
+            {
+              "full_name" => spec.full_name,
+              "full_gem_path" => spec.full_gem_path,
+              "extension_dir" => spec.extension_dir,
+              "source_type" => spec.source.class.name,
+              "files" => spec.files,
+              "gemspec" => spec.to_ruby
+            }
+          })
+        RUBY
+        stdout, stderr, status = Open3.capture3(
+          bundle_env, RbConfig.ruby, "-e", script,
+          chdir: project_root.to_s)
+        unless status.success?
+          warn "Could not inspect locked project gems for --full"
+          warn stderr unless stderr.to_s.strip.empty?
+          return false
+        end
+
+        ruby_abi = (@ruflet_full_runtime_manifest || {})["ruby_abi"].to_s
+        ruby_abi = RbConfig::CONFIG.fetch("ruby_version") if ruby_abi.empty?
+        installed_root = File.expand_path(bundle_path)
+        specs = JSON.parse(stdout)
+        specs.each do |spec|
+          next unless spec.fetch("source_type") == "Bundler::Source::Path"
+
+          source = File.expand_path(spec.fetch("full_gem_path"))
+          next if source == installed_root || source.start_with?("#{installed_root}#{File::SEPARATOR}")
+
+          full_name = spec.fetch("full_name")
+          destination = File.join(bundle_path, "ruby", ruby_abi, "gems", full_name)
+          FileUtils.rm_rf(destination)
+          FileUtils.mkdir_p(File.dirname(destination))
+          unless copy_full_runtime_gem_files(
+            source, destination, spec.fetch("files"), full_name: full_name)
+            return false
+          end
+
+          specifications = File.join(bundle_path, "ruby", ruby_abi, "specifications")
+          FileUtils.mkdir_p(specifications)
+          File.write(File.join(specifications, "#{full_name}.gemspec"), spec.fetch("gemspec"))
+
+          extension_source = spec["extension_dir"].to_s
+          next unless !extension_source.empty? && Dir.exist?(extension_source)
+
+          extension_destination = File.join(
+            bundle_path, "ruby", ruby_abi, "extensions", "ruflet", full_name)
+          FileUtils.rm_rf(extension_destination)
+          FileUtils.mkdir_p(File.dirname(extension_destination))
+          FileUtils.cp_r(extension_source, extension_destination)
+        end
+        true
+      rescue JSON::ParserError, KeyError, SystemCallError => e
+        warn "Could not vendor path gems for --full: #{e.class}: #{e.message}"
+        false
+      end
+
+      # Downloaded .gem archives are installation inputs, not runtime inputs.
+      # Keeping them would duplicate every registry gem in the application.
+      def prune_full_runtime_bundle_cache(bundle_path)
+        Dir.glob(File.join(bundle_path, "ruby", "*", "cache")).each do |cache_dir|
+          FileUtils.rm_rf(cache_dir)
+        end
+      end
+
+      # Full self builds cannot fall back to a local socket: the embedded
+      # renderer and CRuby VM communicate only through the native in-memory
+      # bridge. Reject an older locked ruflet_server while the app is still
+      # being built instead of shipping a bundle that fails on first launch.
+      def validate_full_runtime_in_process_transport(bundle_path)
+        server_roots = Dir.glob(
+          File.join(bundle_path, "ruby", "*", "gems", "ruflet_server-*")
+        ).select { |path| Dir.exist?(path) }
+        return true if server_roots.empty?
+
+        supported = server_roots.any? do |root|
+          File.file?(
+            File.join(root, "lib", "ruflet", "server", "in_process_connection.rb")
+          )
+        end
+        return true if supported
+
+        warn "The locked ruflet_server gem does not support port-free --self --full builds."
+        warn "Update the application's Gemfile.lock to a Ruflet release with in-process transport."
+        false
+      end
+
+      # A path gem is a source checkout, not an installable payload. Copy only
+      # the files declared by its gemspec so build products, tests, caches and
+      # other workstation state cannot leak into a mobile application bundle.
+      def copy_full_runtime_gem_files(source, destination, files, full_name:)
+        source_root = File.expand_path(source)
+        destination_root = File.expand_path(destination)
+        declared_files = Array(files).map(&:to_s).reject(&:empty?).uniq.sort
+        if declared_files.empty?
+          warn "Could not vendor path gem #{full_name}: its gemspec declares no files"
+          return false
+        end
+
+        declared_files.each do |relative_path|
+          pathname = Pathname.new(relative_path)
+          clean_path = pathname.cleanpath
+          if pathname.absolute? || clean_path.each_filename.include?("..")
+            warn "Could not vendor path gem #{full_name}: unsafe file path #{relative_path.inspect}"
+            return false
+          end
+
+          source_file = File.expand_path(clean_path.to_s, source_root)
+          unless source_file.start_with?("#{source_root}#{File::SEPARATOR}") && File.file?(source_file)
+            warn "Could not vendor path gem #{full_name}: declared file is missing: #{relative_path}"
+            return false
+          end
+
+          destination_file = File.expand_path(clean_path.to_s, destination_root)
+          FileUtils.mkdir_p(File.dirname(destination_file))
+          FileUtils.cp(source_file, destination_file, preserve: true)
+        end
+        true
+      rescue SystemCallError => e
+        warn "Could not vendor path gem #{full_name}: #{e.class}: #{e.message}"
+        false
+      end
+
+      def write_embedded_runtime_manifest(project_root, destination_root, profile:, platform:)
+        paths = Dir.glob(File.join(destination_root, "**", "*"), File::FNM_DOTMATCH)
+          .select { |path| File.file?(path) }
+          .reject { |path| File.basename(path) == ".ruflet-runtime.json" }
+          .sort
+        digest = Digest::SHA256.new
+        paths.each do |path|
+          relative = Pathname.new(path).relative_path_from(Pathname.new(destination_root)).to_s
+          digest << relative << "\0" << File.binread(path) << "\0"
+        end
+
+        manifest = {
+          "schema" => 1,
+          "profile" => profile.to_s,
+          "engine" => profile == :full ? "cruby" : "mruby",
+          "platform" => platform.to_s,
+          "project" => project_root.basename.to_s,
+          "entrypoint" => File.file?(File.join(destination_root, "main.mrb")) ? "main.mrb" : "main.rb",
+          "bundle_gemfile" => profile == :full && File.file?(File.join(destination_root, "Gemfile")) ? "Gemfile" : nil,
+          "bundle_path" => profile == :full && Dir.exist?(File.join(destination_root, "vendor", "bundle")) ? "vendor/bundle" : nil,
+          "cache_key" => digest.hexdigest,
+          "warm_launch" => true
+        }.compact
+        File.write(
+          File.join(destination_root, ".ruflet-runtime.json"),
+          "#{JSON.pretty_generate(manifest)}\n"
+        )
       end
 
       def remove_self_contained_project_assets(client_dir, verbose: false)
@@ -1848,7 +3345,7 @@ module Ruflet
       # 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].freeze
+      SECRET_ASSET_BASENAMES = %w[.env .netrc key.properties].freeze
 
       def secret_project_asset?(relative)
         basename = File.basename(relative)
@@ -1860,10 +3357,30 @@ module Ruflet
         false
       end
 
+      # What a self-contained build actually needs from the project at runtime:
+      # the entrypoint, the Ruby under lib/, and the assets that code loads by
+      # path (image(src: "assets/logo.png"), lottie(...), fonts, audio).
+      #
+      # Everything else is already consumed by the time the app runs. Lite gems
+      # are compiled into the VM; full-profile gems and lockfiles are staged by
+      # package_full_runtime_gems instead of copied from the working tree.
+      # ruflet.yaml and services.yaml have been turned into native configuration,
+      # while tests, CI and store artwork were never runtime inputs. Listing
+      # what belongs in rather than guessing what to leave out keeps unexpected
+      # directories from being shipped --
+      # release artwork once carried a lockfile that Apple read as an unsigned
+      # code object and rejected the whole upload over.
+      SELF_CONTAINED_PROJECT_ENTRYPOINT = "main.rb"
+      SELF_CONTAINED_PROJECT_DIRECTORIES = %w[lib assets].freeze
+
       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)
+
+        unless self_contained_project_path?(relative)
+          return false
+        end
+
         if secret_project_asset?(relative)
           build_note("Excluded #{relative} from the embedded project; it looks like a credential")
           return false
@@ -1871,6 +3388,13 @@ module Ruflet
         true
       end
 
+      def self_contained_project_path?(relative)
+        return true if relative == SELF_CONTAINED_PROJECT_ENTRYPOINT
+
+        top = relative.split(File::SEPARATOR).first
+        SELF_CONTAINED_PROJECT_DIRECTORIES.include?(top)
+      end
+
       def flutter_target_entrypoint(client_dir, self_contained:)
         candidate = File.join(
           client_dir,
@@ -1897,7 +3421,7 @@ module Ruflet
         return nil if key.empty?
 
         key.tr!("-", "_")
-        key.gsub!(/\A(flet_)+/, "")
+        key.gsub!(/\A(flet_)+/, "") # Compatibility for existing application configuration.
         key.gsub!(/\A(ruflet_)+/, "")
         key.gsub!(/\Aservice_/, "")
         key
@@ -1919,15 +3443,49 @@ module Ruflet
         write_pubspec_yaml(path, data)
       end
 
-      def sync_client_extension_dependencies(path, selected_packages)
-        return if selected_packages.empty?
+      def sync_client_package_directories(client_dir, selected_packages)
+        packages_root = File.join(client_dir, "ruflet_packages")
+
+        kept_packages = (["ruflet"] + selected_packages).uniq
+        template_root =
+          if Ruflet::CLI.respond_to?(:resolve_ruflet_client_template_root, true)
+            Ruflet::CLI.send(:resolve_ruflet_client_template_root)
+          end
+        template_packages_root = template_root && File.join(template_root, "ruflet_packages")
+
+        # These are disposable client sources, not application files. Refresh
+        # even existing packages so a rebuild cannot keep an older engine fork.
+        kept_packages.each do |package_name|
+          destination = File.join(packages_root, package_name)
+          next unless template_packages_root
+
+          source = File.join(template_packages_root, package_name)
+          next unless Dir.exist?(source)
+          next if File.expand_path(source) == File.expand_path(destination)
+
+          FileUtils.rm_rf(destination) if File.exist?(destination)
+          Ruflet::CLI.send(:copy_client_template_entry, template_packages_root, packages_root, package_name)
+        end
+
+        return unless Dir.exist?(packages_root)
+
+        Dir.children(packages_root).each do |entry|
+          path = File.join(packages_root, entry)
+          next unless Dir.exist?(path)
+          next if kept_packages.include?(entry)
 
+          FileUtils.rm_rf(path)
+        end
+      end
+
+      def sync_client_extension_dependencies(path, selected_packages)
         template_deps = template_client_pubspec_dependencies
         return if template_deps.empty?
 
         data = YAML.safe_load(read_text_file(path), aliases: true) || {}
         deps = (data["dependencies"] || {}).dup
-        selected_packages.each do |package_name|
+        deps.delete_if { |name, _| name == "flet" || name.start_with?("flet_") }
+        (["ruflet"] + selected_packages).each do |package_name|
           deps[package_name] = template_deps[package_name] if template_deps.key?(package_name)
         end
 
@@ -1935,6 +3493,49 @@ module Ruflet
         write_pubspec_yaml(path, data)
       end
 
+      # Check Pub's actual result, including transitive local forks. Merely
+      # declaring a path dependency is insufficient: an override can replace it.
+      def validate_local_ruflet_packages(client_dir)
+        config_path = File.join(client_dir, ".dart_tool", "package_config.json")
+        resolved = JSON.parse(File.read(config_path)).fetch("packages")
+        legacy = resolved.map { |entry| entry.fetch("name") }.select { |name| name == "flet" || name.start_with?("flet_") }
+        raise "legacy Flet packages resolved: #{legacy.join(', ')}" unless legacy.empty?
+
+        expected = (["ruflet"] + Array(@ruflet_selected_flutter_extension_packages)).to_h do |name|
+          [name, File.join(client_dir, "ruflet_packages", name)]
+        end
+        # The core/extension manifests also select local decoupled vendor forks.
+        queue = expected.values.dup
+        until queue.empty?
+          root = queue.shift
+          manifest = YAML.safe_load(File.read(File.join(root, "pubspec.yaml")), aliases: true)
+          (manifest["dependencies"] || {}).each do |name, dependency|
+            next unless dependency.is_a?(Hash) && dependency["path"]
+            next if expected.key?(name)
+
+            local = File.expand_path(dependency.fetch("path"), root)
+            expected[name] = local
+            queue << local
+          end
+        end
+        base = "file://#{URI::DEFAULT_PARSER.escape(File.expand_path(config_path))}"
+        expected.each do |name, root|
+          entry = resolved.find { |package| package["name"] == name }
+          raise "missing local package #{name}" unless entry
+
+          uri = URI.join(base, entry.fetch("rootUri"))
+          actual = URI::DEFAULT_PARSER.unescape(uri.path)
+          unless uri.scheme == "file" && File.realpath(actual) == File.realpath(root)
+            raise "#{name} must resolve to the bundled Ruflet source at #{root}, got #{uri}"
+          end
+        end
+        build_note("Verified #{expected.length} local Ruflet engine, extension and vendor packages")
+        true
+      rescue StandardError => e
+        warn "build config error: local Ruflet package verification failed: #{e.message}"
+        false
+      end
+
       def template_client_pubspec_dependencies
         template_root =
           if Ruflet::CLI.respond_to?(:resolve_ruflet_client_template_root, true)
@@ -2002,7 +3603,7 @@ module Ruflet
         if marker_index
           lines.insert(marker_index, extension_line)
         else
-          list_index = lines.index { |line| line.include?("final extensions = <FletExtension>[") }
+          list_index = lines.index { |line| line.include?("final extensions = <RufletExtension>[") }
           lines.insert(list_index ? list_index + 1 : lines.length, extension_line)
         end
         lines.join
@@ -2145,6 +3746,8 @@ module Ruflet
           ["build", "appbundle"]
         when "ios"
           ["build", "ios"]
+        when "ipa"
+          ["build", "ipa"]
         when "web"
           ["build", "web"]
         when "macos"