diff --git a/README.md b/README.md
index 2db81e81..08022ab8 100644
--- a/README.md
+++ b/README.md
@@ -232,11 +232,19 @@ the import and the `Extension()` call from the package name, which every
 extension package follows. `branch` and `tag` work in place of `ref`, and `path`
 takes a local checkout instead of a repository.
 
+At build time the managed Flutter client keeps the core `flet` package plus
+only the local packages selected by `extensions:` and `services:`. Packages
+removed for one build are restored automatically from the client template if a
+later configuration declares them again.
+
 ### Protected capabilities are explicit
 
 Camera, microphone, location, and motion access are declared in
 `services.yaml`. Ruflet activates the required client integrations and writes
-the matching Android and iOS permission descriptions during the build.
+the matching Android and iOS permission descriptions during the build. Ruflet
+also removes its previously managed permissions when the capability is no
+longer declared, so stale camera, microphone, location, or motion access does
+not ship in the next build.
 
 ```yaml
 services:
@@ -396,6 +404,9 @@ ruflet build apk --self
 ruflet build ios --self
 ```
 
+`ruflet build ios --self` prepares both the physical-device and simulator app
+bundles. You do not need a separate simulator build command.
+
 Install the latest mobile build on a connected device:
 
 ```bash
@@ -404,6 +415,10 @@ ruflet install
 ruflet install --device DEVICE_ID
 ```
 
+With one compatible mobile target connected, plain `ruflet install` selects it
+automatically; `--device` remains available when several matching targets are
+connected.
+
 Ruflet uses the canonical external Flutter template, resolves packages,
 applies app identity, generates splash screens and launcher icons, prepares
 native dependencies, and then runs the platform build.
diff --git a/packages/ruflet/lib/ruflet/cli/build_command.rb b/packages/ruflet/lib/ruflet/cli/build_command.rb
index 92de01fe..ddd3664f 100644
--- a/packages/ruflet/lib/ruflet/cli/build_command.rb
+++ b/packages/ruflet/lib/ruflet/cli/build_command.rb
@@ -29,6 +29,7 @@ module BuildCommand
         "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" },
+        "spinkit" => { package: "flet_spinkit", alias: "ruflet_spinkit" },
         "video" => { package: "flet_video", alias: "ruflet_video" },
         "webview" => { package: "flet_webview", alias: "ruflet_webview" }
       }.freeze
@@ -53,6 +54,14 @@ module BuildCommand
         "location" => "NSLocationWhenInUseUsageDescription",
         "motion" => "NSMotionUsageDescription"
       }.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 +
+        %w[NSLocationAlwaysAndWhenInUseUsageDescription NSPhotoLibraryUsageDescription]
+      ).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
@@ -156,6 +165,25 @@ def command_build(args)
 
         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")
+          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
@@ -1554,6 +1582,7 @@ def apply_service_extension_config(client_dir, config = {}, self_contained: @ruf
           prune_client_pubspec(pubspec_path, extension_packages)
           sync_external_extension_dependencies(pubspec_path, external)
         end
+        sync_client_package_directories(client_dir, extension_packages)
         client_entrypoint_paths(client_dir).each do |entrypoint|
           next unless File.file?(entrypoint)
 
@@ -1748,8 +1777,6 @@ def apply_native_service_permissions(client_dir, config)
         extension_services.each do |service|
           entries << { name: service, description: "" } unless entries.any? { |entry| entry[:name] == service }
         end
-        return if entries.empty?
-
         apply_android_service_permissions(client_dir, entries)
         apply_ios_service_usage_descriptions(client_dir, entries)
       end
@@ -1759,6 +1786,12 @@ def apply_android_service_permissions(client_dir, entries)
         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}"))
 
@@ -1772,6 +1805,12 @@ def apply_ios_service_usage_descriptions(client_dir, entries)
         return unless File.file?(path)
 
         content = read_text_file(path)
+        MANAGED_IOS_USAGE_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
@@ -1841,8 +1880,6 @@ def sync_client_pubspec_for_runtime_mode(client_dir, self_contained:)
         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)
@@ -1909,7 +1946,6 @@ def refresh_managed_client_template_files(client_dir, verbose: false)
           "lib/main.dart",
           "lib/main.self.dart",
           "lib/main.server.dart",
-          "lib/ruflet_file_picker_service.dart",
           "lib/connection_probe.dart",
           "lib/connection_probe_io.dart",
           "lib/connection_probe_stub.dart",
@@ -1934,6 +1970,11 @@ def refresh_managed_client_template_files(client_dir, verbose: false)
           FileUtils.cp(source, destination)
           build_log(verbose, "refreshed template file #{relative_path}")
         end
+
+        # Older managed clients carried a macOS-only FilePicker override. Flet'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"))
       end
 
       def write_pubspec_yaml(path, data)
@@ -2214,6 +2255,40 @@ def prune_client_pubspec(path, selected_packages)
         write_pubspec_yaml(path, data)
       end
 
+      def sync_client_package_directories(client_dir, selected_packages)
+        packages_root = File.join(client_dir, "flet_packages")
+        return unless Dir.exist?(packages_root)
+
+        kept_packages = (["flet"] + 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, "flet_packages")
+
+        # A declaration can change between builds. Restore newly selected local
+        # packages from the immutable template before pruning the old selection.
+        kept_packages.each do |package_name|
+          destination = File.join(packages_root, package_name)
+          next if Dir.exist?(destination)
+          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.cp_r(source, destination)
+        end
+
+        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)
         return if selected_packages.empty?
 
diff --git a/packages/ruflet/test/build_package_pruning_test.rb b/packages/ruflet/test/build_package_pruning_test.rb
new file mode 100644
index 00000000..483398ca
--- /dev/null
+++ b/packages/ruflet/test/build_package_pruning_test.rb
@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require "fileutils"
+
+class RufletCliBuildPackagePruningTest < Minitest::Test
+  class DummyBuilder
+    include Ruflet::CLI::BuildCommand
+  end
+
+  def test_keeps_only_core_and_packages_declared_by_services_and_extensions
+    builder = DummyBuilder.new
+
+    Dir.mktmpdir do |dir|
+      template_root = File.join(dir, "template")
+      client_dir = File.join(dir, "client")
+      package_names = %w[
+        flet flet_audio_recorder flet_permission_handler flet_spinkit flet_video
+      ]
+      package_names.each do |name|
+        FileUtils.mkdir_p(File.join(template_root, "flet_packages", name))
+        File.write(File.join(template_root, "flet_packages", name, "marker"), name)
+        FileUtils.mkdir_p(File.join(client_dir, "flet_packages", name))
+      end
+      FileUtils.mkdir_p(File.join(client_dir, "flet_packages", "flet_ads"))
+      FileUtils.mkdir_p(File.join(client_dir, "lib"))
+      File.write(
+        File.join(template_root, "pubspec.yaml"),
+        <<~YAML
+          dependencies:
+            flet_audio_recorder:
+              path: flet_packages/flet_audio_recorder
+            flet_permission_handler:
+              path: flet_packages/flet_permission_handler
+            flet_spinkit:
+              path: flet_packages/flet_spinkit
+            flet_video:
+              path: flet_packages/flet_video
+        YAML
+      )
+      File.write(
+        File.join(client_dir, "pubspec.yaml"),
+        "dependencies:\n  flet:\n    path: flet_packages/flet\n"
+      )
+
+      Ruflet::CLI.stub(:resolve_ruflet_client_template_root, template_root) do
+        builder.send(
+          :apply_service_extension_config,
+          client_dir,
+          { "services" => ["microphone"], "extensions" => ["spinkit"] }
+        )
+
+        assert_equal(
+          %w[flet flet_audio_recorder flet_permission_handler flet_spinkit],
+          package_directories(client_dir)
+        )
+
+        # A later build with a different declaration restores its package from
+        # the immutable template before pruning packages no longer selected.
+        builder.send(
+          :apply_service_extension_config,
+          client_dir,
+          { "extensions" => ["video"] }
+        )
+        assert_equal %w[flet flet_video], package_directories(client_dir)
+        assert_equal "flet_video", File.read(File.join(client_dir, "flet_packages", "flet_video", "marker"))
+      end
+    end
+  end
+
+  def test_native_permissions_are_replaced_by_current_service_declarations
+    builder = DummyBuilder.new
+
+    Dir.mktmpdir do |dir|
+      manifest = File.join(dir, "android", "app", "src", "main", "AndroidManifest.xml")
+      plist = File.join(dir, "ios", "Runner", "Info.plist")
+      FileUtils.mkdir_p(File.dirname(manifest))
+      FileUtils.mkdir_p(File.dirname(plist))
+      File.write(
+        manifest,
+        <<~XML
+          <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+            <uses-permission android:name="android.permission.INTERNET"/>
+            <uses-permission android:name="android.permission.CAMERA"/>
+            <uses-permission android:name="android.permission.RECORD_AUDIO"/>
+            <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
+            <uses-permission android:name="android.permission.FLASHLIGHT"/>
+            <application/>
+          </manifest>
+        XML
+      )
+      File.write(
+        plist,
+        <<~XML
+          <plist><dict>
+            <key>NSCameraUsageDescription</key><string>old camera</string>
+            <key>NSMicrophoneUsageDescription</key><string>old microphone</string>
+            <key>NSLocationWhenInUseUsageDescription</key><string>old location</string>
+            <key>NSPhotoLibraryUsageDescription</key><string>old photos</string>
+          </dict></plist>
+        XML
+      )
+
+      builder.send(
+        :apply_native_service_permissions,
+        dir,
+        { "services" => [{ "microphone" => { "description" => "Record voice notes." } }] }
+      )
+
+      android = File.read(manifest)
+      assert_includes android, "android.permission.INTERNET"
+      assert_includes android, "android.permission.RECORD_AUDIO"
+      refute_includes android, "android.permission.CAMERA"
+      refute_includes android, "android.permission.ACCESS_FINE_LOCATION"
+      refute_includes android, "android.permission.FLASHLIGHT"
+
+      ios = File.read(plist)
+      assert_includes ios, "NSMicrophoneUsageDescription"
+      assert_includes ios, "Record voice notes."
+      refute_includes ios, "NSCameraUsageDescription"
+      refute_includes ios, "NSLocationWhenInUseUsageDescription"
+      refute_includes ios, "NSPhotoLibraryUsageDescription"
+    end
+  end
+
+  private
+
+  def package_directories(client_dir)
+    Dir.children(File.join(client_dir, "flet_packages"))
+      .select { |entry| Dir.exist?(File.join(client_dir, "flet_packages", entry)) }
+      .sort
+  end
+end
diff --git a/packages/ruflet/test/update_command_test.rb b/packages/ruflet/test/update_command_test.rb
index 880dd72d..9dd50b79 100644
--- a/packages/ruflet/test/update_command_test.rb
+++ b/packages/ruflet/test/update_command_test.rb
@@ -281,7 +281,7 @@ def test_prepare_flutter_client_uses_source_ruby_runtime_dependency
       pubspec = File.read(File.join(client_dir, "pubspec.yaml"))
       ruby_runtime = YAML.safe_load(pubspec, aliases: true).dig("dependencies", "ruby_runtime")
       assert_equal File.expand_path("../../../ruby_runtime", __dir__), ruby_runtime["path"]
-      assert YAML.safe_load(pubspec, aliases: true).dig("dependencies", "flet_spinkit")
+      refute YAML.safe_load(pubspec, aliases: true).dig("dependencies", "flet_spinkit")
       refute_path_exists File.join(client_dir, "lib", "ruflet_spinkit.dart")
       assert_includes calls, client_dir
     end
@@ -876,7 +876,8 @@ def test_command_build_ios_uses_unbundled_env_for_flutter
 
       assert_equal 0, code
       refute calls.first[:env].key?("BUNDLE_GEMFILE")
-    assert_equal ["flutter", "build", "ios", "--codesign", "--target", "lib/main.self.dart"], calls.first[:args]
+      assert_equal ["flutter", "build", "ios", "--codesign", "--target", "lib/main.self.dart"], calls.first[:args]
+      assert_equal ["flutter", "build", "ios", "--simulator", "--target", "lib/main.self.dart"], calls.last[:args]
       refute_includes calls.first[:env]["PATH"], "/Users/macbookpro/.gem/ruby/3.4.0/bin"
       assert_includes calls.first[:env]["PATH"], File.join(client_dir, ".ruflet", "bin")
       assert File.executable?(File.join(client_dir, ".ruflet", "bin", "pod"))
@@ -934,6 +935,7 @@ def test_command_install_syncs_ios_build_outputs_and_runs_flutter_install
       ios_app_dir = File.join(dir, "build", "ios", "iphonesimulator", "Runner.app")
       FileUtils.mkdir_p(ios_app_dir)
       File.write(File.join(ios_app_dir, "Info.plist"), "plist")
+      File.write(File.join(ios_app_dir, "Runner"), "simulator executable")
 
       builder.define_singleton_method(:detect_flutter_client_dir) { client_dir }
       builder.define_singleton_method(:load_ruflet_config) { {} }
@@ -941,7 +943,6 @@ def test_command_install_syncs_ios_build_outputs_and_runs_flutter_install
         { flutter: "flutter", dart: "dart", env: {} }
       end
       builder.define_singleton_method(:prepare_flutter_client) { |_client_dir, **_kwargs| flunk("install should not run build preparation") }
-
       calls = []
       builder.define_singleton_method(:system) do |_env, *_args, chdir: nil|
         calls << { env: _env, args: _args, chdir: chdir }
@@ -1005,6 +1006,8 @@ def test_command_install_fails_when_no_built_outputs_exist
     builder = DummyBuilder.new
 
     Dir.mktmpdir do |dir|
+      previous_dir = Dir.pwd
+      Dir.chdir(dir)
       client_dir = File.join(dir, "ruflet_client")
       FileUtils.mkdir_p(File.join(client_dir, "lib"))
       File.write(File.join(client_dir, "lib", "main.server.dart"), "void main() {}\n")
@@ -1027,6 +1030,7 @@ def test_command_install_fails_when_no_built_outputs_exist
       assert_includes err.string, "Could not find built app outputs under ./build"
     ensure
       $stderr = original_stderr
+      Dir.chdir(previous_dir) if previous_dir
     end
   end
 
diff --git a/packages/ruflet_rails/Gemfile b/packages/ruflet_rails/Gemfile
new file mode 100644
index 00000000..9398fdbd
--- /dev/null
+++ b/packages/ruflet_rails/Gemfile
@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+# Develop against the sibling packages in this repo, not the released gems.
+# The HTML DSL leans on current ruflet_core (ControlFactory, the control
+# registry the transformer builds every tag from) and on ruflet_server's
+# WireCodec, so resolving those to a published version would test the gem
+# against code it is not actually shipping with.
+gem "ruflet", path: "../ruflet"
+gem "ruflet_core", path: "../ruflet_core"
+gem "ruflet_server", path: "../ruflet_server"
+
+group :development, :test do
+  gem "minitest", "~> 5.0"
+  gem "rake", "~> 13.0"
+end
diff --git a/packages/ruflet_rails/Gemfile.lock b/packages/ruflet_rails/Gemfile.lock
new file mode 100644
index 00000000..81032e49
--- /dev/null
+++ b/packages/ruflet_rails/Gemfile.lock
@@ -0,0 +1,338 @@
+PATH
+  remote: ../ruflet_core
+  specs:
+    ruflet_core (0.0.21)
+
+PATH
+  remote: ../ruflet_server
+  specs:
+    ruflet_server (0.0.21)
+      ruflet_core (= 0.0.21)
+
+PATH
+  remote: ../ruflet
+  specs:
+    ruflet (0.0.21)
+      rqrcode (~> 2.2)
+
+PATH
+  remote: .
+  specs:
+    ruflet_rails (0.0.16)
+      rails (>= 7.0)
+      ruflet (>= 0.0.21)
+      ruflet_core (>= 0.0.21)
+      ruflet_server (>= 0.0.21)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    action_text-trix (2.1.19)
+      railties
+    actioncable (8.1.3.1)
+      actionpack (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (8.1.3.1)
+      actionpack (= 8.1.3.1)
+      activejob (= 8.1.3.1)
+      activerecord (= 8.1.3.1)
+      activestorage (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      mail (>= 2.8.0)
+    actionmailer (8.1.3.1)
+      actionpack (= 8.1.3.1)
+      actionview (= 8.1.3.1)
+      activejob (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      mail (>= 2.8.0)
+      rails-dom-testing (~> 2.2)
+    actionpack (8.1.3.1)
+      actionview (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actiontext (8.1.3.1)
+      action_text-trix (~> 2.1.15)
+      actionpack (= 8.1.3.1)
+      activerecord (= 8.1.3.1)
+      activestorage (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (8.1.3.1)
+      activesupport (= 8.1.3.1)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (8.1.3.1)
+      activesupport (= 8.1.3.1)
+      globalid (>= 0.3.6)
+    activemodel (8.1.3.1)
+      activesupport (= 8.1.3.1)
+    activerecord (8.1.3.1)
+      activemodel (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      timeout (>= 0.4.0)
+    activestorage (8.1.3.1)
+      actionpack (= 8.1.3.1)
+      activejob (= 8.1.3.1)
+      activerecord (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      marcel (~> 1.0)
+    activesupport (8.1.3.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    builder (3.3.0)
+    chunky_png (1.4.0)
+    concurrent-ruby (1.3.8)
+    connection_pool (3.0.2)
+    crass (1.0.7)
+    date (3.5.1)
+    drb (2.2.3)
+    erb (6.0.6)
+    erubi (1.13.1)
+    globalid (1.4.0)
+      activesupport (>= 6.1)
+    i18n (1.15.2)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.21.1)
+    logger (1.7.0)
+    loofah (2.25.2)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.9.1)
+      logger
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.2.1)
+    mini_mime (1.1.5)
+    minitest (5.27.0)
+    net-imap (0.6.6)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.5)
+    nokogiri (1.19.4-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-linux-musl)
+      racc (~> 1.4)
+    pp (0.6.4)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    racc (1.8.1)
+    rack (3.2.6)
+    rack-session (2.1.2)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.3.1)
+      rack (>= 3)
+    rails (8.1.3.1)
+      actioncable (= 8.1.3.1)
+      actionmailbox (= 8.1.3.1)
+      actionmailer (= 8.1.3.1)
+      actionpack (= 8.1.3.1)
+      actiontext (= 8.1.3.1)
+      actionview (= 8.1.3.1)
+      activejob (= 8.1.3.1)
+      activemodel (= 8.1.3.1)
+      activerecord (= 8.1.3.1)
+      activestorage (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      bundler (>= 1.15.0)
+      railties (= 8.1.3.1)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.7.1)
+      loofah (~> 2.25, >= 2.25.2)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.1.3.1)
+      actionpack (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      tsort (>= 0.2)
+      zeitwerk (~> 2.6)
+    rake (13.4.2)
+    rbs (4.1.1)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    rdoc (8.0.0)
+      erb
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
+      tsort
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rqrcode (2.2.0)
+      chunky_png (~> 1.0)
+      rqrcode_core (~> 1.0)
+    rqrcode_core (1.2.0)
+    securerandom (0.4.1)
+    thor (1.5.0)
+    timeout (0.6.1)
+    tsort (0.2.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.1.1)
+    useragent (0.16.11)
+    websocket-driver (0.8.2)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.8.2)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  ruflet!
+  ruflet_core!
+  ruflet_rails!
+  ruflet_server!
+
+CHECKSUMS
+  action_text-trix (2.1.19) sha256=7012f59421009cf284aa651294896414d653a61a2417c9b8714c8476d2f74009
+  actioncable (8.1.3.1) sha256=e318528295c878a3efdfe25f0f2267c80cb7a76eba41bb5f64d44aa380a3d91b
+  actionmailbox (8.1.3.1) sha256=5f704972097d843ade8e435e93694a1dac732b926df1717aceba1f3840082b1c
+  actionmailer (8.1.3.1) sha256=88ea441b28ff02a0c6c006468892642a3d9942affce9d294e81a74504aa5c43c
+  actionpack (8.1.3.1) sha256=974cb7154548e81f470b1b0f247b99cb38e87825899dca58610596e2817723d0
+  actiontext (8.1.3.1) sha256=5da729d833d1a29cddb1eee938878e55e503d2613e00e735f5daf58c2ba98af2
+  actionview (8.1.3.1) sha256=2da68b8414c47b43bfbed1ce69c5afe1c04f78c267aacb5660a4cab5ca12cfb6
+  activejob (8.1.3.1) sha256=1c8dd275df930df40deecffec63d913a550a33fd94bd298f69721dd96939954a
+  activemodel (8.1.3.1) sha256=99cc02ce2faec371d14440949d85787ebd23a907c9baef0a9d4bcd4d21888f88
+  activerecord (8.1.3.1) sha256=0a2fb6c28f4938f6b013a3a549bec0a7e37d535f3dc8990e804bcc3258c0403b
+  activestorage (8.1.3.1) sha256=f555254f387b1cffa499d2fd3115d12635eadc5b15206a8534316a67036163ef
+  activesupport (8.1.3.1) sha256=85458765f25ea48b9019c46b6bb3fa5683197bf4280d9f06710a6e8d7a831376
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
+  builder (3.3.0) sha256=497918d2f9dca528fdca4b88d84e4ef4387256d984b8154e9d5d3fe5a9c8835f
+  chunky_png (1.4.0) sha256=89d5b31b55c0cf4da3cf89a2b4ebc3178d8abe8cbaf116a1dba95668502fdcfe
+  concurrent-ruby (1.3.8) sha256=b2f1be836e968ccc78ccfce277ea79c72a88633f22306782c16ff23fb415d1e1
+  connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
+  crass (1.0.7) sha256=94868719948664c89ddcaf0a37c65048413dfcb1c869470a5f7a7ceb5390b295
+  date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
+  drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
+  erb (6.0.6) sha256=a9b24986700f5bf127c4f297c5403c3ca41b83b0a316c0cd09a096b56e644ae5
+  erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
+  globalid (1.4.0) sha256=037f12fbf1d9d7a014d501c2d5c77356fd4ddd96d7a7991d6700bba96706f427
+  i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
+  io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
+  irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
+  json (2.21.1) sha256=13a43df75d95641443f5702dff350f237164a9d811ff0f2c2800d4d980220583
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  loofah (2.25.2) sha256=2007f746959ac65552456e04b433e83deb22759ab38c838b4445c70e43425918
+  mail (2.9.1) sha256=06574eca475253d6c18145dd70af80d0eb970182d55053497c5f4d797ea160e8
+  marcel (1.2.1) sha256=1678e9360e32f9eafa917c80029e2f6d10b2715c66a4b87b6d0da9b9cd1f859f
+  mini_mime (1.1.5) sha256=8681b7e2e4215f2a159f9400b5816d85e9d8c6c6b491e96a12797e798f8bccef
+  minitest (5.27.0) sha256=2d3b17f8a36fe7801c1adcffdbc38233b938eb0b4966e97a6739055a45fa77d5
+  net-imap (0.6.6) sha256=96aa4ee50df3060203e649efc341f53480b791d49e150f2fdebf68beb141a8df
+  net-pop (0.1.2) sha256=848b4e982013c15b2f0382792268763b748cce91c9e91e36b0f27ed26420dff3
+  net-protocol (0.2.2) sha256=aa73e0cba6a125369de9837b8d8ef82a61849360eba0521900e2c3713aa162a8
+  net-smtp (0.5.1) sha256=ed96a0af63c524fceb4b29b0d352195c30d82dd916a42f03c62a3a70e5b70736
+  nio4r (2.7.5) sha256=6c90168e48fb5f8e768419c93abb94ba2b892a1d0602cb06eef16d8b7df1dca1
+  nokogiri (1.19.4-aarch64-linux-gnu) sha256=1269fb644a6de405057a53dd5c762b1209b43ca7424f839454d3dbc677c31a8f
+  nokogiri (1.19.4-aarch64-linux-musl) sha256=35c65b9ce72b3bb03207bdbe7067915019dc18c1b9b59139684bd6690fdd01af
+  nokogiri (1.19.4-arm-linux-gnu) sha256=a301313e38bb065d68239e79734bcd6f56fb6efaacebde29e9abf2a4735340ca
+  nokogiri (1.19.4-arm-linux-musl) sha256=588923c101bcfa78869734d247d25b598674323e7f22474fc468f6e5647311eb
+  nokogiri (1.19.4-arm64-darwin) sha256=a46db9853286e6597b36ebc6953817d15acf3a299583eb3f89fdc6f91dd63527
+  nokogiri (1.19.4-x86_64-darwin) sha256=7fd17057d3e1f00e9954a74b3cd76595d3d4a5ef233b7ed9599047c204f70551
+  nokogiri (1.19.4-x86_64-linux-gnu) sha256=379fae440b28915e3f19d752ce2dcf8465ed2b2fbefd2a7ca0dd497bc981a06a
+  nokogiri (1.19.4-x86_64-linux-musl) sha256=17dfb7c1fa194ae02fbf7c51a7afc8d278045ab3fdacfd86f91d02d7b274470b
+  pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
+  prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rack (3.2.6) sha256=5ed78e1f73b2e25679bec7d45ee2d4483cc4146eb1be0264fc4d94cb5ef212c2
+  rack-session (2.1.2) sha256=595434f8c0c3473ae7d7ac56ecda6cc6dfd9d37c0b2b5255330aa1576967ffe8
+  rack-test (2.2.0) sha256=005a36692c306ac0b4a9350355ee080fd09ddef1148a5f8b2ac636c720f5c463
+  rackup (2.3.1) sha256=6c79c26753778e90983761d677a48937ee3192b3ffef6bc963c0950f94688868
+  rails (8.1.3.1) sha256=ccd11a36bfc171bf9c66d585d14c0ece91c0c9dde840aae60c0118d6f5c9c52a
+  rails-dom-testing (2.3.0) sha256=8acc7953a7b911ca44588bf08737bc16719f431a1cc3091a292bca7317925c1d
+  rails-html-sanitizer (1.7.1) sha256=e797a7c9b01e567307e317c576b49ab4168017e63eea4dba9ce3cb587e2f22c2
+  railties (8.1.3.1) sha256=2388a232579a00cefea4487de66c8553c3408c1300abdc6cf1799d86ffb04487
+  rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+  rbs (4.1.1) sha256=1bf118f2f95d1cd3956357645d495152b661e0257e57781d18ceecd461622b9e
+  rdoc (8.0.0) sha256=03bf8c08a9639658855a0cfd77c0abca8325c227693f7f33f82957811348c469
+  reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
+  rqrcode (2.2.0) sha256=23eea88bb44c7ee6d6cab9354d08c287f7ebcdc6112e1fe7bcc2d010d1ffefc1
+  rqrcode_core (1.2.0) sha256=cf4989dc82d24e2877984738c4ee569308625fed2a810960f1b02d68d0308d1a
+  ruflet (0.0.21)
+  ruflet_core (0.0.21)
+  ruflet_rails (0.0.16)
+  ruflet_server (0.0.21)
+  securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
+  thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
+  timeout (0.6.1) sha256=78f57368a7e7bbadec56971f78a3f5ecbcfb59b7fcbb0a3ed6ddc08a5094accb
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  tzinfo (2.0.6) sha256=8daf828cc77bcf7d63b0e3bdb6caa47e2272dcfaf4fbfe46f8c3a9df087a829b
+  uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
+  useragent (0.16.11) sha256=700e6413ad4bb954bb63547fa098dddf7b0ebe75b40cc6f93b8d54255b173844
+  websocket-driver (0.8.2) sha256=97c556b019bf3410b4961002ac501621e9322d3f8a7bc02161a09301cc4c4146
+  websocket-extensions (0.1.5) sha256=1c6ba63092cda343eb53fc657110c71c754c56484aad42578495227d717a8241
+  zeitwerk (2.8.2) sha256=7212a61311083c604184b1ea2574b9aa05cd14f855a0841c06985cabe9181d12
+
+BUNDLED WITH
+  4.0.11
diff --git a/packages/ruflet_rails/README.md b/packages/ruflet_rails/README.md
index d6b4f4c8..85d05a62 100644
--- a/packages/ruflet_rails/README.md
+++ b/packages/ruflet_rails/README.md
@@ -60,7 +60,7 @@ bundle exec rake ruflet:web
 Mount the installed client and a developer-owned Ruflet entrypoint:
 
 ```ruby
-mount Ruflet::Rails.web_app(app_file: Rails.root.join("app/views/ruflet/main.rb")), at: "/app"
+mount Ruflet::Rails.web(app_file: Rails.root.join("app/views/ruflet/main.rb")), at: "/app"
 ```
 
 The install generator adds the same mount at `/ruflet` when `--web` is used.
@@ -120,11 +120,214 @@ bundle exec rake ruflet:install
 bundle exec rake ruflet:install[DEVICE_ID]
 ```
 
+## HTML as the UI DSL (no WebView)
+
+Beyond the WebView shell, Ruflet can treat HTML itself as the UI language:
+Rails views describe screens with markup, and `Ruflet::Rails.html_to_native`
+compiles each page into **real native Ruflet controls** — no WebView anywhere.
+This is HTML-over-the-wire for native UI: state lives in Rails, every
+interaction is a request, and the response markup re-renders the screen.
+
+```ruby
+# app/views/ruflet/main.rb
+Ruflet.run do |page|
+  Ruflet::Rails.html_to_native(page, start_url: "#{Ruflet::Rails.backend_url}/native")
+end
+```
+
+Screens are ordinary Rails views (ERB, controllers, sessions, and redirects
+all work — requests carry the Rails session cookie and CSRF token, plus an
+`X-Ruflet-Native: 1` header so a controller can render native markup and a
+browser page from the same action):
+
+```erb
+<%# app/views/counters/show.html.erb %>
+<appbar title="Counter"></appbar>
+
+<column class="p-6 gap-4 items-center justify-center flex-1">
+  <text class="text-5xl font-bold text-slate-900"><%= @count %></text>
+  <row class="gap-3">
+    <button variant="outlined" icon="remove" on-click="<%= counter_decrement_path %>">Down</button>
+    <button variant="filled" icon="add" on-click="<%= counter_increment_path %>">Up</button>
+  </row>
+  <a href="<%= settings_path %>">Settings</a>
+</column>
+```
+
+- **Layout** — `<column>`, `<row>`, `<stack>`, `<div>`/`<section>` (container),
+  `<card>`, `<center>`, `<spacer>`, `<list>`, `<grid>`.
+- **Content** — `<text>`, `<h1>`–`<h6>`, `<p>`, `<markdown>`, `<img>`, `<icon>`,
+  `<hr>`, `<ul>`/`<li>`.
+- **Styling** — a broad Tailwind-flavored `class` vocabulary that maps onto
+  each control's real props (only the ones a control accepts are applied):
+  - spacing & size: `p-4`, `px-6`, `m-2`, `-mt-2`, `gap-3`, `w-64`, `h-full`,
+    `flex-1`, `aspect-video`, `aspect-[4/3]`
+  - color: `bg-slate-100`, `text-emerald-600`, `bg-[#123456]`, theme tokens
+    (`bg-primary`, `text-on-surface`), gradients
+    (`bg-gradient-to-r from-blue-500 via-sky-400 to-cyan-300`)
+  - typography: `text-xl`, `text-[42]`, `font-bold`, `font-mono`, `italic`,
+    `text-center`, `tracking-wide`, `leading-relaxed`, `underline`,
+    `line-through`, `uppercase`/`lowercase`/`capitalize`, `truncate`,
+    `line-clamp-2`, `whitespace-nowrap`, `select-none`, `text-ellipsis`
+  - shape & borders: `rounded-2xl`, `rounded-t-lg`, `rounded-br-sm`, `border`,
+    `border-2`, `border-t`, `border-red-500`, `shadow-lg`, `opacity-75`, `blur-md`
+  - transforms & position: `rotate-45`, `-rotate-12`, `scale-95`, `top-4`,
+    `left-2`, `inset-0`/`inset-x-4` (Stack children)
+  - transitions: `transition`, `duration-300`, `ease-in-out` (implicit animation)
+  - layout & display: `items-center`, `justify-between`, `place-center`,
+    `flex-wrap`, `gap-x-3`/`gap-y-2`, `size-12`, `w-screen`, `min-h-screen`,
+    `scroll`, `overflow-hidden`, `object-cover` (image fit), `hidden`/`invisible`
+  Anything not mapped is ignored; the full native prop is always available as
+  an explicit attribute (`gradient='{…}'`, `blur="8"`, …).
+- **Navigation** — `<a href>` pushes a native screen; `nav="replace|root|back"`
+  change the mode. The native back button/gesture pops.
+- **Actions** — `on-click="/counter/increment"` posts to Rails and re-renders
+  the current screen in place with the response (`redirect_to` is followed).
+  Prefix a verb for other methods: `on-click="delete:/items/3"`.
+- **Forms** — `<form action method>` with named `<input>`, `<textarea>`,
+  `<select>` fields tracks values natively and submits them like a normal
+  Rails form, then renders the response.
+- **App chrome** — `<appbar title="Inbox" leading-icon="menu">` with
+  `<action icon="search" href="/search"/>` children becomes the native AppBar.
+- **The whole widget catalog** — any other tag falls through to the ruflet_core
+  control registry with its attributes as props:
+  `<progress-bar value="0.4">`, `<switch label="Dark mode">`,
+  `<chip label="New">`… kebab-case maps to the control name.
+
+**First-class components** — these have dedicated tags/helpers that map to the
+right native shape (some Ruflet "components" are *props* on another control,
+not controls of their own — the DSL handles that for you):
+
+| Tag | Helper | Notes |
+| --- | --- | --- |
+| `<badge label="3">…</badge>` | `badge` | wraps its child; badge is a prop on it |
+| `<tooltip message="…">…</tooltip>` | `tooltip` | prop on its child |
+| `<chip label="Ruby" icon="star">` | `chip` | text → `label`; `on-click`/`href` supported |
+| `<avatar src>` / `<avatar>AM</avatar>` | `avatar` | image or initials |
+| `<list-tile title subtitle leading href>` | `list_tile` | taps navigate/act natively |
+| `<expansion-tile title>…</expansion-tile>` | `expansion_tile` | collapsible section |
+| `<switch>` `<checkbox>` `<slider>` `<radio>` | same | standalone; `name` makes them form fields |
+| `<radio-group name value>…radios…</radio-group>` | `radio_group` | |
+| `<segmented-button name value>…<segment>…</segmented-button>` | `segmented_button` | |
+| `<tabs><tab label icon>…</tab></tabs>` | `tabs` / `tab` | native TabBar + panes |
+| `<table><thead><tr><th>…` | — | plain HTML tables → native `DataTable` |
+| `<fab icon href>` | `fab` | mounts as the screen's FloatingActionButton |
+| `<bottom-nav><nav-item icon label href selected>…` | `bottom_nav` / `nav_item` | screen's NavigationBar; a tab resets to that URL as root |
+
+**Every Ruflet control is reachable.** Any tag without a dedicated builder
+maps straight onto the ruflet_core control registry — the entire catalog
+(charts, canvas, cupertino_*, maps, sensors, list/menu/expansion controls, …)
+works from markup. The passthrough is schema-aware: a control's text and child
+elements are routed into whichever prop it actually accepts (`content`,
+`controls`, `label`, `title`), so `<filled-button>Save</filled-button>`,
+`<banner><text>…</text></banner>`, and `<responsive-row>…</responsive-row>`
+all build correctly. Use the raw tag (kebab-case → control name) or the
+`widget` helper:
+
+```erb
+<%= widget "bar-chart", expand: true do %>
+  <%= widget "bar-chart-group", x: 0 do %>
+    <%= widget "bar-chart-rod", from_y: 0, to_y: 10 %>
+  <% end %>
+<% end %>
+
+<cupertino-activity-indicator animating="true"></cupertino-activity-indicator>
+```
+
+**Services and extensions.** Non-visual platform services (`<geolocator>`,
+`<battery>`, `<clipboard>`, `<flashlight>`, `<permission-handler>`,
+`<secure-storage>`, `<shared-preferences>`, `<file-picker>`, `<wakelock>`,
+`<share>`, `<url-launcher>`, the sensors, …) are non-visual: declaring one
+mounts it on the screen's service registry rather than in the layout. Extension
+controls that *do* render (`<camera>`, `<audio>`, `<video>`, `<lottie>`,
+`<rive>`, `<map>`, `<code-editor>`, `<web-view>`, `<spinkit>`,
+`<color-picker>`, the charts) render inline like any other control. Each has a
+matching helper:
+
+```erb
+<%= geolocator %>
+<%= camera id: "camera-preview", preview_enabled: true %>
+<%= video src: "clip.mp4" %>
+<%= lottie src: "loader.json" %>
+<%= map do %><%= widget "tile-layer", url_template: "…" %><% end %>
+```
+
+Buttons can invoke native services without a request back to Rails. Common
+operations have short names, and the open-ended `method`/`args` form exposes
+new service methods without waiting for another `ruflet_rails` release:
+
+```erb
+<%= button "Copy", service: "copy", text: "Hello from Rails" %>
+<%= button "Locate", service: "location" %>
+<%= button "Allow camera",
+           service: "permission-handler",
+           method: "request",
+           args: { permission: "camera" } %>
+```
+
+An inline extension can also be controlled by its native ID:
+
+```erb
+<%= audio id: "player", src: "https://example.com/song.mp3" %>
+<%= button "Play", service: "control", target: "player", method: "play" %>
+<%= button "Seek", service: "control", target: "player",
+                   method: "seek", position: 2_000 %>
+```
+
+Service results and errors are reported in a native dialog by default. For a
+stream such as an accelerometer, pass `result_target: "status-control-id"` to
+update an inline Text control instead.
+
+```erb
+<%# a form, natively rendered %>
+<form action="<%= session_path %>" method="post">
+  <column class="p-6 gap-4">
+    <h2>Sign in</h2>
+    <input type="email" name="email" label="Email" placeholder="you@example.com">
+    <input type="password" name="password" label="Password">
+    <input type="checkbox" name="remember" label="Remember me" checked>
+    <input type="submit" value="Sign in">
+  </column>
+</form>
+```
+
+### Ruby helper DSL
+
+The same markup can be authored with Ruby helpers (auto-included into
+ActionView), and both styles mix freely in one template. Attribute keys are
+snake_case and become kebab-case attributes (`on_click:` → `on-click`);
+Hash/Array values serialize as JSON:
+
+```erb
+<%= appbar "Counter" %>
+
+<%= column class: "p-6 gap-6 items-center justify-center flex-1" do %>
+  <%= text @count, class: "text-[96] font-bold" %>
+  <%= row class: "gap-3" do %>
+    <%= button "Down", variant: "outlined", icon: "remove",
+               on_click: counter_decrement_path %>
+    <%= button "Up", variant: "filled", icon: "add",
+               on_click: counter_increment_path %>
+  <% end %>
+  <%= link "Settings", settings_path %>
+<% end %>
+```
+
+Available helpers: layout (`column`, `row`, `stack`, `card`, `center`,
+`list`, `grid`, `spacer`, `divider`), content (`text`, `h1`–`h6`/`heading`,
+`markdown`, `image`, `icon`), interaction (`button`, `link`), chrome
+(`appbar`, `appbar_action`), forms (`form`, `input`, `textarea`, `dropdown`,
+`submit`), and `widget("progress-bar", value: 0.4)` for anything else in the
+control registry.
+
+Pick the mode per app: `html_to_native` when HTML should *become* native controls,
+`native_shell` when you want the real web page in a WebView with native chrome.
+
 ## Native WebView shell
 
 Beyond the server-driven UI, Ruflet can wrap an existing Rails HTML app in a
 managed native WebView. This is an opt-in shell: calling
-`Ruflet::Rails.native_app` wraps web pages in a native Ruflet shell whose body is
+`Ruflet::Rails.native_shell` wraps web pages in a native Ruflet shell whose body is
 a WebView. Plain `Ruflet.run { |page| ... }` remains a normal Ruflet app with no
 WebView wrapper or HTML adapter.
 
@@ -136,7 +339,7 @@ promote page chrome.
 ```ruby
 # app/views/ruflet/main.rb
 Ruflet.run do |page|
-  Ruflet::Rails.native_app(
+  Ruflet::Rails.native_shell(
     page,
     start_url: "https://myapp.com",
     title: "My App",                       # opt into a native AppBar (tracks <title>)
@@ -290,13 +493,13 @@ Add `data-ruflet-close="false"` when a sheet link should not dismiss:
 <%= ruflet_haptic_button "Tap", style: "light" %>
 ```
 
-For a Fizzy-style web app, keep `Ruflet::Rails.native_app` simple and opt in from
+For a Fizzy-style web app, keep `Ruflet::Rails.native_shell` simple and opt in from
 the views that need native treatment:
 
 ```ruby
 # app/views/ruflet/main.rb
 Ruflet.run do |page|
-  Ruflet::Rails.native_app(page, start_url: "#{Ruflet::Rails.backend_url}/")
+  Ruflet::Rails.native_shell(page, start_url: "#{Ruflet::Rails.backend_url}/")
 end
 ```
 
diff --git a/packages/ruflet_rails/Rakefile b/packages/ruflet_rails/Rakefile
new file mode 100644
index 00000000..41b7c020
--- /dev/null
+++ b/packages/ruflet_rails/Rakefile
@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
+task default: :test
diff --git a/packages/ruflet_rails/lib/generators/ruflet/install/install_generator.rb b/packages/ruflet_rails/lib/generators/ruflet/install/install_generator.rb
index 38668679..aaa8b81b 100644
--- a/packages/ruflet_rails/lib/generators/ruflet/install/install_generator.rb
+++ b/packages/ruflet_rails/lib/generators/ruflet/install/install_generator.rb
@@ -6,9 +6,8 @@
 module Ruflet
   module Generators
     class InstallGenerator < ::Rails::Generators::Base
-      class_option :web, type: :boolean, default: false, desc: "Install the prebuilt Ruflet web client"
       class_option :desktop, type: :boolean, default: false, desc: "Download the server-driven desktop Ruflet client"
-      class_option :client, type: :string, default: nil, desc: "Install prebuilt clients: web, desktop, all, or none"
+      class_option :client, type: :string, default: nil, desc: "Install prebuilt clients: desktop or none"
 
       desc "Install Ruflet into a Rails app."
 
@@ -31,21 +30,11 @@ def create_ruflet_initializer
       def mount_websocket
         routes = File.join(destination_root, "config", "routes.rb")
         return unless File.file?(routes)
-        return if File.read(routes).include?("Ruflet::Rails.app(")
+        return if File.read(routes).include?("Ruflet::Rails.native(")
 
         route Ruflet::Rails::InstallSupport.route_snippet(entrypoint: entrypoint_path)
       end
 
-      def mount_web_app
-        return unless web_requested?
-
-        routes = File.join(destination_root, "config", "routes.rb")
-        return unless File.file?(routes)
-        return if File.read(routes).include?("Ruflet::Rails.web_app(")
-
-        route Ruflet::Rails::InstallSupport.web_route_snippet(entrypoint: entrypoint_path)
-      end
-
       def add_desktop_flag_to_binstubs
         return unless desktop_requested?
 
@@ -57,7 +46,6 @@ def download_prebuilt_client
         client = requested_client
         return if client == "none"
 
-        install_web_client if %w[web all].include?(client)
         install_desktop_client if %w[desktop all].include?(client)
       rescue StandardError => e
         @client_download_failed = true
@@ -66,7 +54,6 @@ def download_prebuilt_client
 
       def print_install_status
         Ruflet::Rails::InstallSupport.install_next_steps(
-          target: install_target,
           entrypoint: entrypoint_path,
           client: requested_client
         ).each { |line| say line }
@@ -85,13 +72,11 @@ def entrypoint_path
       def requested_client
         explicit = options[:client].to_s.strip.downcase
         unless explicit.empty?
-          raise Thor::Error, "--client must be web, desktop, all, or none" unless %w[web desktop all none].include?(explicit)
+          raise Thor::Error, "--client must be desktop or none" unless %w[desktop none].include?(explicit)
 
           return explicit
         end
 
-        return "all" if options[:web] && options[:desktop]
-        return "web" if options[:web]
         return "desktop" if options[:desktop]
 
         "none"
@@ -101,19 +86,6 @@ def desktop_requested?
         %w[desktop all].include?(requested_client)
       end
 
-      def web_requested?
-        %w[web all].include?(requested_client)
-      end
-
-      def install_target
-        "ruflet"
-      end
-
-      def install_web_client
-        return if Ruflet::Rails::WebInstaller.install!(root: destination_root)
-
-        client_download_failed("web")
-      end
 
       def install_desktop_client
         require "ruflet/cli"
diff --git a/packages/ruflet_rails/lib/ruflet/rails.rb b/packages/ruflet_rails/lib/ruflet/rails.rb
index 74bd4642..0acc78b9 100644
--- a/packages/ruflet_rails/lib/ruflet/rails.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails.rb
@@ -28,67 +28,26 @@ def broadcast(&block)
       sessions.broadcast(&block)
     end
 
-    # WebSocket endpoint for native mobile/desktop clients. The developer owns
-    # the Ruflet entrypoint explicitly; there is no Rails component discovery:
+    # WebSocket endpoint for native clients (Ruflet Explorer, or a built
+    # mobile/desktop app). You own the Ruflet entrypoint explicitly; there is
+    # no Rails component discovery:
     #
     #   # a standalone Ruflet app file (Ruflet.run/MyApp.new.run), per session:
-    #   match "/ws", to: Ruflet::Rails.endpoint(app_file: Rails.root.join("app/ruflet/main.rb")), via: :all
+    #   match "/ws", to: Ruflet::Rails.native(Rails.root.join("app/ruflet/main.rb")), via: :all
     #
-    #   # a custom block:
-    #   match "/ws", to: Ruflet::Rails.endpoint { |page| MyHome.render(page) }, via: :all
+    #   # or a custom block:
+    #   match "/ws", to: Ruflet::Rails.native { |page| MyHome.render(page) }, via: :all
     #
-    # One of app_file: or a block is required.
-    def endpoint(app_file: nil, &block)
+    # One of an app file (positional) or a block is required.
+    def native(app_file = nil, &block)
       sources = [app_file, block].compact
-      raise ArgumentError, "endpoint accepts only one of app_file: or a block" if sources.length > 1
-      raise ArgumentError, "endpoint requires one of app_file: or a block" if sources.empty?
+      raise ArgumentError, "native accepts only one of an app file or a block" if sources.length > 1
+      raise ArgumentError, "native requires an app file or a block" if sources.empty?
 
       return Protocol::Runner.new.build_app_endpoint(file_path: app_file) if app_file
 
       Protocol::Runner.new(&block).build_endpoint
     end
 
-    # Shorthand for a standalone app-file endpoint.
-    #
-    #   match "/ws", to: Ruflet::Rails.app(Rails.root.join("app/ruflet/main.rb")), via: :all
-    def app(file_path)
-      endpoint(app_file: file_path)
-    end
-
-    # Self-contained web frontend, mountable under any route. Serves the
-    # Flutter web build (with <base href> rewritten to the mount point) and
-    # answers the Ruflet WebSocket on the same path. Routes stay routing-only;
-    # UI code lives in dev files:
-    #
-    #   # a standalone Ruflet app file (MyApp.new.run), loaded per session:
-    #   mount Ruflet::Rails.web_app(app_file: "app/ruflet/showcase/main.rb"), at: "/showcase"
-    #
-    #   # a custom block:
-    #   mount Ruflet::Rails.web_app { |page| MyHome.render(page) }, at: "/app"
-    #
-    # One of app_file: or a block is required.
-    def web_app(app_file: nil, build_dir: nil, &app_block)
-      sources = [app_file, app_block].compact
-      raise ArgumentError, "web_app accepts only one of app_file: or a block" if sources.length > 1
-      raise ArgumentError, "web_app requires one of app_file: or a block" if sources.empty?
-
-      Protocol::WebApp.new(
-        build_dir: build_dir,
-        entrypoint: web_app_entrypoint(app_file: app_file),
-        &app_block
-      )
-    end
-
-    def web_app_entrypoint(app_file: nil)
-      return unless app_file
-
-      absolute = app_file.to_s
-      lambda do |page, env|
-        loaded = Protocol::MobileLoader.new(File.expand_path(absolute)).load!
-        entry = loaded[:entrypoint]
-        entry.arity == 1 ? entry.call(page) : entry.call(page, env)
-      end
-    end
-
   end
 end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/desktop_launcher.rb b/packages/ruflet_rails/lib/ruflet/rails/desktop_launcher.rb
index 8da3c040..d782877f 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/desktop_launcher.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/desktop_launcher.rb
@@ -8,7 +8,7 @@ module DesktopLauncher
       module_function
 
       def launch_once(root:, argv: ARGV, env: ENV, wait: 1.0)
-        return false unless desktop_enabled?(root: root, argv: argv, env: env)
+        return false unless desktop_enabled?(argv: argv, env: env)
         return false unless env["RUFLET_RAILS_DESKTOP_SERVER"].to_s.downcase == "true" || rails_server_command?(argv)
         return false if env["RUFLET_RAILS_DESKTOP"].to_s.downcase == "false"
         return false if launched?
@@ -51,7 +51,7 @@ def backend_url(root:, argv: ARGV, env: ENV)
         "http://localhost:#{env["PORT"].to_s.empty? ? 3000 : env["PORT"]}"
       end
 
-      def desktop_enabled?(root:, argv: ARGV, env: ENV)
+      def desktop_enabled?(argv: ARGV, env: ENV)
         return true if env["RUFLET_RAILS_DESKTOP_SERVER"].to_s.downcase == "true"
         return true if env["RUFLET_RAILS_DESKTOP"].to_s.downcase == "true"
         return true if Array(argv).map(&:to_s).include?("--desktop")
diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
new file mode 100644
index 00000000..c31ab1ad
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "html_dsl/parser"
+require_relative "html_dsl/styles"
+require_relative "html_dsl/transformer"
+require_relative "html_dsl/template_source"
+require_relative "html_dsl/control_diff"
+require_relative "html_dsl/html_app"
+require_relative "html_dsl/view_helpers"
+
+module Ruflet
+  module Rails
+    # HTML as the UI DSL: Rails views describe screens with markup
+    # (`<column>`, `<row>`, `<text>`, `<button on-click>`, Tailwind-flavored
+    # classes) and Ruflet renders them as real native controls — no WebView.
+    module HtmlDsl
+    end
+
+    module_function
+
+    # Render your Rails ERB views as native controls, over the WebSocket. Each
+    # screen is a normal Rails route: it runs through routing and its controller
+    # — params, before_actions, saving a form, loading records, assigning
+    # `@ivars` — then the ERB view is compiled into a native control tree. The
+    # dispatch is in-process (a function call, not network HTTP: no socket, no
+    # disconnect); links navigate by URL and forms POST back through the
+    # controller.
+    #
+    #   # app/views/ruflet/main.rb  (runs in the /ws session)
+    #   Ruflet.run { |page| Ruflet::Rails.erb_to_native(page, start_url: "/native") }
+    #
+    # `start_url` is a path, because there is no second connection to point at:
+    # the client dials one route (the WebSocket) and every screen after that is
+    # dispatched in-process. When a host is needed at all — Rails still checks
+    # the Host header — it is taken from the connection the client actually
+    # made, so a phone on the LAN and a browser on localhost both work without
+    # configuring anything. A full URL is still accepted, and then names the
+    # host verbatim.
+    #
+    # A `fetcher:` can be injected for tests.
+    def erb_to_native(page, start_url: "/", **opts)
+      opts[:fetcher] ||= HtmlDsl::TemplateSource.new
+      HtmlDsl::HtmlApp.new(page, start_url: start_url, **opts).start
+    end
+  end
+end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/control_diff.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/control_diff.rb
new file mode 100644
index 00000000..ec3fed12
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/control_diff.rb
@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Ruflet
+  module Rails
+    module HtmlDsl
+      # Compares the control tree already mounted on a screen with the one just
+      # built from fresh markup, and reports the minimum set of prop updates
+      # that turns the first into the second.
+      #
+      # Re-rendering a screen in place otherwise means shipping every control
+      # on it to change one value — a counter tick re-sends the heading, both
+      # buttons and the caption to move a single digit, and the client rebuilds
+      # that subtree (losing scroll position and any transient widget state).
+      #
+      # The diff is deliberately conservative: it only reports updates when the
+      # two trees have exactly the same shape (same control types, same number
+      # of children, same prop-held controls, in the same order). Any structural
+      # difference returns nil, and the caller replaces the body wholesale as
+      # before. Shape changes are where a diff would be subtly wrong, and they
+      # are also the case where a full replace costs what it should.
+      class ControlDiff
+        # Props whose values are server-side plumbing, never wire state.
+        SKIPPED_PROPS = %w[key].freeze
+
+        def initialize(old_tree, new_tree)
+          @old_tree = old_tree
+          @new_tree = new_tree
+        end
+
+        # [[mounted_control, {prop => value}], …], or nil when the shape moved.
+        def updates
+          @updates = []
+          return nil unless walk(@old_tree, @new_tree)
+
+          @updates
+        end
+
+        private
+
+        def walk(old_node, new_node)
+          return true if old_node.nil? && new_node.nil?
+          return false if old_node.nil? || new_node.nil?
+
+          if old_node.is_a?(Array) || new_node.is_a?(Array)
+            return false unless old_node.is_a?(Array) && new_node.is_a?(Array)
+            return false unless old_node.length == new_node.length
+
+            return old_node.each_with_index.all? { |item, i| walk(item, new_node[i]) }
+          end
+
+          return old_node == new_node unless control?(old_node) || control?(new_node)
+          return false unless control?(old_node) && control?(new_node)
+          return false unless old_node.type == new_node.type
+          return false unless old_node.children.length == new_node.children.length
+
+          return false unless compare_props(old_node, new_node)
+
+          old_node.children.each_with_index.all? { |child, i| walk(child, new_node.children[i]) }
+        end
+
+        def compare_props(old_node, new_node)
+          keys = (old_node.props.keys | new_node.props.keys) - SKIPPED_PROPS
+          changed = {}
+
+          keys.each do |key|
+            old_value = old_node.props[key]
+            new_value = new_node.props[key]
+
+            # A prop holding controls is structure: recurse instead of comparing.
+            if holds_controls?(old_value) || holds_controls?(new_value)
+              return false unless walk(old_value, new_value)
+
+              next
+            end
+
+            changed[key.to_sym] = new_value unless old_value == new_value
+          end
+
+          # The fresh tree carries handlers bound to this render (a button's
+          # on-click closes over the screen it was built for). Move them onto
+          # the mounted control so taps keep working after a patch; handlers
+          # live server-side, so this costs nothing on the wire.
+          rebind_handlers(old_node, new_node)
+
+          @updates << [old_node, changed] unless changed.empty?
+          true
+        end
+
+        def rebind_handlers(old_node, new_node)
+          handlers = new_node.instance_variable_get(:@handlers)
+          return if handlers.nil? || handlers.empty?
+
+          old_node.instance_variable_set(:@handlers, handlers)
+        end
+
+        def control?(node)
+          node.is_a?(Ruflet::Control)
+        end
+
+        def holds_controls?(value)
+          return true if control?(value)
+          return value.any? { |item| control?(item) } if value.is_a?(Array)
+
+          false
+        end
+      end
+    end
+  end
+end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
new file mode 100644
index 00000000..c926d3f9
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -0,0 +1,1305 @@
+# frozen_string_literal: true
+
+require "uri"
+require "erb"
+require "json"
+
+module Ruflet
+  module Rails
+    module HtmlDsl
+      # HTML-over-the-wire native UI: a Rails template renders HTML DSL markup
+      # and this app turns each screen into real Ruflet controls — no WebView.
+      # Links push native screens, `on-click` runs a controller method and
+      # re-renders the screen in place, forms hand their field values to one.
+      class HtmlApp
+        Screen = Struct.new(:url, :view, :route, :root, :fields, :title,
+                            :appbar_sig, :fab_sig, :nav_sig, :body, :markup, keyword_init: true)
+
+        # Event handlers stay bound to the screen whose markup declared them,
+        # so a control on a covered screen still targets the right state.
+        class ScreenHandlers
+          def initialize(app, screen)
+            @app = app
+            @screen = screen
+          end
+
+          def navigate(url, mode) = @app.navigate(url, mode)
+          def action(url:) = @app.action(url: url, from: @screen)
+          def submit_form(form) = @app.submit_form(form, from: @screen)
+          def field_changed(name, value) = @screen.fields[name] = value
+          def service(spec) = @app.run_service(spec)
+          def control_event(spec, event) = @app.handle_control_event(spec, event)
+        end
+
+        def initialize(page, start_url:, title: nil, fetcher: nil)
+          @page = page
+          @start_url = start_url.to_s
+          @title = title
+          @fetcher = fetcher || default_fetcher
+          @screens = []
+          @route_seq = 0
+          @service_request_token = 0
+        end
+
+        def start
+          @page.on_view_pop = ->(_event) { pop }
+          push_screen(@start_url, root: true)
+          self
+        end
+
+        # Screens are rendered in the session itself, with no request behind
+        # them, so the whole session stays on its single WebSocket thread.
+        def default_fetcher
+          TemplateSource.new
+        end
+
+        # --- navigation ---------------------------------------------------------
+
+        def navigate(url, mode)
+          url = absolute_url(url)
+          case mode.to_s
+          when "back"
+            pop
+          when "root"
+            @screens.clear
+            push_screen(url, root: true)
+          when "replace"
+            @screens.pop
+            push_screen(url, root: @screens.empty?)
+          else
+            push_screen(url, root: @screens.empty?)
+          end
+        end
+
+        # An `on-click` action: run the method the URL names, then re-render
+        # the screen it was tapped on with the markup that comes back.
+        def action(url:, from: nil)
+          screen = from || @screens.last
+          return unless screen
+
+          response = request(absolute_url(url))
+          rerender(screen, response)
+        end
+
+        def submit_form(form, from: nil)
+          screen = from || @screens.last
+          return unless screen
+
+          params = form[:fields].keys.each_with_object({}) do |name, collected|
+            value = screen.fields.key?(name) ? screen.fields[name] : form[:fields][name]
+            collected[name] = value.nil? ? "" : value
+          end
+          response = request(absolute_url(form[:action]), params: params)
+          rerender(screen, response)
+        end
+
+        def pop
+          return if @screens.size <= 1
+
+          invalidate_pending_services
+          @screens.pop
+          flush
+        end
+
+        # A pending service result belongs to the screen that asked for it.
+        # Bumping the request token when the stack changes means a slow result
+        # that lands after the user has navigated away is ignored, instead of
+        # surfacing on whatever screen happens to be visible now.
+        def invalidate_pending_services
+          @service_request_token += 1
+        end
+
+        # Run a native platform service in response to a tap
+        # (`<button service="copy" text="…">`). Everything the device can do is
+        # reachable this way: the tap invokes the matching native method and,
+        # for anything that returns data or can fail, the result comes back in
+        # a native result dialog. Streaming services can target an inline Text
+        # control instead, so rapid readings do not cover the application UI.
+        def run_service(spec)
+          @service_request_token += 1
+          @service_result_target = spec["result-target"]
+          name = spec["service"].to_s.downcase.tr("_", "-")
+          case name
+          # --- clipboard --------------------------------------------------------
+          when "copy", "clipboard", "clipboard-set"
+            @page.set_clipboard(spec["text"].to_s)
+            show_service_result(spec["toast"] || "Copied to clipboard", title: "Clipboard",
+                                                                          target: @service_result_target)
+          when "paste", "read-clipboard", "clipboard-get"
+            @page.get_clipboard(on_result: report("Clipboard", show_result: true))
+          when "clipboard-set-files"
+            @page.set_clipboard_files(array_value(spec["files"]), on_result: report("Clipboard files saved"))
+          when "clipboard-get-files"
+            @page.get_clipboard_files(on_result: report("Clipboard files", show_result: true))
+          when "clipboard-set-image"
+            @page.set_clipboard_image(spec["value"] || spec["data"], on_result: report("Clipboard image saved"))
+          when "clipboard-get-image"
+            @page.get_clipboard_image(on_result: report("Clipboard image", show_result: true))
+          # --- share ------------------------------------------------------------
+          when "share", "share-text"
+            @page.share_text(spec["text"].to_s, title: spec["title"], subject: spec["subject"],
+                                                     on_result: report(spec["toast"] || "Share sheet opened"))
+          when "share-link", "share-url", "share-uri"
+            @page.share_uri((spec["uri"] || spec["url"]).to_s, on_result: report("Share sheet opened"))
+          when "share-files"
+            @page.share_files(array_value(spec["files"]), text: spec["text"], title: spec["title"],
+                                                          subject: spec["subject"],
+                                                          on_result: report("Share sheet opened"))
+          # --- haptics ----------------------------------------------------------
+          when "haptic", "vibrate"
+            run_haptic(spec["style"])
+            show_service_result(spec["toast"] || "Haptic feedback", title: "Haptics",
+                                                                     target: @service_result_target)
+          # --- links ------------------------------------------------------------
+          when "launch", "open", "url"
+            @page.launch_url(spec["url"].to_s, mode: spec["mode"], on_result: report("Link opened"))
+          when "can-launch"
+            invoke_named_service("url_launcher", "can_launch_url", { "url" => spec["url"] }, "Can launch")
+          when "open-window"
+            @page.open_window(spec["url"].to_s, title: spec["title"], width: spec["width"],
+                                                     height: spec["height"], on_result: report("Window opened"))
+          when "close-in-app-web-view"
+            @page.close_in_app_web_view(on_result: report("In-app browser closed"))
+          # --- hardware ---------------------------------------------------------
+          when "flashlight", "torch"
+            toggle_flashlight
+          when "flashlight-on", "torch-on"
+            @page.flashlight.on(on_result: report("Torch on"))
+            @flashlight_on = true
+          when "flashlight-off", "torch-off"
+            @page.flashlight.off(on_result: report("Torch off"))
+            @flashlight_on = false
+          when "flashlight-available"
+            @page.flashlight.is_available(on_result: report("Flashlight available", show_result: true))
+          when "wakelock", "keep-awake"
+            toggle_wakelock
+          when "wakelock-enable"
+            @page.wakelock.enable(on_result: report("Staying awake"))
+            @wakelock_on = true
+          when "wakelock-disable"
+            @page.wakelock.disable(on_result: report("Sleep allowed"))
+            @wakelock_on = false
+          when "wakelock-status"
+            @page.wakelock.is_enabled(on_result: report("Wakelock enabled", show_result: true))
+          when "brightness"
+            level = clamp_unit(spec["value"], 0.5)
+            @page.screen_brightness.set_application_screen_brightness(
+              level, on_result: report("Brightness #{(level * 100).round}%")
+            )
+          when "brightness-get", "brightness-application"
+            invoke_named_service("screen_brightness", "get_application_screen_brightness", nil,
+                                 "Application brightness", show_result: true)
+          when "brightness-system-get"
+            invoke_named_service("screen_brightness", "get_system_screen_brightness", nil,
+                                 "System brightness", show_result: true)
+          when "brightness-can-change-system"
+            invoke_named_service("screen_brightness", "can_change_system_screen_brightness", nil,
+                                 "Can change system brightness", show_result: true)
+          when "brightness-animate-get"
+            invoke_named_service("screen_brightness", "is_animate", nil,
+                                 "Brightness animation", show_result: true)
+          when "brightness-auto-reset-get"
+            invoke_named_service("screen_brightness", "is_auto_reset", nil,
+                                 "Brightness auto reset", show_result: true)
+          when "brightness-system"
+            level = clamp_unit(spec["value"], 0.5)
+            @page.screen_brightness.set_system_screen_brightness(
+              level, on_result: report("System brightness #{(level * 100).round}%")
+            )
+          when "brightness-animate-set"
+            invoke_named_service("screen_brightness", "set_animate", { "value" => truthy?(spec["value"]) },
+                                 "Brightness animation")
+          when "brightness-auto-reset-set"
+            invoke_named_service("screen_brightness", "set_auto_reset", { "value" => truthy?(spec["value"]) },
+                                 "Brightness auto reset")
+          when "brightness-reset"
+            invoke_named_service("screen_brightness", "reset_application_screen_brightness", nil,
+                                 "Application brightness reset")
+          # --- queries ----------------------------------------------------------
+          when "battery"
+            read_battery
+          when "battery-level"
+            @page.get_battery_level(on_result: report("Battery level", show_result: true))
+          when "battery-state"
+            @page.get_battery_state(on_result: report("Battery state", show_result: true))
+          when "battery-save-mode"
+            @page.is_in_battery_save_mode(on_result: report("Battery save mode", show_result: true))
+          when "connectivity"
+            @page.get_connectivity(on_result: report("Connectivity", show_result: true))
+          when "location", "geolocate", "position"
+            geolocator.get_current_position(on_result: report("Position", show_result: true))
+          when "location-last"
+            geolocator.get_last_known_position(on_result: report("Last position", show_result: true))
+          when "location-permission"
+            geolocator.get_permission_status(on_result: report("Location permission", show_result: true))
+          when "location-request-permission"
+            geolocator.request_permission(on_result: report("Location permission", show_result: true))
+          when "location-service-enabled"
+            geolocator.is_location_service_enabled(on_result: report("Location service", show_result: true))
+          when "location-open-settings"
+            geolocator.open_location_settings(on_result: report("Location settings opened"))
+          when "location-open-app-settings"
+            geolocator.open_app_settings(on_result: report("App settings opened"))
+          when "location-distance"
+            geolocator.distance_between(
+              spec["start-latitude"], spec["start-longitude"], spec["end-latitude"], spec["end-longitude"],
+              on_result: report("Distance", show_result: true)
+            )
+          # --- secure storage ---------------------------------------------------
+          when "secure-set"
+            secure_storage.set(spec["key"].to_s, spec["value"].to_s, on_result: report("Stored securely"))
+          when "secure-get"
+            secure_storage.get(spec["key"].to_s, on_result: report("Secure value", show_result: true))
+          when "secure-contains"
+            secure_storage.contains_key(spec["key"].to_s,
+                                        on_result: report("Secure key exists", show_result: true))
+          when "secure-all"
+            secure_storage.get_all(on_result: report("Secure values", show_result: true))
+          when "secure-remove"
+            secure_storage.remove(spec["key"].to_s, on_result: report("Secure value removed"))
+          when "secure-clear"
+            secure_storage.clear(on_result: report("Secure storage cleared"))
+          when "secure-availability"
+            secure_storage.get_availability(on_result: report("Secure storage", show_result: true))
+          # --- shared preferences -----------------------------------------------
+          when "prefs-set", "preference-set"
+            @page.shared_preferences.set(spec["key"].to_s, spec["value"],
+                                         on_result: report("Preference saved"))
+          when "prefs-get", "preference-get"
+            @page.shared_preferences.get(spec["key"].to_s, on_result: report("Preference", show_result: true))
+          when "prefs-contains", "preference-contains"
+            @page.shared_preferences.contains_key(
+              spec["key"].to_s, on_result: report("Preference exists", show_result: true)
+            )
+          when "prefs-keys", "preference-keys"
+            @page.shared_preferences.get_keys(
+              spec["prefix"], on_result: report("Preference keys", show_result: true)
+            )
+          when "prefs-remove", "preference-remove"
+            @page.shared_preferences.remove(spec["key"].to_s, on_result: report("Preference removed"))
+          when "prefs-clear", "preference-clear"
+            @page.shared_preferences.clear(on_result: report("Preferences cleared"))
+          # --- permissions ------------------------------------------------------
+          when "permission", "request-permission"
+            permissions.request(spec["name"].to_s, timeout: interactive_timeout(spec),
+                                                   on_result: report("Permission", show_result: true))
+          when "permission-status"
+            permissions.get_status(spec["name"].to_s, on_result: report("Permission", show_result: true))
+          when "permission-settings"
+            permissions.open_app_settings(on_result: report("App settings opened"))
+          # --- files and paths ---------------------------------------------------
+          when "pick-files", "file-picker"
+            @page.pick_files(
+              dialog_title: spec["dialog-title"], initial_directory: spec["initial-directory"],
+              file_type: spec["file-type"] || "any",
+              allowed_extensions: array_value(spec["allowed-extensions"]),
+              allow_multiple: truthy?(spec["allow-multiple"]), with_data: truthy?(spec["with-data"]),
+              timeout: interactive_timeout(spec),
+              on_result: report("Selected files", show_result: true)
+            )
+          when "pick-directory", "directory-picker"
+            @page.get_directory_path(
+              dialog_title: spec["dialog-title"], initial_directory: spec["initial-directory"],
+              timeout: interactive_timeout(spec),
+              on_result: report("Selected directory", show_result: true)
+            )
+          when "save-file"
+            @page.save_file(
+              dialog_title: spec["dialog-title"], file_name: spec["file-name"],
+              initial_directory: spec["initial-directory"], file_type: spec["file-type"] || "any",
+              allowed_extensions: array_value(spec["allowed-extensions"]),
+              src_bytes: binary_bytes(spec["src-bytes"]),
+              timeout: interactive_timeout(spec),
+              on_result: report("Saved file", show_result: true)
+            )
+          when /\Astorage-(.+)\z/
+            method = storage_path_method(Regexp.last_match(1))
+            method ? @page.public_send(method, on_result: report("Storage path", show_result: true)) :
+              show_service_result("Unknown storage path: #{Regexp.last_match(1)}", title: "Storage path")
+          # --- accessibility and recording --------------------------------------
+          when "announce", "semantics-announce"
+            semantics.announce_message(
+              spec["message"] || spec["text"], rtl: truthy?(spec["rtl"]),
+              assertiveness: spec["assertiveness"] || "polite",
+              on_result: report("Accessibility message announced")
+            )
+          when "semantics-tooltip"
+            semantics.announce_tooltip(spec["message"] || spec["text"],
+                                       on_result: report("Accessibility tooltip announced"))
+          when "semantics-features"
+            semantics.get_accessibility_features(
+              on_result: report("Accessibility features", show_result: true)
+            )
+          when /\Aaudio-recorder-(.+)\z/
+            run_audio_recorder(Regexp.last_match(1), spec)
+          when /\A(accelerometer|user-accelerometer|gyroscope|magnetometer|barometer)-(start|stop)\z/
+            toggle_sensor(Regexp.last_match(1), Regexp.last_match(2), spec)
+          when "camera-open", "camera-initialize"
+            open_camera(spec)
+          when "camera-capture", "camera-take-picture"
+            capture_camera_picture(spec)
+          # --- extension controls and generic service escape hatch --------------
+          when "control"
+            invoke_target_control(spec)
+          else
+            invoke_generic_service(name, spec)
+          end
+        rescue StandardError => e
+          show_service_result(e.message, title: "#{service_label(name)} failed",
+                                         target: @service_result_target)
+        end
+
+        # Declarative extension callback used by ERB attributes such as:
+        #   on-loaded-target="audio-status" on-loaded-message="Audio loaded"
+        #   on-change-control="demo-rive" on-change-property="speed_multiplier"
+        def handle_control_event(spec, event)
+          data = event.respond_to?(:data) ? event.data : event
+          value = if data.is_a?(Hash)
+                    data["value"] || data[:value] || (data.one? ? data.values.first : data)
+                  else
+                    data
+                  end
+
+          if spec["control"] && spec["property"]
+            control = @page.get_control(spec["control"].to_s)
+            @page.update(control, spec["property"].to_s.tr("-", "_").to_sym => value) if control
+          end
+
+          # The event can re-run a whole service (e.g. battery re-reads level /
+          # state / saver on `on_state_change`), which reports for itself.
+          if spec["service"]
+            return run_service("service" => spec["service"], "result-target" => spec["result-target"])
+          end
+
+          target = spec["target"]
+          return unless target
+
+          message = spec["message"]
+          message = "#{spec['prefix']}#{format_service_value(value)}" if message.to_s.empty?
+          show_service_result(message, target: target)
+        end
+
+        private
+
+        # --- screens --------------------------------------------------------------
+
+        # A new screen is fetched and rendered atomically, then pushed as one
+        # complete View. Painting a placeholder first (spinner + a guessed app
+        # bar) only to swap it for the real chrome makes the screen visibly
+        # flicker/shake; a single push lets the client run one clean transition.
+        def push_screen(url, root: false)
+          url = absolute_url(url)
+          return if url.empty?
+
+          invalidate_pending_services
+          screen = Screen.new(url: url, root: root, fields: {})
+          screen.route = root ? "/" : "/screen/#{@route_seq += 1}"
+          response = request(url)
+          result = render_result(screen, response)
+          screen.view = build_view(screen, result)
+          remember_chrome(screen, result)
+          @screens.push(screen)
+          # The service registry may immediately send a page update. Put the
+          # completed screen on the stack first so that first update already
+          # contains the real view instead of an empty/previous screen.
+          mount_services(result)
+          flush
+          run_on_load(result)
+          screen
+        end
+
+        # Run each `on-load` service once the screen is mounted and its services
+        # are registered — Studio's build-time `refresh_info.call` that fills a
+        # panel (battery, screen brightness, …) before the user taps anything.
+        def run_on_load(result)
+          Array(result.on_load).each { |spec| run_service(spec) }
+        rescue StandardError
+          nil
+        end
+
+        # Mount a screen's declared services (`<geolocator>`, `<battery>`, …) on
+        # the page's service registry so they register with the client. Each
+        # screen owns its services; navigating replaces them.
+        # Services are what `invoke` targets. If mounting fails the control
+        # never reaches the client, every later invoke waits for an answer that
+        # cannot come, and the screen reports "execution expired" — a timeout
+        # standing in for a mount error nobody saw. Swallowing the cause here
+        # is what made camera/recorder/audio failures unreadable, so say it.
+        def mount_services(result)
+          return unless @page.respond_to?(:services=)
+
+          @page.services = result.services
+        rescue StandardError => e
+          warn "[ruflet_rails] mounting services failed: #{e.class}: #{e.message}"
+          show_service_result("Services could not be mounted: #{e.message}",
+                              title: "Screen services failed")
+        end
+
+        # Attributes the DSL consumes itself. Everything else on a service
+        # element becomes a native invoke argument, so anything that is really
+        # markup — the button's own styling, its icon, its variant, the
+        # `on-load` marker — has to be named here. It is not cosmetic: a `play`
+        # that arrives carrying `class`/`icon`/`variant` is a call the client
+        # cannot match to the control's method signature, which is exactly how
+        # the ERB audio buttons ended up doing nothing at all.
+        SERVICE_META_KEYS = %w[
+          service method target args toast timeout id disabled
+          class icon variant on-load file-name output-path path configuration upload encoder
+        ].freeze
+
+        # Anything naming a control to update — result-target, capture-target,
+        # indicator-target, record-target, … — is markup, and apps keep
+        # inventing new ones. Match the shape instead of listing them: an
+        # invented name that leaks becomes an argument the client cannot match
+        # to the method's signature, and the tap silently does nothing.
+        CONTROL_TARGET_ATTRIBUTE = /-target\z/
+
+        # Declarative event wiring (`on-loaded-target`, `on-error-prefix`, …) is
+        # markup too, and there is one per event, so match them by shape.
+        DECLARED_EVENT_ATTRIBUTE = /\Aon-.+-(?:target|service|prefix|message|control|property|result-target)\z/
+
+        STORAGE_PATH_METHODS = {
+          "cache" => :get_application_cache_directory,
+          "documents" => :get_application_documents_directory,
+          "support" => :get_application_support_directory,
+          "downloads" => :get_downloads_directory,
+          "external-cache" => :get_external_cache_directories,
+          "external-storage-directories" => :get_external_storage_directories,
+          "external-storage" => :get_external_storage_directory,
+          "library" => :get_library_directory,
+          "temporary" => :get_temporary_directory,
+          "temp" => :get_temporary_directory,
+          "console-log" => :get_console_log_filename
+        }.freeze
+
+        def storage_path_method(name)
+          STORAGE_PATH_METHODS[name.to_s.tr("_", "-")]
+        end
+
+        # Reuse the service the screen already mounted (matched by type) without
+        # passing any props to it. Passing props to an existing service merges
+        # and RE-REGISTERS it — a service-container update sent right before we
+        # invoke, which can make the client tear down and rebuild the control at
+        # the very moment the invoke arrives (→ "execution expired"). Studio never
+        # re-touches a service after creating it; this mirrors that. Only when the
+        # screen declared no such service do we create one, with a stable key.
+        def reuse_service(type, key)
+          compact = type.to_s.delete("_").downcase
+          existing = @page.services.find do |service|
+            service.respond_to?(:type) && service.type.to_s.delete("_").downcase == compact
+          end
+          existing || @page.service(type, key: key)
+        end
+
+        def geolocator
+          reuse_service(:geolocator, "ruflet_rails_geolocator")
+        end
+
+        def semantics
+          reuse_service(:semantics_service, "ruflet_rails_semantics")
+        end
+
+        def run_audio_recorder(action, spec)
+          recorder = reuse_service(:audio_recorder, "ruflet_rails_audio_recorder")
+          callback = report("Audio recorder #{action.tr('-', ' ')}", show_result: true)
+          case action
+          when "start"
+            start_audio_recording(recorder, spec)
+          when "stop"
+            stop_audio_recording(recorder, spec)
+          when "supported-encoder"
+            recorder.is_supported_encoder(spec["encoder"], on_result: callback)
+          else
+            method = "#{action.tr('-', '_')}_recording"
+            method = action.tr("-", "_") if recorder.respond_to?(action.tr("-", "_"))
+            raise ArgumentError, "unknown recorder action #{action.inspect}" unless recorder.respond_to?(method)
+
+            recorder.public_send(method, on_result: callback)
+          end
+        end
+
+        # Recording needs a writable file path *on the device*, and the mic
+        # permission has to be granted first. Studio establishes the same
+        # sequence; Rails asks PermissionHandler explicitly because the record
+        # plugin's `has_permission` preflight can remain pending on an iOS
+        # simulator before the system prompt has ever been shown.
+        def start_audio_recording(recorder, spec)
+          target = spec["result-target"]
+          configuration = spec["configuration"] || { "encoder" => "wav" }
+          explicit = (spec["output-path"] || spec["path"]).to_s
+
+          begin_recording = lambda do |file|
+            start_native_recording = lambda do
+              recorder.start_recording(
+                output_path: file, configuration: configuration, upload: spec["upload"],
+                timeout: interactive_timeout(spec),
+                on_result: lambda do |*rec|
+                  if service_error?(rec[1])
+                    next show_service_result("Start error: #{rec[1]}",
+                                             title: "Audio recorder failed", target: target)
+                  end
+                  unless rec[0]
+                    next show_service_result("The recorder could not start.",
+                                             title: "Audio recorder failed", target: target)
+                  end
+
+                  set_audio_recording_state(spec, recording: true)
+                  show_service_result("Recording… Speak now.", title: "Audio recorder", target: target)
+                end
+              )
+            end
+
+            if @recording_microphone_permission_granted
+              start_native_recording.call
+              next
+            end
+
+            permissions = reuse_service(:permission_handler, "ruflet_rails_permissions")
+            permissions.request("microphone", timeout: interactive_timeout(spec), on_result: lambda do |*out|
+              permission_status, perm_error = out
+              if service_error?(perm_error)
+                next show_service_result("Recorder permission error: #{perm_error}",
+                                         title: "Audio recorder failed", target: target)
+              end
+              unless microphone_permission_granted?(permission_status)
+                next show_service_result("Microphone permission was not granted.",
+                                         title: "Audio recorder", target: target)
+              end
+
+              @recording_microphone_permission_granted = true
+              start_native_recording.call
+            end)
+          end
+
+          release_recording_playback do
+            next begin_recording.call(explicit) unless explicit.empty?
+
+            show_service_result("Preparing recording…", title: "Audio recorder", target: target)
+            if @recording_documents_directory
+              file_name = spec["file-name"].to_s
+              file_name = next_recording_file_name if file_name.empty?
+              next begin_recording.call("#{@recording_documents_directory}/#{file_name}")
+            end
+
+            @page.get_application_documents_directory(on_result: lambda do |dir, dir_error|
+              if service_error?(dir_error) || dir.to_s.empty?
+                next show_service_result(
+                  "Recording path error: #{dir_error || 'documents directory unavailable'}",
+                  title: "Audio recorder failed", target: target
+                )
+              end
+
+              @recording_documents_directory = dir.to_s.sub(%r{/+\z}, "")
+              requested_name = spec["file-name"].to_s
+              file_name = requested_name.empty? ? next_recording_file_name : requested_name
+              file = "#{@recording_documents_directory}/#{file_name}"
+              begin_recording.call(file)
+            end)
+          end
+        end
+
+        def next_recording_file_name
+          @recording_sequence = @recording_sequence.to_i + 1
+          "ruflet_recording_#{@recording_sequence}.wav"
+        end
+
+        def release_recording_playback(&after_release)
+          @recording_playback_generation = @recording_playback_generation.to_i + 1
+          previous = @recording_playback
+          @recording_playback = nil
+          return after_release.call unless previous
+
+          # A completed native player does not consistently answer a `release`
+          # invocation. Removing the service disposes the player and must not
+          # block the next recording session on an optional callback.
+          @page.remove_service(previous)
+          after_release.call
+        end
+
+        def microphone_permission_granted?(status)
+          status == true || status.to_s == "granted"
+        end
+
+        def stop_audio_recording(recorder, spec)
+          target = spec["result-target"]
+          recorder.stop_recording(on_result: lambda do |path, error|
+            set_audio_recording_state(spec, recording: false)
+            if service_error?(error)
+              next show_service_result("Stop error: #{error}",
+                                       title: "Audio recorder failed", target: target)
+            end
+            if path.to_s.empty?
+              next show_service_result("Recording stopped, but no audio file was returned.",
+                                       title: "Audio recorder failed", target: target)
+            end
+
+            autoplay_recording(path.to_s, target: target)
+          end)
+        end
+
+        def set_audio_recording_state(spec, recording:)
+          update_control_property(spec["indicator-target"], visible: recording)
+          update_control_property(spec["record-target"], disabled: recording)
+          update_control_property(spec["stop-target"], disabled: !recording)
+        end
+
+        def update_control_property(id, **props)
+          return if id.to_s.empty?
+
+          control = @page.get_control(id.to_s)
+          @page.update(control, **props) if control
+        end
+
+        def autoplay_recording(path, target:)
+          @page.remove_service(@recording_playback) if @recording_playback
+          @recording_playback_generation = @recording_playback_generation.to_i + 1
+          generation = @recording_playback_generation
+          @recording_playback = @page.service(
+            :audio,
+            id: "ruflet_rails_recording_playback",
+            src: path,
+            autoplay: true,
+            release_mode: "stop",
+            on_state_change: lambda do |event|
+              next unless generation == @recording_playback_generation
+
+              data = event.respond_to?(:data) ? event.data : event
+              state = data.is_a?(Hash) ? (data["state"] || data[:state]) : data
+              message = case state.to_s
+                        when "playing" then "Playing your recording…"
+                        when "completed", "stopped" then "Recording saved and playback finished."
+                        end
+              show_service_result(message, target: target) if message
+            end,
+            on_error: lambda do |event|
+              next unless generation == @recording_playback_generation
+
+              data = event.respond_to?(:data) ? event.data : event
+              show_service_result("Playback error: #{format_service_value(data)}",
+                                  title: "Audio playback failed", target: target)
+            end
+          )
+          show_service_result("Saved. Playing your recording…", title: "Audio recorder", target: target)
+        end
+
+        def toggle_sensor(type, action, spec)
+          type = type.tr("-", "_")
+          sensor = @page.service(
+            type,
+            key: "ruflet_rails_#{type}",
+            interval: spec["interval"],
+            cancel_on_error: spec["cancel-on-error"],
+            on_reading: lambda { |event|
+              show_service_result(
+                format_service_value(event_data(event)),
+                title: service_label(type),
+                target: spec["result-target"]
+              )
+            },
+            on_error: lambda { |event|
+              show_service_result(
+                format_service_value(event_data(event)),
+                title: "#{service_label(type)} failed",
+                target: spec["result-target"]
+              )
+            }
+          )
+          enabled = action == "start"
+          @page.update(sensor, enabled: enabled)
+          show_service_result(
+            "#{service_label(type)} #{enabled ? 'started' : 'stopped'}",
+            title: "Sensor",
+            target: spec["result-target"]
+          )
+        end
+
+        def event_data(event)
+          event.respond_to?(:data) ? event.data : event
+        end
+
+        def open_camera(spec)
+          request_token = @service_request_token
+          camera = target_control!(spec, default: "demo-camera")
+          result_target = spec["result-target"]
+          capture_target = spec["capture-target"]
+          preview_target = spec["preview-target"]
+          show_service_result("Checking available cameras…", title: "Camera", target: result_target)
+          @page.invoke(
+            camera,
+            "get_available_cameras",
+            # On a real device this is the call that raises the camera
+            # permission prompt, so it waits on the person, not the hardware.
+            timeout: interactive_timeout(spec),
+            on_result: lambda do |cameras, camera_error|
+              next unless current_service_request?(request_token)
+
+              if service_error?(camera_error)
+                show_service_result(camera_error, title: "Camera failed", target: result_target)
+                next
+              end
+
+              description = Array(cameras).first
+              unless description
+                show_service_result("No camera is available on this device.", title: "Camera",
+                                     target: result_target)
+                next
+              end
+
+              show_service_result("Initializing camera…", title: "Camera", target: result_target)
+              @page.invoke(
+                camera,
+                "initialize",
+                args: {
+                  "description" => description,
+                  "resolution_preset" => spec["resolution-preset"] || "medium",
+                  "enable_audio" => truthy?(spec["enable-audio"]),
+                  "image_format_group" => spec["image-format-group"] || "jpeg"
+                },
+                timeout: [service_timeout(spec), 180].max,
+                on_result: lambda do |_result, init_error|
+                  next unless current_service_request?(request_token)
+
+                  if service_error?(init_error)
+                    show_service_result(init_error, title: "Camera initialization failed",
+                                                    target: result_target)
+                  else
+                    if capture_target && (capture_button = @page.get_control(capture_target))
+                      @page.update(capture_button, disabled: false)
+                    end
+                    if preview_target && (preview = @page.get_control(preview_target))
+                      @page.update(preview, height: 320)
+                    end
+                    show_service_result("Camera initialized and preview is ready.", title: "Camera",
+                                                                                  target: result_target)
+                  end
+                end
+              )
+            end
+          )
+        end
+
+        def capture_camera_picture(spec)
+          request_token = @service_request_token
+          camera = target_control!(spec, default: "demo-camera")
+          result_target = spec["result-target"]
+          show_service_result("Taking picture…", title: "Camera", target: result_target)
+          @page.invoke(
+            camera,
+            "take_picture",
+            timeout: [service_timeout(spec), 45].max,
+            on_result: lambda do |result, error|
+              next unless current_service_request?(request_token)
+
+              if service_error?(error)
+                show_service_result(error, title: "Camera capture failed", target: result_target)
+              else
+                bytes = result.respond_to?(:bytesize) ? result.bytesize : Array(result).length
+                show_service_result("Captured #{bytes} bytes.", title: "Camera", target: result_target)
+              end
+            end
+          )
+        end
+
+        # Invoke a method on an inline extension control. Give the control an
+        # `id` in ERB and target it from a service button:
+        #   <%= audio id: "player", src: "..." %>
+        #   <%= button "Play", service: "control", target: "player", method: "play" %>
+        def invoke_target_control(spec)
+          target = spec["target"].to_s
+          method = spec["method"].to_s.tr("-", "_")
+          raise ArgumentError, "target is required" if target.empty?
+          raise ArgumentError, "method is required" if method.empty?
+
+          control = target_control!(spec)
+
+          args = service_args(spec)
+          if method == "update"
+            @page.update(control, **args.transform_keys(&:to_sym))
+            show_service_result(spec["toast"] || "#{service_label(target)} updated",
+                                title: "Extension", target: spec["result-target"])
+          else
+            @page.invoke(
+              control, method, args: args.empty? ? nil : args,
+              timeout: service_timeout(spec), on_result: report(spec["toast"] || service_label(method), show_result: true)
+            )
+          end
+        end
+
+        def target_control!(spec, default: nil)
+          target = (spec["target"] || default).to_s
+          raise ArgumentError, "target is required" if target.empty?
+
+          control = @page.get_control(target)
+          raise ArgumentError, "control #{target.inspect} was not found" unless control
+
+          control
+        end
+
+        # Open-ended form for services that do not need a convenience alias:
+        #   service="geolocator" method="get_current_position"
+        #   service="secure-storage.get_all"
+        # Any non-metadata attributes (or an `args` JSON object) become invoke
+        # arguments. This keeps new Ruflet service methods usable without a
+        # ruflet_rails release for every method addition.
+        def invoke_generic_service(name, spec)
+          service_name, dotted_method = name.split(".", 2)
+          method = (spec["method"] || dotted_method).to_s.tr("-", "_")
+          raise ArgumentError, "unknown service #{name.inspect}" if method.empty?
+
+          invoke_named_service(
+            service_name.tr("-", "_"), method, service_args(spec),
+            spec["toast"] || service_label(method), show_result: true,
+            timeout: service_timeout(spec)
+          )
+        end
+
+        def invoke_named_service(type, method, args, label, show_result: false, timeout: 10)
+          control = @page.service(type)
+          @page.invoke(
+            control, method, args: args.nil? || args.empty? ? nil : args,
+            timeout: timeout, on_result: report(label, show_result: show_result)
+          )
+        end
+
+        def service_args(spec)
+          args = spec["args"].is_a?(Hash) ? spec["args"].dup : {}
+          spec.each do |key, value|
+            next if SERVICE_META_KEYS.include?(key)
+            next if CONTROL_TARGET_ATTRIBUTE.match?(key)
+            next if DECLARED_EVENT_ATTRIBUTE.match?(key)
+            next if value.nil?
+
+            args[key.tr("-", "_")] = value
+          end
+          args
+        end
+
+        def service_timeout(spec)
+          value = spec["timeout"]
+          value.nil? || value.to_s.empty? ? 10 : value.to_f
+        end
+
+        # Anything that puts a system dialog on screen — a permission prompt, a
+        # file picker, a save sheet — waits on a person, not on the device, so
+        # the 10s default expires while they are still reading it.
+        #
+        # But a long ceiling only helps the case where an answer is coming. If
+        # the plugin is missing or never replies, every extra second is dead
+        # time the user spends staring at a screen that will fail anyway. 30s
+        # covers answering a dialog without turning a broken call into a
+        # half-minute hang; markup can raise it with `timeout=` where a flow
+        # genuinely needs longer.
+        INTERACTIVE_TIMEOUT = 30
+
+        def interactive_timeout(spec)
+          declared = spec["timeout"]
+          return declared.to_f unless declared.nil? || declared.to_s.empty?
+
+          INTERACTIVE_TIMEOUT
+        end
+
+        # HTML attributes are text, but the client's file APIs want bytes.
+        # Msgpack sends a binary-encoded String as `bin`, which arrives as the
+        # Uint8List those APIs declare; a UTF-8 String arrives as a Dart String
+        # and fails their cast.
+        def binary_bytes(value)
+          return nil if value.nil?
+          return value if value.respond_to?(:encoding) && value.encoding == Encoding::BINARY
+
+          value.to_s.dup.force_encoding(Encoding::BINARY)
+        end
+
+        def truthy?(value)
+          value == true || %w[1 true yes on].include?(value.to_s.downcase)
+        end
+
+        def array_value(value)
+          return value if value.is_a?(Array)
+          return [] if value.nil? || value.to_s.empty?
+
+          value.to_s.split(",").map(&:strip).reject(&:empty?)
+        end
+
+        def service_label(value)
+          value.to_s.tr("_.-", "   ").split.map(&:capitalize).join(" ")
+        end
+
+        def run_haptic(style)
+          case style.to_s.downcase
+          when "heavy" then @page.heavy_impact
+          when "medium" then @page.medium_impact
+          when "light" then @page.light_impact
+          when "vibrate" then @page.vibrate
+          else @page.selection_click
+          end
+        end
+
+        def toggle_flashlight
+          @flashlight_on = !@flashlight_on
+          label = @flashlight_on ? "Torch on" : "Torch off"
+          if @flashlight_on
+            @page.flashlight.on(on_result: report(label))
+          else
+            @page.flashlight.off(on_result: report(label))
+          end
+        end
+
+        def toggle_wakelock
+          @wakelock_on = !@wakelock_on
+          label = @wakelock_on ? "Staying awake" : "Sleep allowed"
+          if @wakelock_on
+            @page.wakelock.enable(on_result: report(label))
+          else
+            @page.wakelock.disable(on_result: report(label))
+          end
+        end
+
+        # Chained battery read: level, then charging state, reported together.
+        def read_battery
+          request_token = @service_request_token
+          result_target = @service_result_target
+          @page.get_battery_level(on_result: lambda do |*level_out|
+            next unless current_service_request?(request_token)
+
+            level, level_error = level_out
+            next show_service_result(level_error, title: "Battery failed", target: result_target) if service_error?(level_error)
+
+            @page.get_battery_state(on_result: lambda do |*state_out|
+              next unless current_service_request?(request_token)
+
+              state, state_error = state_out
+              next show_service_result(state_error, title: "Battery failed", target: result_target) if service_error?(state_error)
+
+              @page.is_in_battery_save_mode(on_result: lambda do |*save_out|
+                next unless current_service_request?(request_token)
+
+                save_mode, save_error = save_out
+                next show_service_result(save_error, title: "Battery failed", target: result_target) if service_error?(save_error)
+
+                level_label = level.nil? ? "Unknown" : "#{level}%"
+                state_label = state.to_s.empty? ? "unknown" : state.to_s.upcase
+                saver_label = save_mode ? "ON" : "OFF"
+                show_service_result(
+                  "Battery level: #{level_label}\nBattery state: #{state_label}\nBattery saver: #{saver_label}",
+                  title: "Battery", target: result_target
+                )
+              end)
+            end)
+          end)
+        end
+
+        def secure_storage
+          reuse_service(:secure_storage, "ruflet_rails_secure_storage")
+        end
+
+        def permissions
+          reuse_service(:permission_handler, "ruflet_rails_permissions")
+        end
+
+        # Build an `on_result` callback that reports the outcome in a native
+        # dialog. Native results arrive as `(value, error)`; a variadic lambda
+        # copes with methods that pass only a value.
+        def report(label, show_result: false)
+          request_token = @service_request_token
+          result_target = @service_result_target
+          lambda do |*out|
+            next unless current_service_request?(request_token)
+
+            value, error = out
+            if service_error?(error)
+              show_service_result(error, title: "#{label} failed", target: result_target)
+            elsif show_result
+              show_service_result(format_service_value(value), title: label, target: result_target)
+            else
+              show_service_result("Completed successfully.", title: label, target: result_target)
+            end
+          end
+        end
+
+        def service_error?(error)
+          !error.nil? && !error.to_s.empty?
+        end
+
+        def format_service_value(value)
+          value = value.data if value.respond_to?(:data)
+          case value
+          when nil then "(none)"
+          when Hash then value.map { |k, v| "#{k}: #{v}" }.join(", ")
+          when Array then value.map(&:to_s).join(", ")
+          else value.to_s.empty? ? "(empty)" : value.to_s
+          end
+        end
+
+        def clamp_unit(value, default)
+          return default if value.nil? || value.to_s.strip.empty?
+
+          value.to_f.clamp(0.0, 1.0)
+        end
+
+        def show_service_result(message, title: "Service result", target: nil)
+          message = message.to_s
+          return if message.empty?
+
+          # A targeted result updates its status control in place — the Studio
+          # model. Crucially, when a target was requested but the control is
+          # gone (the user navigated away before this async result arrived), we
+          # drop it silently. Falling back to the dialog here is exactly what
+          # makes a stray "…failed/expired" alert pop up on an unrelated screen.
+          if target
+            control = @page.get_control(target.to_s)
+            @page.update(control, value: message) if control
+            return
+          end
+
+          ensure_service_dialog
+          if @service_dialog.wire_id
+            @page.update(@service_dialog_title, value: title.to_s)
+            @page.update(@service_dialog_content, value: message)
+            # Ruflet Studio mounts one dialog and toggles its open property.
+            # Keeping the same control prevents delayed responses from stacking.
+            @page.update(@service_dialog, open: true)
+          else
+            @service_dialog_title.props["value"] = title.to_s
+            @service_dialog_content.props["value"] = message
+            @page.show_dialog(@service_dialog)
+          end
+        rescue StandardError
+          nil
+        end
+
+        def close_service_dialog
+          return unless @service_dialog
+
+          @service_request_token += 1
+          @page.update(@service_dialog, open: false)
+        rescue StandardError
+          nil
+        end
+
+        def ensure_service_dialog
+          return @service_dialog if @service_dialog
+
+          @service_dialog_title = text("")
+          @service_dialog_content = text("", selectable: true)
+          @service_dialog = alert_dialog(
+            adaptive: true,
+            modal: true,
+            scrollable: true,
+            open: false,
+            title: @service_dialog_title,
+            content: @service_dialog_content,
+            actions: [
+              text_button(
+                content: text("Close"),
+                on_click: ->(_event) { close_service_dialog }
+              )
+            ],
+            on_dismiss: ->(_event) { close_service_dialog }
+          )
+        end
+
+        def current_service_request?(token)
+          token == @service_request_token
+        end
+
+        # In-place re-render (an action or form submit on the current screen).
+        # Only the parts that actually changed are patched: re-sending an
+        # identical app bar / nav / FAB makes the client rebuild that widget
+        # and flicker, so we diff each against the last render first.
+        def rerender(screen, response)
+          # Re-rendering a screen means parsing its markup and rebuilding the
+          # whole control tree, which costs more than the ERB render that
+          # produced it. When an action leaves the screen byte-identical —
+          # a tap that changed nothing the screen shows — none of that work can
+          # change anything, and neither can the diff it feeds.
+          markup = response.body.to_s
+          return if screen.view&.wire_id && screen.markup && screen.markup == markup
+
+          screen.markup = markup
+          result = render_result(screen, response)
+          mount_services(result)
+          unless screen.view&.wire_id
+            screen.view = build_view(screen, result)
+            remember_chrome(screen, result)
+            flush
+            return
+          end
+
+          new_body = body_for(result)
+          patch = {}
+          appbar = appbar_for(screen, result)
+          patch[:appbar] = appbar if chrome_changed?(screen, :appbar_sig, appbar)
+          patch[:floating_action_button] = result.fab if chrome_changed?(screen, :fab_sig, result.fab)
+          patch[:navigation_bar] = result.bottom_nav if chrome_changed?(screen, :nav_sig, result.bottom_nav)
+
+          # Most re-renders change a value, not a shape: a counter ticks, a
+          # status line fills in, a list item flips. Replacing the whole body
+          # would re-send every control on the screen to move one string, and
+          # would make the client rebuild the subtree (losing scroll position
+          # with it). When the new tree has the same shape as the mounted one,
+          # send only the props that actually differ.
+          updates = ControlDiff.new(screen.body, new_body).updates if screen.body
+          if updates
+            @page.update(screen.view, **patch) unless patch.empty?
+            updates.each { |control, props| @page.update(control, **props) }
+          else
+            screen.body = new_body
+            @page.update(screen.view, controls: [new_body], **patch)
+          end
+        end
+
+        # Record the current chrome signatures so the next in-place re-render
+        # can tell what changed.
+        def remember_chrome(screen, result)
+          screen.appbar_sig = chrome_sig(appbar_for(screen, result))
+          screen.fab_sig = chrome_sig(result.fab)
+          screen.nav_sig = chrome_sig(result.bottom_nav)
+        end
+
+        def chrome_changed?(screen, field, control)
+          sig = chrome_sig(control)
+          return false if screen[field] == sig
+
+          screen[field] = sig
+          true
+        end
+
+        def chrome_sig(control)
+          control ? JSON.generate(control.to_patch) : nil
+        rescue StandardError
+          control.object_id.to_s
+        end
+
+        def render_result(screen, response)
+          screen.url = response.url.to_s unless response.url.to_s.empty?
+          screen.fields = {}
+          body = response.body.to_s
+          # Strings sliced from a binary body would go over the wire as
+          # msgpack bin (byte arrays on the client); make sure we parse UTF-8.
+          body = body.dup.force_encoding(Encoding::UTF_8) if body.encoding == Encoding::ASCII_8BIT
+          result = transform(screen, body)
+          screen.title = result.title
+          if result.controls.empty?
+            result.controls = [container(content: text("Empty screen"), alignment: { x: 0, y: 0 }, expand: true)]
+          end
+          result
+        end
+
+        def transform(screen, body)
+          transformer = Transformer.new(handlers: ScreenHandlers.new(self, screen),
+                                        asset_base_url: asset_base_url)
+          transformer.transform(body)
+        rescue StandardError => e
+          transformer.transform(error_markup(screen.url, e))
+        end
+
+        # Media is the one thing the client fetches for itself, so it is the one
+        # thing that still needs a host. Resolved per render, because the answer
+        # depends on the connection this session is running on.
+        def asset_base_url
+          return nil unless defined?(::Ruflet::Rails.backend_url)
+
+          ::Ruflet::Rails.backend_url
+        rescue StandardError
+          nil
+        end
+
+
+
+        def build_view(screen, result)
+          args = { route: screen.route }
+          appbar = appbar_for(screen, result)
+          args[:appbar] = appbar if appbar
+          args[:floating_action_button] = result.fab if result.fab
+          args[:navigation_bar] = result.bottom_nav if result.bottom_nav
+          # Kept so the next in-place re-render can diff against what is
+          # actually mounted instead of replacing it.
+          screen.body = body_for(result)
+          view([screen.body], **args)
+        end
+
+        # Screens scroll by default, like a web page. But a screen whose
+        # top-level control expands (flex-1 / h-full, e.g. a vertically
+        # centered layout) needs the fixed viewport instead: an expanding
+        # child inside a scrollable has unbounded height and collapses to an
+        # empty body.
+        def body_for(result)
+          expanding = result.controls.any? { |control| control.respond_to?(:props) && control.props["expand"] }
+          props = { expand: true, spacing: 0 }
+          props[:scroll] = "auto" unless expanding
+          column(result.controls, **props)
+        end
+
+        # Declared `<appbar>` wins. A pushed screen without one still gets a
+        # titled AppBar so the native back button exists; the root only gets
+        # one when the app asked for a title.
+        def appbar_for(screen, result)
+          return result.appbar if result.appbar
+
+          title = screen.root ? (@title || "") : (result.title || @title || title_from_url(screen.url))
+          return nil if title.to_s.strip.empty?
+
+          appbar(title: text(title.to_s))
+        end
+
+        def flush
+          @page.views = @screens.map(&:view)
+          @page.update
+        end
+
+        # --- HTTP -----------------------------------------------------------------
+
+        def request(url, params: nil)
+          @fetcher.fetch(url, params: params)
+        rescue StandardError => e
+          TemplateSource::Response.new(body: error_markup(url, e), url: url)
+        end
+
+        def error_markup(url, error)
+          <<~HTML
+            <column class="p-6 gap-2">
+              <h3>Could not load screen</h3>
+              <text class="text-slate-500">#{url}</text>
+              <text class="text-red-600">#{error.message}</text>
+            </column>
+          HTML
+        end
+
+        # Screens may be declared as paths ("/native") or as full URLs. A path
+        # stays a path: the fetcher supplies the host from the live WebSocket
+        # connection, so nothing here has to name one. Relative links still
+        # resolve against the current screen either way — done by borrowing a
+        # placeholder host, since URI.join needs an absolute base, and then
+        # dropping it again.
+        PATH_RESOLUTION_BASE = "http://ruflet.invalid"
+
+        def absolute_url(url)
+          url = url.to_s
+          return "" if url.empty?
+          return url if URI.parse(url).absolute?
+
+          base = current_url
+          return URI.join(base, url).to_s if URI.parse(base).absolute?
+
+          resolved = URI.join("#{PATH_RESOLUTION_BASE}#{base}", url)
+          resolved.query ? "#{resolved.path}?#{resolved.query}" : resolved.path
+        rescue URI::InvalidURIError, URI::BadURIError
+          url
+        end
+
+        def current_url
+          @screens.last&.url || @start_url
+        end
+
+        def title_from_url(url)
+          path = URI.parse(url.to_s).path.to_s
+          label = path.split("/").reject(&:empty?).last.to_s
+          label = "Screen" if label.empty?
+          label.tr("_-", " ").split.map(&:capitalize).join(" ")
+        rescue URI::InvalidURIError
+          "Screen"
+        end
+      end
+    end
+  end
+end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/parser.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/parser.rb
new file mode 100644
index 00000000..8cdddf35
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/parser.rb
@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Ruflet
+  module Rails
+    module HtmlDsl
+      # Minimal, dependency-free HTML parser for the Ruflet HTML DSL.
+      #
+      # ERB output is developer-authored markup, so this parser expects
+      # reasonably well-formed documents: tags are balanced (void elements
+      # aside) and attribute values are quoted or simple tokens. It exists so
+      # the DSL works everywhere ruflet_rails runs, including runtimes where
+      # nokogiri is unavailable.
+      class Parser
+        VOID_ELEMENTS = %w[
+          area base br col embed hr img input link meta param source track wbr
+        ].freeze
+        RAW_TEXT_ELEMENTS = %w[script style].freeze
+
+        Element = Struct.new(:tag, :attrs, :children) do
+          def element? = true
+          def text? = false
+
+          # Concatenated text of all descendant text nodes.
+          def text
+            children.map { |child| child.text? ? child.value : child.text }.join.strip
+          end
+
+          def [](name)
+            attrs[name.to_s]
+          end
+
+          def key?(name)
+            attrs.key?(name.to_s)
+          end
+
+          def elements
+            children.select(&:element?)
+          end
+        end
+
+        TextNode = Struct.new(:value) do
+          def element? = false
+          def text? = true
+        end
+
+        def self.parse(html)
+          new(html.to_s).parse
+        end
+
+        def initialize(html)
+          @html = html
+          @pos = 0
+          @length = html.length
+        end
+
+        # Returns the list of top-level nodes.
+        def parse
+          root = Element.new("#root", {}, [])
+          stack = [root]
+
+          until eos?
+            text = scan_text
+            stack.last.children << TextNode.new(decode_entities(text)) unless text.strip.empty?
+            break if eos?
+
+            if peek_string?("<!--")
+              skip_past("-->")
+            elsif peek_string?("<!") || peek_string?("<?")
+              skip_past(">")
+            elsif peek_string?("</")
+              tag = scan_closing_tag
+              close_element(stack, tag) if tag
+            else
+              element, self_closing = scan_opening_tag
+              next unless element
+
+              if RAW_TEXT_ELEMENTS.include?(element.tag)
+                skip_raw_text(element.tag)
+                next
+              end
+
+              stack.last.children << element
+              stack.push(element) unless self_closing || VOID_ELEMENTS.include?(element.tag)
+            end
+          end
+
+          root.children
+        end
+
+        private
+
+        def eos?
+          @pos >= @length
+        end
+
+        def peek_string?(str)
+          @html[@pos, str.length] == str
+        end
+
+        def scan_text
+          start = @pos
+          next_tag = @html.index("<", @pos)
+          @pos = next_tag || @length
+          @html[start...@pos].to_s
+        end
+
+        def skip_past(marker)
+          index = @html.index(marker, @pos)
+          @pos = index ? index + marker.length : @length
+        end
+
+        def scan_closing_tag
+          match = @html.match(/\G<\/\s*([a-zA-Z][a-zA-Z0-9:_-]*)\s*>/, @pos)
+          unless match
+            skip_past(">")
+            return nil
+          end
+
+          @pos += match[0].length
+          match[1].downcase
+        end
+
+        def scan_opening_tag
+          match = @html.match(/\G<\s*([a-zA-Z][a-zA-Z0-9:_-]*)/, @pos)
+          unless match
+            # Stray "<" that is not a tag: emit it as text.
+            @pos += 1
+            return [nil, false]
+          end
+
+          @pos += match[0].length
+          tag = match[1].downcase
+          attrs = scan_attributes
+          self_closing = false
+
+          if peek_string?("/>")
+            self_closing = true
+            @pos += 2
+          elsif peek_string?(">")
+            @pos += 1
+          else
+            skip_past(">")
+          end
+
+          [Element.new(tag, attrs, []), self_closing]
+        end
+
+        ATTRIBUTE_PATTERN = /\G\s*([^\s=\/>"']+)(?:\s*=\s*("([^"]*)"|'([^']*)'|[^\s>]+))?/
+
+        def scan_attributes
+          attrs = {}
+          loop do
+            skip_whitespace
+            break if eos? || peek_string?(">") || peek_string?("/>")
+
+            match = @html.match(ATTRIBUTE_PATTERN, @pos)
+            break unless match
+
+            @pos += match[0].length
+            name = match[1].downcase
+            value = match[3] || match[4] || (match[2] ? match[2] : "")
+            attrs[name] = decode_entities(value)
+          end
+          attrs
+        end
+
+        def skip_whitespace
+          @pos += 1 while !eos? && @html[@pos] =~ /\s/
+        end
+
+        def skip_raw_text(tag)
+          closing = "</#{tag}"
+          index = @html.downcase.index(closing, @pos)
+          if index
+            @pos = index
+            skip_past(">")
+          else
+            @pos = @length
+          end
+        end
+
+        # Close the innermost open element with this tag; tolerate stray
+        # closers and mildly mis-nested markup by unwinding to the match.
+        def close_element(stack, tag)
+          index = stack.rindex { |element| element.tag == tag }
+          return unless index&.positive?
+
+          stack.pop while stack.length > index
+        end
+
+        ENTITIES = {
+          "&amp;" => "&", "&lt;" => "<", "&gt;" => ">",
+          "&quot;" => '"', "&#39;" => "'", "&apos;" => "'", "&nbsp;" => " "
+        }.freeze
+
+        def decode_entities(text)
+          return text unless text.include?("&")
+
+          decoded = text
+          ENTITIES.each { |entity, char| decoded = decoded.gsub(entity, char) }
+          decoded.gsub(/&#(\d+);/) { Regexp.last_match(1).to_i.chr(Encoding::UTF_8) }
+        rescue RangeError
+          decoded
+        end
+      end
+    end
+  end
+end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/styles.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/styles.rb
new file mode 100644
index 00000000..e762aad2
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/styles.rb
@@ -0,0 +1,433 @@
+# frozen_string_literal: true
+
+module Ruflet
+  module Rails
+    module HtmlDsl
+      # Maps a Tailwind-flavored `class` attribute onto Ruflet control props.
+      #
+      # Returns a flat hash of prop-named keys (`:size`, `:padding`, `:bgcolor`,
+      # `:border`, `:gradient`, `:rotate`, …). The transformer distributes these
+      # onto the control itself (text props), onto a wrapping container (box
+      # props), or onto any control whose schema accepts them (schema_style_props).
+      module Styles
+        SPACING_UNIT = 4
+
+        TEXT_SIZES = {
+          "xs" => 12, "sm" => 14, "base" => 16, "lg" => 18, "xl" => 20,
+          "2xl" => 24, "3xl" => 30, "4xl" => 36, "5xl" => 48, "6xl" => 60,
+          "7xl" => 72, "8xl" => 96, "9xl" => 128
+        }.freeze
+
+        FONT_WEIGHTS = {
+          "thin" => "w100", "extralight" => "w200", "light" => "w300",
+          "normal" => "normal", "medium" => "w500", "semibold" => "w600",
+          "bold" => "bold", "extrabold" => "w800", "black" => "w900"
+        }.freeze
+
+        FONT_FAMILIES = { "mono" => "monospace", "serif" => "serif", "sans" => "sans-serif" }.freeze
+
+        LETTER_SPACING = {
+          "tighter" => -0.8, "tight" => -0.4, "normal" => 0.0,
+          "wide" => 0.4, "wider" => 0.8, "widest" => 1.6
+        }.freeze
+
+        LINE_HEIGHT = {
+          "none" => 1.0, "tight" => 1.25, "snug" => 1.375,
+          "normal" => 1.5, "relaxed" => 1.625, "loose" => 2.0
+        }.freeze
+
+        # underline=1, overline=2, line-through=4 (bitmask; may combine).
+        DECORATIONS = { "underline" => 1, "overline" => 2, "line-through" => 4 }.freeze
+
+        CURVES = {
+          "linear" => "linear", "in" => "easeIn", "out" => "easeOut", "in-out" => "easeInOut"
+        }.freeze
+
+        RADII = {
+          nil => 4, "none" => 0, "sm" => 2, "md" => 6, "lg" => 8,
+          "xl" => 12, "2xl" => 16, "3xl" => 24, "full" => 9999
+        }.freeze
+
+        MAIN_AXIS = {
+          "start" => "start", "center" => "center", "end" => "end",
+          "between" => "spaceBetween", "around" => "spaceAround", "evenly" => "spaceEvenly"
+        }.freeze
+
+        CROSS_AXIS = {
+          "start" => "start", "center" => "center", "end" => "end",
+          "stretch" => "stretch", "baseline" => "baseline"
+        }.freeze
+
+        SHADOWS = {
+          "sm" => { "blur_radius" => 3, "color" => "#26000000", "offset" => { "x" => 0, "y" => 1 } },
+          nil => { "blur_radius" => 6, "color" => "#26000000", "offset" => { "x" => 0, "y" => 2 } },
+          "md" => { "blur_radius" => 10, "color" => "#26000000", "offset" => { "x" => 0, "y" => 4 } },
+          "lg" => { "blur_radius" => 18, "color" => "#33000000", "offset" => { "x" => 0, "y" => 8 } },
+          "xl" => { "blur_radius" => 28, "color" => "#33000000", "offset" => { "x" => 0, "y" => 12 } },
+          "2xl" => { "blur_radius" => 40, "color" => "#40000000", "offset" => { "x" => 0, "y" => 20 } },
+          "none" => nil
+        }.freeze
+
+        BLURS = { "none" => 0, "sm" => 2, nil => 4, "md" => 8, "lg" => 16, "xl" => 24, "2xl" => 40, "3xl" => 64 }.freeze
+
+        # Fixed rotation angles (degrees) Tailwind ships, → radians.
+        ROTATIONS = %w[0 1 2 3 6 12 45 90 180].freeze
+
+        SCALES = {
+          "0" => 0.0, "50" => 0.5, "75" => 0.75, "90" => 0.9, "95" => 0.95,
+          "100" => 1.0, "105" => 1.05, "110" => 1.1, "125" => 1.25, "150" => 1.5
+        }.freeze
+
+        OBJECT_FITS = {
+          "contain" => "contain", "cover" => "cover", "fill" => "fill",
+          "none" => "none", "scale-down" => "scaleDown"
+        }.freeze
+
+        # Tailwind gradient direction → begin/end alignment ({x,y} in -1..1).
+        GRADIENT_DIRS = {
+          "r" => [{ "x" => -1, "y" => 0 }, { "x" => 1, "y" => 0 }],
+          "l" => [{ "x" => 1, "y" => 0 }, { "x" => -1, "y" => 0 }],
+          "t" => [{ "x" => 0, "y" => 1 }, { "x" => 0, "y" => -1 }],
+          "b" => [{ "x" => 0, "y" => -1 }, { "x" => 0, "y" => 1 }],
+          "tr" => [{ "x" => -1, "y" => 1 }, { "x" => 1, "y" => -1 }],
+          "tl" => [{ "x" => 1, "y" => 1 }, { "x" => -1, "y" => -1 }],
+          "br" => [{ "x" => -1, "y" => -1 }, { "x" => 1, "y" => 1 }],
+          "bl" => [{ "x" => 1, "y" => -1 }, { "x" => -1, "y" => 1 }]
+        }.freeze
+
+        # Standard Tailwind palette (v3), most-used families.
+        PALETTE = {
+          "slate" => %w[#f8fafc #f1f5f9 #e2e8f0 #cbd5e1 #94a3b8 #64748b #475569 #334155 #1e293b #0f172a],
+          "gray" => %w[#f9fafb #f3f4f6 #e5e7eb #d1d5db #9ca3af #6b7280 #4b5563 #374151 #1f2937 #111827],
+          "zinc" => %w[#fafafa #f4f4f5 #e4e4e7 #d4d4d8 #a1a1aa #71717a #52525b #3f3f46 #27272a #18181b],
+          "neutral" => %w[#fafafa #f5f5f5 #e5e5e5 #d4d4d4 #a3a3a3 #737373 #525252 #404040 #262626 #171717],
+          "stone" => %w[#fafaf9 #f5f5f4 #e7e5e4 #d6d3d1 #a8a29e #78716c #57534e #44403c #292524 #1c1917],
+          "red" => %w[#fef2f2 #fee2e2 #fecaca #fca5a5 #f87171 #ef4444 #dc2626 #b91c1c #991b1b #7f1d1d],
+          "orange" => %w[#fff7ed #ffedd5 #fed7aa #fdba74 #fb923c #f97316 #ea580c #c2410c #9a3412 #7c2d12],
+          "amber" => %w[#fffbeb #fef3c7 #fde68a #fcd34d #fbbf24 #f59e0b #d97706 #b45309 #92400e #78350f],
+          "yellow" => %w[#fefce8 #fef9c3 #fef08a #fde047 #facc15 #eab308 #ca8a04 #a16207 #854d0e #713f12],
+          "lime" => %w[#f7fee7 #ecfccb #d9f99d #bef264 #a3e635 #84cc16 #65a30d #4d7c0f #3f6212 #365314],
+          "green" => %w[#f0fdf4 #dcfce7 #bbf7d0 #86efac #4ade80 #22c55e #16a34a #15803d #166534 #14532d],
+          "emerald" => %w[#ecfdf5 #d1fae5 #a7f3d0 #6ee7b7 #34d399 #10b981 #059669 #047857 #065f46 #064e3b],
+          "teal" => %w[#f0fdfa #ccfbf1 #99f6e4 #5eead4 #2dd4bf #14b8a6 #0d9488 #0f766e #115e59 #134e4a],
+          "cyan" => %w[#ecfeff #cffafe #a5f3fc #67e8f9 #22d3ee #06b6d4 #0891b2 #0e7490 #155e75 #164e63],
+          "sky" => %w[#f0f9ff #e0f2fe #bae6fd #7dd3fc #38bdf8 #0ea5e9 #0284c7 #0369a1 #075985 #0c4a6e],
+          "blue" => %w[#eff6ff #dbeafe #bfdbfe #93c5fd #60a5fa #3b82f6 #2563eb #1d4ed8 #1e40af #1e3a8a],
+          "indigo" => %w[#eef2ff #e0e7ff #c7d2fe #a5b4fc #818cf8 #6366f1 #4f46e5 #4338ca #3730a3 #312e81],
+          "violet" => %w[#f5f3ff #ede9fe #ddd6fe #c4b5fd #a78bfa #8b5cf6 #7c3aed #6d28d9 #5b21b6 #4c1d95],
+          "purple" => %w[#faf5ff #f3e8ff #e9d5ff #d8b4fe #c084fc #a855f7 #9333ea #7e22ce #6b21a8 #581c87],
+          "fuchsia" => %w[#fdf4ff #fae8ff #f5d0fe #f0abfc #e879f9 #d946ef #c026d3 #a21caf #86198f #701a75],
+          "pink" => %w[#fdf2f8 #fce7f3 #fbcfe8 #f9a8d4 #f472b6 #ec4899 #db2777 #be185d #9d174d #831843],
+          "rose" => %w[#fff1f2 #ffe4e6 #fecdd3 #fda4af #fb7185 #f43f5e #e11d48 #be123c #9f1239 #881337]
+        }.freeze
+        SHADES = %w[50 100 200 300 400 500 600 700 800 900].freeze
+
+        NAMED_COLORS = {
+          "white" => "#ffffff", "black" => "#000000", "transparent" => "transparent",
+          # Material theme tokens pass through as Ruflet theme color names.
+          "primary" => "primary", "onprimary" => "onprimary",
+          "primarycontainer" => "primarycontainer", "onprimarycontainer" => "onprimarycontainer",
+          "secondary" => "secondary", "onsecondary" => "onsecondary",
+          "secondarycontainer" => "secondarycontainer", "onsecondarycontainer" => "onsecondarycontainer",
+          "tertiary" => "tertiary", "ontertiary" => "ontertiary",
+          "error" => "error", "onerror" => "onerror",
+          "surface" => "surface", "onsurface" => "onsurface",
+          "surfacevariant" => "surfacevariant", "onsurfacevariant" => "onsurfacevariant",
+          "inversesurface" => "inversesurface", "outline" => "outline"
+        }.freeze
+
+        module_function
+
+        def parse(class_attr)
+          props = {}
+          class_attr.to_s.split(/\s+/).each { |token| apply_token(props, token) }
+          finalize_border(props)
+          finalize_gradient(props)
+          finalize_animate(props)
+          props
+        end
+
+        def color_for(token)
+          return nil if token.nil? || token.empty?
+
+          normalized = token.tr("-", "").downcase
+          return NAMED_COLORS[normalized] if NAMED_COLORS.key?(normalized)
+          return token if token.start_with?("#")
+
+          family, shade = token.split("-", 2)
+          shades = PALETTE[family]
+          return nil unless shades
+
+          index = SHADES.index(shade || "500")
+          index && shades[index]
+        end
+
+        def apply_token(props, token)
+          case token
+          # --- spacing ---------------------------------------------------------
+          when /\A(p|px|py|pt|pr|pb|pl)-(.+)\z/
+            apply_edges(props, :padding, Regexp.last_match(1), Regexp.last_match(2))
+          when /\A-?(m|mx|my|mt|mr|mb|ml)-(.+)\z/
+            apply_edges(props, :margin, Regexp.last_match(1), Regexp.last_match(2), negative: token.start_with?("-"))
+          when /\A(?:gap-y|space-y)-(.+)\z/
+            (value = length(Regexp.last_match(1))) && props[:run_spacing] = value
+          when /\A(?:gap-x|gap|space-x)-(.+)\z/
+            (value = length(Regexp.last_match(1))) && props[:spacing] = value
+          # --- sizing ----------------------------------------------------------
+          when "w-full", "h-full", "w-screen", "h-screen", "min-h-screen", "min-w-full",
+               "flex-1", "grow", "expand", "flex-auto", "size-full"
+            props[:expand] = true
+          when /\Asize-(.+)\z/
+            (value = length(Regexp.last_match(1))) && props.merge!(width: value, height: value)
+          when /\A(?:min-|max-)?w-(.+)\z/
+            (value = length(Regexp.last_match(1))) && props[:width] = value
+          when /\A(?:min-|max-)?h-(.+)\z/
+            (value = length(Regexp.last_match(1))) && props[:height] = value
+          when "aspect-square" then props[:aspect_ratio] = 1.0
+          when "aspect-video" then props[:aspect_ratio] = 16.0 / 9.0
+          when /\Aaspect-\[(\d+)\/(\d+)\]\z/
+            props[:aspect_ratio] = Regexp.last_match(1).to_f / Regexp.last_match(2).to_f
+          # --- flex alignment --------------------------------------------------
+          when /\Aitems-(.+)\z/
+            (value = CROSS_AXIS[Regexp.last_match(1)]) && props[:cross_alignment] = value
+          when /\Ajustify-(.+)\z/
+            (value = MAIN_AXIS[Regexp.last_match(1)]) && props[:main_alignment] = value
+          # --- positioning (stack children) ------------------------------------
+          when /\A-?(top|left|right|bottom)-(.+)\z/
+            apply_position(props, Regexp.last_match(1), Regexp.last_match(2), negative: token.start_with?("-"))
+          when /\Ainset-x-(.+)\z/
+            %w[left right].each { |edge| apply_position(props, edge, Regexp.last_match(1)) }
+          when /\Ainset-y-(.+)\z/
+            %w[top bottom].each { |edge| apply_position(props, edge, Regexp.last_match(1)) }
+          when /\Ainset-(.+)\z/
+            %w[top left right bottom].each { |edge| apply_position(props, edge, Regexp.last_match(1)) }
+          # --- container content alignment -------------------------------------
+          when "place-items-center", "place-content-center", "place-center", "grid-center"
+            props[:alignment] = { "x" => 0, "y" => 0 }
+          # --- typography ------------------------------------------------------
+          when "text-center", "text-left", "text-right", "text-justify"
+            props[:text_align] = token.split("-").last
+          when "text-ellipsis" then props[:overflow] = "ellipsis"
+          when "text-clip" then props[:overflow] = "clip"
+          when /\Atext-(xs|sm|base|lg|[2-9]?xl)\z/
+            props[:size] = TEXT_SIZES[Regexp.last_match(1)]
+          when /\Atext-\[(\d+)(?:px)?\]\z/
+            props[:size] = Regexp.last_match(1).to_i
+          when /\Atext-(.+)\z/
+            (value = color_for(Regexp.last_match(1))) && props[:color] = value
+          when /\Afont-(mono|serif|sans)\z/
+            props[:font_family] = FONT_FAMILIES[Regexp.last_match(1)]
+          when /\Afont-(.+)\z/
+            (value = FONT_WEIGHTS[Regexp.last_match(1)]) && props[:weight] = value
+          when "italic" then props[:italic] = true
+          when "not-italic" then props[:italic] = false
+          when /\Atracking-(tighter|tight|normal|wide|wider|widest)\z/
+            props[:letter_spacing] = LETTER_SPACING[Regexp.last_match(1)]
+          when /\Aleading-(none|tight|snug|normal|relaxed|loose)\z/
+            props[:line_height] = LINE_HEIGHT[Regexp.last_match(1)]
+          when "underline", "overline", "line-through"
+            props[:decoration] = (props[:decoration] || 0) | DECORATIONS[token]
+          when "no-underline" then props[:decoration] = 0
+          when "uppercase", "lowercase", "capitalize" then props[:text_transform] = token
+          when "normal-case" then props[:text_transform] = nil
+          when "truncate" then props.merge!(max_lines: 1, overflow: "ellipsis")
+          when "line-clamp-none" then props[:max_lines] = nil
+          when /\Aline-clamp-(\d+)\z/
+            props.merge!(max_lines: Regexp.last_match(1).to_i, overflow: "ellipsis")
+          when "whitespace-nowrap", "text-nowrap" then props[:no_wrap] = true
+          when "whitespace-normal", "text-wrap" then props[:no_wrap] = false
+          when "select-none" then props[:selectable] = false
+          when "select-text", "select-all" then props[:selectable] = true
+          # --- background / gradient ------------------------------------------
+          when /\Abg-gradient-to-(tr|tl|br|bl|[trbl])\z/
+            props[:_grad_dir] = Regexp.last_match(1)
+          when /\Afrom-(.+)\z/
+            (value = color_for(Regexp.last_match(1))) && props[:_grad_from] = value
+          when /\Avia-(.+)\z/
+            (value = color_for(Regexp.last_match(1))) && props[:_grad_via] = value
+          when /\Ato-(.+)\z/
+            (value = color_for(Regexp.last_match(1))) && props[:_grad_to] = value
+          when /\Abg-\[(#[0-9a-fA-F]+)\]\z/
+            props[:bgcolor] = Regexp.last_match(1)
+          when /\Abg-(.+)\z/
+            (value = color_for(Regexp.last_match(1))) && props[:bgcolor] = value
+          # --- borders & corners ----------------------------------------------
+          when /\Arounded(-[trbl][trbl]?)?(?:-(.+))?\z/
+            apply_radius(props, Regexp.last_match(1), Regexp.last_match(2))
+          when "border" then set_border(props, width: 1)
+          when /\Aborder-(\d+)\z/ then set_border(props, width: Regexp.last_match(1).to_i)
+          when /\Aborder-(t|r|b|l|x|y)(?:-(\d+))?\z/
+            set_border(props, side: Regexp.last_match(1), width: (Regexp.last_match(2) || 1).to_i)
+          when /\Aborder-(.+)\z/
+            (value = color_for(Regexp.last_match(1))) && set_border(props, color: value)
+          # --- effects ---------------------------------------------------------
+          when /\Ashadow(?:-(sm|md|lg|xl|2xl|none))?\z/
+            props[:shadow] = SHADOWS[Regexp.last_match(1)]
+          when /\Aopacity-(\d+)\z/
+            props[:opacity] = Regexp.last_match(1).to_i / 100.0
+          when /\Ablur(?:-(none|sm|md|lg|xl|2xl|3xl))?\z/
+            props[:blur] = BLURS[Regexp.last_match(1)]
+          when /\Ablur-\[(\d+)(?:px)?\]\z/ then props[:blur] = Regexp.last_match(1).to_i
+          # --- transforms ------------------------------------------------------
+          when /\A(-?)rotate-(\d+)\z/
+            if ROTATIONS.include?(Regexp.last_match(2))
+              deg = Regexp.last_match(2).to_f
+              deg = -deg if Regexp.last_match(1) == "-"
+              props[:rotate] = (deg * Math::PI / 180).round(4)
+            end
+          when /\Arotate-\[(-?\d+)deg\]\z/
+            props[:rotate] = (Regexp.last_match(1).to_f * Math::PI / 180).round(4)
+          when /\Ascale-(\d+)\z/
+            (value = SCALES[Regexp.last_match(1)]) && props[:scale] = value
+          # --- visibility / clipping / image fit -------------------------------
+          when "hidden", "invisible" then props[:visible] = false
+          when "visible" then props[:visible] = true
+          when "overflow-hidden", "overflow-clip" then props[:clip_behavior] = "hardEdge"
+          when "scroll", "overflow-auto", "overflow-y-auto", "overflow-scroll" then props[:scroll] = "auto"
+          when /\Aobject-(contain|cover|fill|none|scale-down)\z/
+            props[:fit] = OBJECT_FITS[Regexp.last_match(1)]
+          when "wrap", "flex-wrap" then props[:wrap] = true
+          # --- transitions / implicit animation --------------------------------
+          when /\Atransition(?:-(all|colors|opacity|transform|shadow))?\z/
+            props[:_anim_on] = true
+          when /\Aduration-(\d+)\z/
+            props[:_anim_duration] = Regexp.last_match(1).to_i
+          when /\Aease-(linear|in-out|in|out)\z/
+            props[:_anim_curve] = CURVES[Regexp.last_match(1)]
+          end
+        end
+
+        def finalize_animate(props)
+          on = props.delete(:_anim_on)
+          duration = props.delete(:_anim_duration)
+          curve = props.delete(:_anim_curve)
+          return unless on || duration || curve
+
+          duration ||= 150
+          props[:animate] = curve ? { "duration" => duration, "curve" => curve } : duration
+        end
+
+        # --- assembly helpers ---------------------------------------------------
+
+        def apply_edges(props, key, prefix, raw, negative: false)
+          value = length(raw)
+          return unless value
+
+          value = -value if negative
+          edges = props[key].is_a?(Hash) ? props[key] : {}
+          edges = uniform_to_edges(props[key]) if props[key].is_a?(Numeric)
+
+          case prefix[-1]
+          when "x" then edges = edges.merge("left" => value, "right" => value)
+          when "y" then edges = edges.merge("top" => value, "bottom" => value)
+          when "t" then edges = edges.merge("top" => value)
+          when "r" then edges = edges.merge("right" => value)
+          when "b" then edges = edges.merge("bottom" => value)
+          when "l" then edges = edges.merge("left" => value)
+          else
+            props[key] = value
+            return
+          end
+          props[key] = edges
+        end
+
+        def apply_position(props, edge, raw, negative: false)
+          value = length(raw)
+          return unless value
+
+          props[edge.to_sym] = negative ? -value : value
+        end
+
+        # rounded / rounded-lg / rounded-t-lg / rounded-tl-xl
+        def apply_radius(props, corner_group, size)
+          radius = RADII.key?(size) ? RADII[size] : length(size)
+          return if radius.nil?
+
+          if corner_group.nil?
+            # Uniform: replace unless per-corner values already exist.
+            props[:border_radius] = props[:border_radius].is_a?(Hash) ? fill_corners(radius) : radius
+            return
+          end
+
+          corners = radius_corners(corner_group.delete("-"))
+          current = props[:border_radius].is_a?(Hash) ? props[:border_radius] : {}
+          corners.each { |c| current[c] = radius }
+          props[:border_radius] = current
+        end
+
+        def radius_corners(group)
+          case group
+          when "t" then %w[top_left top_right]
+          when "b" then %w[bottom_left bottom_right]
+          when "l" then %w[top_left bottom_left]
+          when "r" then %w[top_right bottom_right]
+          when "tl" then %w[top_left]
+          when "tr" then %w[top_right]
+          when "bl" then %w[bottom_left]
+          when "br" then %w[bottom_right]
+          else []
+          end
+        end
+
+        def fill_corners(radius)
+          { "top_left" => radius, "top_right" => radius, "bottom_left" => radius, "bottom_right" => radius }
+        end
+
+        def set_border(props, width: nil, color: nil, side: nil)
+          props[:_border_width] = width if width
+          props[:_border_color] = color if color
+          sides = props[:_border_sides] ||= []
+          sides.concat(border_sides(side)) if side
+          props[:_border_seen] = true
+        end
+
+        def border_sides(side)
+          case side
+          when "x" then %w[left right]
+          when "y" then %w[top bottom]
+          when "t" then %w[top]
+          when "r" then %w[right]
+          when "b" then %w[bottom]
+          when "l" then %w[left]
+          else %w[top right bottom left]
+          end
+        end
+
+        def finalize_border(props)
+          return unless props.delete(:_border_seen)
+
+          width = props.delete(:_border_width)
+          color = props.delete(:_border_color)
+          sides = props.delete(:_border_sides)
+          sides = %w[top right bottom left] if sides.nil? || sides.empty?
+          face = { "width" => width || 1 }
+          face["color"] = color || "#e2e8f0"
+          props[:border] = sides.uniq.each_with_object({}) { |side, out| out[side] = face }
+        end
+
+        def finalize_gradient(props)
+          dir = props.delete(:_grad_dir)
+          colors = [props.delete(:_grad_from), props.delete(:_grad_via), props.delete(:_grad_to)].compact
+          return if colors.length < 2
+
+          from_align, to_align = GRADIENT_DIRS[dir || "b"]
+          props[:gradient] = { "_type" => "linear", "begin" => from_align, "end" => to_align, "colors" => colors }
+        end
+
+        def uniform_to_edges(value)
+          { "left" => value, "top" => value, "right" => value, "bottom" => value }
+        end
+
+        # Tailwind scale (`4` => 16), fractions (`1/2` => 50% is unsupported, skipped),
+        # and arbitrary `[Npx]` values.
+        def length(raw)
+          return nil if raw.nil?
+          return Regexp.last_match(1).to_i if raw =~ /\A\[(\d+)(?:px)?\]\z/
+          return (raw.to_f * SPACING_UNIT).round if raw =~ /\A\d+(\.\d+)?\z/
+
+          nil
+        end
+      end
+    end
+  end
+end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
new file mode 100644
index 00000000..87af6152
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Ruflet
+  module Rails
+    module HtmlDsl
+      # The ERB file as the app.
+      #
+      # A normal Ruflet app is a Ruby file: handlers run in the session, mutate
+      # state, and the page diffs and patches over the WebSocket. This puts an
+      # ERB file in that slot. Templates under app/views describe the screen,
+      # and a tap calls a method on the developer's own controller — directly,
+      # in the session — after which the template re-renders and only the
+      # changed controls are patched.
+      #
+      # There is no request: no routing, no middleware, no Rack env, and so no
+      # "Started POST … Completed 200 OK" per tap. What that costs is the parts
+      # of Rails that only exist because of a request — `session`, `flash`,
+      # `cookies` and CSRF. State lives where a Ruflet app keeps it instead: in
+      # the controller instance, which is held for the life of the session, so
+      # an ordinary `@count` survives from one tap to the next.
+      #
+      class TemplateSource
+        Response = Struct.new(:body, :url, keyword_init: true)
+
+        def initialize
+          @controllers = {}
+          @session = indifferent({})
+          @templates = {}
+          @lookups = {}
+        end
+
+        def fetch(url, params: nil)
+          path = URI.parse(url.to_s).path.to_s
+          screen = NativeScreens.resolve(path)
+          return missing(url, path) unless screen
+
+          controller = controller_for(screen[:controller])
+          assign_params(controller, params, screen[:params])
+          invoke(controller, screen[:action])
+
+          # An action like #counter_increment changes state and then re-renders
+          # counter.html.erb, whose ivars only #counter assigns. Without running
+          # the screen's own action the template redraws from whatever the last
+          # visit left behind — the tap works and the screen never moves.
+          own = template_action(screen)
+          invoke(controller, own) if own && own != screen[:action].to_s
+
+          Response.new(body: render(screen, controller), url: url)
+        rescue StandardError => e
+          Response.new(body: failure_markup(path, e), url: url)
+        end
+
+        private
+
+        # One instance per controller class, for the life of the session. This
+        # is what makes `@count` behave the way a local in a Ruflet Ruby app
+        # does: it is simply still there on the next tap.
+        def controller_for(klass)
+          @controllers[klass] ||= build_controller(klass)
+        end
+
+        def build_controller(klass)
+          instance = klass.new
+          instance.singleton_class.include(ScreenContext)
+          # One session for the connection, shared by every screen in it. A
+          # controller keeps `session[:count]` working with no request behind
+          # it, and screens can hand state to each other as they always have.
+          instance.ruflet_screen_session = @session
+          instance
+        end
+
+        def invoke(controller, action)
+          return unless controller.respond_to?(action, true)
+
+          controller.send(action)
+        end
+
+        # Params arrive from a form's fields and from trailing path segments
+        # (/native/device_feature/camera -> id "camera"), not from a Rack env.
+        def assign_params(controller, form_params, path_params)
+          values = {}
+          Array(path_params).each_with_index { |value, index| values[index.zero? ? "id" : "param#{index}"] = value }
+          (form_params || {}).each { |key, value| values[key.to_s] = value }
+          controller.ruflet_screen_params = indifferent(values)
+        end
+
+        def indifferent(values)
+          return values unless defined?(::ActiveSupport::HashWithIndifferentAccess)
+
+          ::ActiveSupport::HashWithIndifferentAccess.new(values)
+        end
+
+        # The screen a method belongs to. `counter_increment` has no template of
+        # its own, so it re-renders `counter` — the screen the button was on.
+        # Rendering the compiled template directly, rather than through
+        # `view.render(template:)`, measures about four times faster: the long
+        # way re-resolves the template and fires the render instrumentation on
+        # every tap, and a screen re-renders on every tap.
+        def render(screen, controller)
+          prefix = controller_path(screen[:controller])
+          action = template_action(screen)
+          raise "No template for #{screen[:controller]}##{screen[:action]}" unless action
+
+          view = view_class.new(lookup_for(prefix), assigns_for(controller), nil)
+          # The app's own helpers (ApplicationHelper and any controller-specific
+          # ones) are what a screen reaches for as readily as the DSL's tags.
+          helpers = screen[:controller].try(:_helpers)
+          view.extend(helpers) if helpers
+
+          # Partials still go through view.render (that is how a template asks
+          # for one), and each announces itself to the log subscriber. A screen
+          # re-renders on every tap, so a partial-backed screen would narrate
+          # every tap into the log. Nothing here is a request; there is nothing
+          # for that line to tell anyone.
+          silence_view_logging { template_for_render(prefix, action).render(view, {}) }
+        end
+
+        # Per-thread, so a concurrent web request keeps its own logging.
+        def silence_view_logging(&block)
+          logger = defined?(ActionView::Base.logger) ? ActionView::Base.logger : nil
+          return yield unless logger.respond_to?(:silence)
+
+          logger.silence(::Logger::ERROR, &block)
+        rescue StandardError
+          yield
+        end
+
+        # Holding the compiled template would otherwise defeat template
+        # reloading, so re-resolve when the file changes. A stat costs a
+        # fraction of what resolving again does.
+        def template_for_render(prefix, action)
+          key = "#{prefix}/#{action}"
+          cached, stamp = @templates[key]
+          return cached if cached && (current = template_mtime(cached)) && current == stamp
+
+          # Only once the file has actually changed. Nothing here runs inside
+          # Rails' reloader, so an edited template is never invalidated for us,
+          # and the resolver caches process-wide — but discarding the view class
+          # on a first resolve would strand the partials already compiled into
+          # it, so this must not fire on the way in.
+          invalidate_templates! if cached
+
+          template = lookup_for(prefix).find_template(action, [prefix], false, [])
+          @templates[key] = [template, template_mtime(template)]
+          template
+        end
+
+        def invalidate_templates!
+          ActionView::LookupContext::DetailsKey.clear
+          @templates = {}
+          @lookups = {}
+          @template_actions = {}
+          self.class.reset_view_class!
+        end
+
+        def template_mtime(template)
+          return nil unless template
+
+          File.mtime(template.identifier)
+        rescue SystemCallError
+          nil
+        end
+
+        # Partials in a screen ("render \"nav\"") resolve relative to the
+        # controller's own view folder, so each prefix gets its own context.
+        # Never mutated after creation.
+        def lookup_for(prefix)
+          @lookups[prefix] ||= build_lookup_context([prefix])
+        end
+
+        def template_action(screen)
+          prefix = controller_path(screen[:controller])
+          @template_actions ||= {}
+          @template_actions[[prefix, screen[:action]]] ||=
+            candidates_for(screen[:action]).find { |action| lookup_for(prefix).exists?(action, [prefix]) }
+        end
+
+        # counter_increment -> counter_increment, counter
+        def candidates_for(action)
+          parts = action.to_s.split("_")
+          parts.length.downto(1).map { |take| parts.first(take).join("_") }
+        end
+
+        def controller_path(klass)
+          klass.respond_to?(:controller_path) ? klass.controller_path : klass.name.sub(/Controller\z/, "").downcase
+        end
+
+        def assigns_for(controller)
+          controller.instance_variables.each_with_object({}) do |name, out|
+            key = name.to_s.delete_prefix("@")
+            next if key.start_with?("ruflet_screen")
+
+            out[key] = controller.instance_variable_get(name)
+          end
+        end
+
+        # One view class for the whole process, not per session. ActionView
+        # caches compiled templates process-wide, and a template compiles its
+        # render method into the class that first rendered it — so a class per
+        # session hands the second connection a template that believes it is
+        # already compiled, and every screen it shares raises NoMethodError.
+        class << self
+          def view_class
+            @view_class ||= ActionView::Base.with_empty_template_cache
+          end
+
+          def reset_view_class!
+            @view_class = nil
+          end
+        end
+
+        def view_class = self.class.view_class
+
+        def build_lookup_context(prefixes = [])
+          ActionView::LookupContext.new(::ActionController::Base.view_paths, {}, prefixes)
+        end
+
+
+        def missing(url, path)
+          Response.new(body: <<~HTML, url: url)
+            <column class="p-6 gap-2">
+              <h3>No screen for #{ERB::Util.html_escape(path)}</h3>
+              <text class="text-slate-500">No controller action matches this path.</text>
+            </column>
+          HTML
+        end
+
+        def failure_markup(path, error)
+          <<~HTML
+            <column class="p-6 gap-2">
+              <h3>Screen failed</h3>
+              <text class="text-slate-500">#{ERB::Util.html_escape(path)}</text>
+              <text class="text-red-600">#{ERB::Util.html_escape("#{error.class}: #{error.message}")}</text>
+            </column>
+          HTML
+        end
+
+        # Gives a plain controller instance the few things a screen needs
+        # without a request behind it.
+        module ScreenContext
+          attr_writer :ruflet_screen_params, :ruflet_screen_session
+
+          # Outlives the tap, like a Rails session, but held by the connection
+          # rather than a cookie.
+          def session
+            @ruflet_screen_session ||= {}
+          end
+
+          def params
+            @ruflet_screen_params ||= {}
+          end
+
+        end
+      end
+    end
+  end
+end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
new file mode 100644
index 00000000..18a9d097
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
@@ -0,0 +1,1160 @@
+# frozen_string_literal: true
+
+require "json"
+require "set"
+
+module Ruflet
+  module Rails
+    module HtmlDsl
+      # Turns parsed HTML DSL markup into real Ruflet controls.
+      #
+      # Known tags map to first-class controls (column, row, text, button,
+      # inputs, ...). Any other tag falls through to the full ruflet_core
+      # control registry (`<progress-bar value="0.4">` builds a ProgressBar),
+      # so the whole widget catalog is reachable from markup.
+      #
+      # `handlers` is the running app (HtmlApp): it receives navigation,
+      # actions, form submissions, and field changes.
+      class Transformer
+        Result = Struct.new(:controls, :appbar, :fab, :bottom_nav, :services, :on_load, :title, keyword_init: true)
+
+        HEADING_STYLES = {
+          "h1" => { size: 32, weight: "bold" },
+          "h2" => { size: 28, weight: "bold" },
+          "h3" => { size: 24, weight: "w600" },
+          "h4" => { size: 20, weight: "w600" },
+          "h5" => { size: 18, weight: "w600" },
+          "h6" => { size: 16, weight: "w600" }
+        }.freeze
+
+        TEXT_TAGS = %w[text span p label h1 h2 h3 h4 h5 h6].freeze
+        # Tags that own their tap handling; never wrap them in a gesture detector.
+        SELF_CLICKING_TAGS = %w[a button input select textarea form list-tile fab].freeze
+        CONTAINER_TAGS = %w[div section article main header footer aside container].freeze
+        SKIPPED_TAGS = %w[head meta link title base br template].freeze
+
+        # Non-visual platform services (sensors, storage, permissions, …). Declared in
+        # markup, they mount on the page's service registry rather than in the
+        # visible control tree. Audio is also a service in the Explorer client
+        # (it has no createWidget implementation); video/charts remain ordinary
+        # inline controls.
+        SERVICE_TAGS = %w[
+          audio audio-recorder barometer battery clipboard connectivity
+          file-picker flashlight geolocator gyroscope accelerometer magnetometer
+          haptic-feedback permission-handler screen-brightness secure-storage
+          shake-detector share shared-preferences storage-paths url-launcher
+          user-accelerometer wakelock semantics-service
+        ].freeze
+        SERVICE_TYPES = SERVICE_TAGS.map { |tag| tag.tr("-", "_") }.to_set.freeze
+
+        # Attributes consumed by the DSL itself, never forwarded as props.
+        RESERVED_ATTRIBUTES = %w[class href nav].freeze
+        FIELD_ATTRIBUTES = %w[type name value label placeholder checked rows min max].freeze
+        # Browser-only attributes carried by real-world HTML; never props.
+        HTML_NOISE_ATTRIBUTES = %w[style role tabindex target rel lang dir translate draggable
+                                   contenteditable autocapitalize autocorrect autocomplete
+                                   spellcheck xmlns accept-charset enctype novalidate].freeze
+
+        TEXT_STYLE_KEYS = %i[size weight color italic text_align font_family
+                             max_lines no_wrap overflow selectable].freeze
+        # Box/visual styles applied to a control (or its wrapping container).
+        BOX_STYLE_KEYS = %i[padding margin bgcolor border_radius border shadow opacity
+                            width height rotate scale top left right bottom blur
+                            aspect_ratio clip_behavior gradient visible alignment animate].freeze
+        # Every style key a control may pick up when its schema allows it. Excludes
+        # :alignment (which is {x,y} for boxes but a main-axis string for flex).
+        SCHEMA_STYLE_KEYS = %i[expand width height spacing fit bgcolor color size weight italic
+                               text_align font_family max_lines no_wrap overflow selectable
+                               padding margin border_radius border shadow opacity rotate scale
+                               top left right bottom blur aspect_ratio clip_behavior gradient
+                               visible animate].freeze
+
+        # Attributes naming something the client fetches for itself (an image,
+        # a sound, a video poster) rather than something Ruby resolves.
+        ASSET_URL_ATTRIBUTE = /\A(?:src|url|poster)\z|-(?:src|url)\z/
+
+        def initialize(handlers:, asset_base_url: nil)
+          @handlers = handlers
+          @asset_base_url = asset_base_url.to_s.sub(%r{/+\z}, "")
+        end
+
+        # Screens are dispatched in-process, but media is not: the client loads
+        # an image or a sound itself, over HTTP, so those URLs are the one place
+        # that still needs a real host. A root-relative path ("/assets/logo.png",
+        # which is what the Rails asset pipeline returns) is resolved against the
+        # host the client connected on. Anything already absolute — an external
+        # CDN, a data: URI, a protocol-relative "//host/x" — is left alone, and
+        # so is a bare name, which the client resolves against its bundled
+        # assets directory.
+        def resolve_asset_url(value)
+          return value unless value.is_a?(String)
+          return value if @asset_base_url.empty?
+          return value unless value.start_with?("/")
+          return value if value.start_with?("//")
+
+          "#{@asset_base_url}#{value}"
+        end
+
+        def transform(html)
+          nodes = Parser.parse(html)
+          @result = Result.new(controls: [], appbar: nil, fab: nil, bottom_nav: nil, services: [],
+                               on_load: [], title: nil)
+          scan_document_metadata(nodes)
+
+          @result.controls = build_children(content_nodes(nodes), form: nil)
+          @result
+        end
+
+        private
+
+        # --- document scanning --------------------------------------------------
+
+        def scan_document_metadata(nodes)
+          each_element(nodes) do |element|
+            @result.title = element.text if element.tag == "title" && @result.title.nil?
+          end
+        end
+
+        def each_element(nodes, &block)
+          nodes.each do |node|
+            next unless node.element?
+
+            block.call(node)
+            each_element(node.children, &block)
+          end
+        end
+
+        # Unwrap html/body wrappers so a full Rails layout and a bare partial
+        # both work as screen sources.
+        def content_nodes(nodes)
+          html = nodes.find { |node| node.element? && node.tag == "html" }
+          nodes = html.children if html
+          body = nodes.find { |node| node.element? && node.tag == "body" }
+          body ? body.children : nodes
+        end
+
+        # --- tree building ------------------------------------------------------
+
+        def build_children(nodes, form:)
+          nodes.filter_map { |node| build_node(node, form: form) }
+        end
+
+        def build_node(node, form:)
+          return build_text_run(node.value) if node.text?
+
+          element = node
+          return nil if SKIPPED_TAGS.include?(element.tag)
+          return extract_appbar(element) if element.tag == "appbar"
+          return extract_fab(element) if element.tag == "fab"
+          return extract_bottom_nav(element) if element.tag == "bottom-nav"
+          return extract_service(element) if SERVICE_TYPES.include?(element.tag.tr("-", "_"))
+
+          control = build_element(element, form: form)
+          return nil unless control
+
+          finalize(control, element)
+        rescue ArgumentError => e
+          # One bad element must not take down the screen (a stray attribute,
+          # an unknown icon, a page of plain web HTML): render a visible
+          # placeholder in its spot and keep building.
+          build_error_placeholder(node, e)
+        end
+
+        def build_error_placeholder(node, error)
+          tag = node.element? ? node.tag : "text"
+          text("⚠ <#{tag}> #{error.message}", color: "#b91c1c", size: 12)
+        end
+
+        def build_text_run(value)
+          stripped = value.strip
+          stripped.empty? ? nil : text(collapse_whitespace(stripped))
+        end
+
+        def build_element(element, form:)
+          styles = Styles.parse(element["class"])
+          case element.tag
+          when *TEXT_TAGS then build_text(element, styles)
+          when *CONTAINER_TAGS then build_container(element, styles, form: form)
+          when "column", "row" then build_flex(element, styles, form: form)
+          when "stack" then stack(build_children(element.children, form: form), **control_props(element, "stack"))
+          when "list", "list-view" then list_view(build_children(element.children, form: form),
+                                                  **control_props(element, "listview"))
+          when "grid", "grid-view" then grid_view(build_children(element.children, form: form),
+                                                  **control_props(element, "gridview"))
+          when "card" then build_card(element, styles, form: form)
+          when "center" then center_of(element, form: form)
+          when "spacer" then container(expand: true)
+          when "hr", "divider" then divider(**element_props(element))
+          when "markdown" then markdown(element.text, **element_props(element))
+          when "img", "image" then build_image(element, styles)
+          when "icon" then icon(element["name"] || element.text, **element_props(element, except: %w[name]))
+          when "a" then build_link(element, styles, form: form)
+          when "button" then build_button(element, form: form)
+          when "input" then build_input(element, form: form)
+          when "textarea" then build_textarea(element, form: form)
+          when "select" then build_select(element, form: form)
+          when "form" then build_form(element, styles)
+          when "ul", "ol" then build_list(element, styles, form: form)
+          when "badge" then build_badge(element, form: form)
+          when "tooltip" then build_tooltip(element, form: form)
+          when "list-tile" then build_list_tile(element)
+          when "expansion-tile" then build_expansion_tile(element, form: form)
+          when "tabs" then build_tabs(element, styles, form: form)
+          when "segmented-button" then build_segmented_button(element, form: form)
+          when "radio-group" then build_radio_group(element, styles, form: form)
+          when "radio" then build_radio(element)
+          when "switch" then build_toggle(element, form: form, builder: :switch)
+          when "checkbox" then build_toggle(element, form: form, builder: :checkbox)
+          when "slider" then build_slider(element, form: form)
+          when "textfield", "text-field" then build_textfield(element, form: form,
+                                                              multiline: element.key?("multiline"))
+          when "table" then build_table(element, form: form)
+          when "avatar" then build_avatar(element)
+          when "chip" then build_chip(element)
+          when "progress" then progress_bar(**element_props(element))
+          else
+            build_generic(element, form: form)
+          end
+        end
+
+        def build_text(element, styles)
+          props = { value: apply_text_transform(collapse_whitespace(element.text), styles[:text_transform]) }
+          props.merge!(HEADING_STYLES[element.tag] || {})
+          props.merge!(styles.slice(*TEXT_STYLE_KEYS))
+          style = text_style_map(styles)
+          props[:style] = style unless style.empty?
+          props.merge!(element_props(element))
+          wrap_in_box(text(**props), styles)
+        end
+
+        # letter-spacing / line-height / decoration live in a nested TextStyle;
+        # the client copyWiths top-level size/color over it, so both coexist.
+        def text_style_map(styles)
+          map = {}
+          map["letter_spacing"] = styles[:letter_spacing] if styles.key?(:letter_spacing)
+          map["height"] = styles[:line_height] if styles[:line_height]
+          map["decoration"] = styles[:decoration] if styles[:decoration]
+          map
+        end
+
+        def apply_text_transform(value, transform)
+          case transform
+          when "uppercase" then value.upcase
+          when "lowercase" then value.downcase
+          when "capitalize" then value.gsub(/\b\w/, &:upcase)
+          else value
+          end
+        end
+
+        def build_container(element, styles, form:)
+          children = build_children(element.children, form: form)
+          content = children.length == 1 ? children.first : column(children, **flex_props(styles))
+          props = element_props(element)
+          props[:content] = content if content
+          props[:alignment] = { x: 0, y: 0 } if styles[:main_alignment] == "center" &&
+                                                styles[:cross_alignment] == "center"
+          container(**box_props(styles), **props)
+        end
+
+        def build_flex(element, styles, form:)
+          children = build_children(element.children, form: form)
+          builder = element.tag == "column" ? :column : :row
+          control = send(builder, children, **flex_props(styles, axis: element.tag),
+                                            **element_props(element))
+          wrap_in_box(control, styles)
+        end
+
+        def build_card(element, styles, form:)
+          children = build_children(element.children, form: form)
+          content = children.length == 1 ? children.first : column(children, **flex_props(styles))
+          content = container(content: content, padding: styles[:padding] || 16)
+          card(content, **element_props(element))
+        end
+
+        def center_of(element, form:)
+          children = build_children(element.children, form: form)
+          content = children.length == 1 ? children.first : column(children, tight: true)
+          container(content: content, alignment: { x: 0, y: 0 }, expand: true)
+        end
+
+        def build_image(element, styles)
+          props = element_props(element, except: %w[src alt])
+          props[:semantics_label] = element["alt"] if element["alt"]
+          props.merge!(styles.slice(:width, :height, :border_radius, :fit, :opacity,
+                                    :aspect_ratio, :rotate, :scale))
+          image(resolve_asset_url(element["src"]), **props)
+        end
+
+        def build_list(element, styles, form:)
+          items = element.elements.select { |child| child.tag == "li" }.map do |item|
+            children = build_children(item.children, form: form)
+            children.length == 1 ? children.first : row(children, spacing: 6)
+          end
+          column(items, **flex_props(styles, axis: "column"), **element_props(element))
+        end
+
+        # --- interactive elements ----------------------------------------------
+
+        def build_link(element, styles, form:)
+          href = element["href"].to_s
+          mode = element["nav"] || "push"
+          on_click = navigation_handler(href, mode)
+          label_nodes = element.children
+          nested = element.elements
+
+          if nested.empty?
+            props = styles.slice(*TEXT_STYLE_KEYS)
+            text_button(content: text(collapse_whitespace(element.text), **props), on_click: on_click)
+          else
+            children = build_children(label_nodes, form: form)
+            content = children.length == 1 ? children.first : column(children, tight: true)
+            gesture_detector(content: wrap_in_box(content, styles), on_tap: on_click)
+          end
+        end
+
+        BUTTON_VARIANTS = {
+          "filled" => :filled_button, "tonal" => :filled_tonal_button,
+          "outlined" => :outlined_button, "text" => :text_button, "elevated" => :button
+        }.freeze
+
+        def build_button(element, form:)
+          label = collapse_whitespace(element.text)
+          icon = element["icon"]
+          on_click =
+            if element["service"]
+              register_on_load(element)
+              service_handler(element)
+            elsif element["on-click"]
+              action_handler(element["on-click"])
+            elsif element["href"]
+              navigation_handler(element["href"], element["nav"] || "push")
+            elsif form
+              submit_handler(form)
+            end
+
+          # A service button's arbitrary attributes are native method
+          # arguments, not button props. Keep visual styling from `class`, but
+          # never leak a future service argument into the strict Button schema.
+          # Service metadata is not part of Button's schema, but `id` and
+          # `disabled` still belong to the button itself. Camera uses both: the
+          # capture action starts disabled and is enabled by id after init.
+          skip = if element["service"]
+                   element.attrs.keys - %w[id disabled]
+                 else
+                   %w[icon variant type name value]
+                 end
+
+          # An icon with no label must be an IconButton: the Material Button
+          # control renders an ErrorControl when `icon` is set without `content`.
+          if icon && label.empty?
+            props = control_props(element, "iconbutton", except: skip)
+            props[:on_click] = on_click if on_click
+            return icon_button(icon, **props)
+          end
+
+          builder = BUTTON_VARIANTS[element["variant"]] || :button
+          props = control_props(element, "filledbutton", except: skip)
+          props[:icon] = icon if icon
+          props[:on_click] = on_click if on_click
+          send(builder, label.empty? ? nil : label, **props)
+        end
+
+        # `<button service="copy" text="…">` — tapping runs a native platform
+        # service (clipboard, share, haptics, flashlight, launch, …). The whole
+        # element's attributes are passed as the spec.
+        def service_handler(element)
+          spec = service_spec(element)
+          handlers = @handlers
+          ->(_event) { handlers.service(spec) }
+        end
+
+        def service_spec(element)
+          element.attrs.transform_values { |value| coerce_value(value) }
+        end
+
+        # `<button service="battery" result-target="x" on-load>` runs the service
+        # once when the screen appears, the way Studio calls `refresh_info` at
+        # build time to populate a panel before any tap. Collected here and run
+        # by HtmlApp after the screen mounts.
+        def register_on_load(element)
+          @result.on_load << service_spec(element) if element.attrs.key?("on-load")
+        end
+
+        def build_input(element, form:)
+          type = (element["type"] || "text").downcase
+          name = element["name"]
+
+          case type
+          when "checkbox"
+            build_toggle(element, form: form, builder: :checkbox)
+          when "range"
+            build_slider(element, form: form)
+          when "radio"
+            build_radio(element)
+          when "submit"
+            props = { on_click: form ? submit_handler(form) : nil }.compact
+            filled_button(element["value"] || "Submit", **props)
+          when "hidden"
+            register_field(form, name, element["value"])
+            nil
+          else
+            build_textfield(element, form: form, password: type == "password",
+                                     keyboard_type: keyboard_for(type))
+          end
+        end
+
+        def build_textfield(element, form:, password: false, keyboard_type: nil, multiline: false)
+          props = control_props(element, "textfield", except: FIELD_ATTRIBUTES)
+          props[:label] = element["label"] if element["label"]
+          props[:hint_text] = element["placeholder"] if element["placeholder"]
+          props[:password] = true if password
+          props[:keyboard_type] = keyboard_type if keyboard_type
+          if multiline
+            props[:multiline] = true
+            props[:min_lines] = (element["rows"] || 3).to_i
+          end
+          props[:on_change] = field_handler(element["name"])
+          props.delete(:on_change) if props[:on_change].nil?
+          register_field(form, element["name"], element["value"])
+          text_field(element["value"], **props)
+        end
+
+        def build_textarea(element, form:)
+          element.attrs["value"] ||= element.text unless element.text.empty?
+          build_textfield(element, form: form, multiline: true)
+        end
+
+        def build_select(element, form:)
+          options = element.elements.select { |child| child.tag == "option" }.map do |option|
+            dropdown_option(option["value"] || option.text, text: option.text)
+          end
+          selected = element.elements.find { |child| child.tag == "option" && child.key?("selected") }
+          value = element["value"] || selected&.[]("value") || selected&.text
+          register_field(form, element["name"], value)
+          props = { value: value, label: element["label"],
+                    on_select: field_handler(element["name"]) }.compact
+          dropdown(options, **props, **control_props(element, "dropdown", except: FIELD_ATTRIBUTES))
+        end
+
+        def build_form(element, styles)
+          form = {
+            action: element["action"].to_s,
+                        fields: {}
+          }
+          children = build_children(element.children, form: form)
+          wrap_in_box(column(children, **flex_props(styles, axis: "column")), styles)
+        end
+
+        def keyboard_for(type)
+          { "email" => "email", "number" => "number", "tel" => "phone", "url" => "url" }[type]
+        end
+
+        # --- stateful components --------------------------------------------------
+
+        # <switch name="dark" label="Dark mode" checked> / <checkbox ...> —
+        # named toggles report their value like form fields.
+        def build_toggle(element, form:, builder:)
+          name = element["name"]
+          checked = element.key?("checked")
+          props = { label: element["label"], value: checked, on_change: field_handler(name) }.compact
+          register_field(form, name, checked)
+          send(builder, **props, **element_props(element, except: FIELD_ATTRIBUTES))
+        end
+
+        def build_slider(element, form:)
+          name = element["name"]
+          props = { value: element["value"]&.to_f, min: (element["min"] || 0).to_f,
+                    max: (element["max"] || 100).to_f, on_change: field_handler(name) }.compact
+          attach_declared_events(element, props, registry_props("slider"))
+          register_field(form, name, element["value"])
+          slider(**props, **element_props(element, except: FIELD_ATTRIBUTES))
+        end
+
+        def build_radio(element)
+          props = { value: element["value"], label: element["label"] }.compact
+          radio(**props, **element_props(element, except: FIELD_ATTRIBUTES))
+        end
+
+        # <radio-group name="plan" value="pro"><radio value="free" label="Free">...</radio-group>
+        def build_radio_group(element, styles, form:)
+          name = element["name"]
+          children = build_children(element.children, form: form)
+          register_field(form, name, element["value"])
+          props = { value: element["value"], on_change: field_handler(name) }.compact
+          radio_group(column(children, **flex_props(styles)),
+                      **props, **element_props(element, except: FIELD_ATTRIBUTES))
+        end
+
+        # <segmented-button name="view" value="list"><segment value="list" label="List" icon="list"/>...
+        def build_segmented_button(element, form:)
+          segments = element.elements.select { |child| child.tag == "segment" }.map do |seg|
+            props = { label: seg["label"] || (seg.text.empty? ? nil : seg.text), icon: seg["icon"] }.compact
+            segment(seg["value"], **props)
+          end
+          name = element["name"]
+          props = { on_change: field_handler(name) }.compact
+          props.merge!(element_props(element, except: FIELD_ATTRIBUTES))
+          if element["value"]
+            props[:selected] = [element["value"]]
+          else
+            props[:allow_empty_selection] = true unless props.key?(:allow_empty_selection)
+          end
+          register_field(form, name, element["value"])
+          segmented_button(segments, **props)
+        end
+
+        # --- composite components -------------------------------------------------
+
+        # <badge label="3"><icon name="notifications"/></badge> — badge is a
+        # prop on the wrapped control, not a control of its own. The client
+        # accepts either a scalar label or a full Badge control (a bare Hash
+        # renders as its `toString`, e.g. "{label: 3}"), so build accordingly.
+        def build_badge(element, form:)
+          children = build_children(element.children, form: form)
+          content = children.length == 1 ? children.first : (children.empty? ? nil : column(children, tight: true))
+          label = element["label"].to_s
+          return text(label) if content.nil?
+
+          styling = element_props(element, except: %w[label])
+          content.props["badge"] =
+            if styling.empty?
+              label
+            else
+              badge(label, **styling)
+            end
+          content
+        end
+
+        # <tooltip message="Explanation"><icon name="help"/></tooltip>
+        def build_tooltip(element, form:)
+          children = build_children(element.children, form: form)
+          content = children.length == 1 ? children.first : column(children, tight: true)
+          return nil if content.nil?
+
+          content.props["tooltip"] = (element["message"] || element["text"]).to_s
+          content
+        end
+
+        # <list-tile title="Inbox" subtitle="12 unread" leading="mail" href="/inbox">
+        def build_list_tile(element)
+          props = element_props(element, except: %w[title subtitle leading trailing icon])
+          props[:title] = element["title"] if element["title"]
+          props[:subtitle] = element["subtitle"] if element["subtitle"]
+          leading = element["leading"] || element["icon"]
+          props[:leading] = leading if leading
+          props[:trailing] = element["trailing"] if element["trailing"]
+          handler =
+            if element["on-click"]
+              action_handler(element["on-click"])
+            elsif element["href"]
+              navigation_handler(element["href"], element["nav"] || "push")
+            end
+          props[:on_click] = handler if handler
+          list_tile(**props)
+        end
+
+        # <expansion-tile title="Details" subtitle="...">children…</expansion-tile>
+        def build_expansion_tile(element, form:)
+          children = build_children(element.children, form: form)
+          props = element_props(element, except: %w[title subtitle leading icon])
+          props[:title] = element["title"].to_s
+          props[:subtitle] = element["subtitle"] if element["subtitle"]
+          leading = element["leading"] || element["icon"]
+          props[:leading] = leading if leading
+          expansion_tile(children, **props)
+        end
+
+        # <tabs><tab label="One" icon="home">…</tab><tab label="Two">…</tab></tabs>
+        # The client's Tabs is a controller: it hosts a TabBar plus a
+        # TabBarView with one pane per tab.
+        def build_tabs(element, styles, form:)
+          tab_elements = element.elements.select { |child| child.tag == "tab" }
+          return nil if tab_elements.empty?
+
+          labels = tab_elements.map do |tab_element|
+            props = {}
+            props[:icon] = tab_element["icon"] if tab_element["icon"]
+            tab(tab_element["label"].to_s, **props)
+          end
+          panes = tab_elements.map do |tab_element|
+            column(build_children(tab_element.children, form: form), spacing: 0, scroll: "auto")
+          end
+          props = element_props(element)
+          props[:expand] = true unless props.key?(:expand)
+          props[:expand] = true if styles[:expand]
+          tabs(
+            column([tab_bar(labels), tab_bar_view(panes, expand: true)], spacing: 0, expand: true),
+            length: tab_elements.length,
+            **props
+          )
+        end
+
+        # Plain HTML tables become native DataTables:
+        # <table><thead><tr><th>…</th></tr></thead><tbody><tr><td>…</td></tr></tbody></table>
+        def build_table(element, form:)
+          rows = collect_table_rows(element)
+          header = rows.find { |tr| tr.elements.any? { |cell| cell.tag == "th" } }
+          body_rows = rows - [header]
+
+          columns = table_cells(header).map { |th| data_column(text(th.text, weight: "w600")) }
+          if columns.empty? && body_rows.any?
+            columns = Array.new(table_cells(body_rows.first).length) { data_column(text("")) }
+          end
+
+          data_rows = body_rows.map do |tr|
+            cells = table_cells(tr).map { |td| data_cell(table_cell_content(td, form: form)) }
+            data_row(cells)
+          end
+          data_table(columns, rows: data_rows, **element_props(element))
+        end
+
+        def collect_table_rows(element)
+          element.elements.flat_map do |child|
+            case child.tag
+            when "tr" then [child]
+            when "thead", "tbody", "tfoot" then child.elements.select { |tr| tr.tag == "tr" }
+            else []
+            end
+          end
+        end
+
+        def table_cells(tr)
+          return [] unless tr
+
+          tr.elements.select { |cell| %w[th td].include?(cell.tag) }
+        end
+
+        def table_cell_content(cell, form:)
+          children = build_children(cell.children, form: form)
+          case children.length
+          when 0 then text("")
+          when 1 then children.first
+          else row(children, spacing: 6)
+          end
+        end
+
+        # <chip label="Ruby"> or <chip>Ruby</chip> — Chip needs `label`, and
+        # a bare `on-click` becomes its native click action.
+        def build_chip(element)
+          props = element_props(element, except: %w[label icon])
+          props[:label] = element["label"] || collapse_whitespace(element.text)
+          props[:leading] = element["icon"] if element["icon"]
+          if element["on-click"]
+            props[:on_click] = action_handler(element["on-click"])
+          elsif element["href"]
+            props[:on_click] = navigation_handler(element["href"], element["nav"] || "push")
+          end
+          chip(**props)
+        end
+
+        # <avatar src="/me.png"> or <avatar class="bg-violet-500">AM</avatar>
+        def build_avatar(element)
+          styles = Styles.parse(element["class"])
+          props = element_props(element, except: %w[src alt])
+          props[:foreground_image_src] = resolve_asset_url(element["src"]) if element["src"]
+          props[:bgcolor] = styles[:bgcolor] if styles[:bgcolor]
+          initials = collapse_whitespace(element.text)
+          content = initials.empty? ? nil : text(initials, color: styles[:color] || "#ffffff", weight: "bold")
+          circle_avatar(content, **props)
+        end
+
+        # <fab icon="add" href="/items/new"> — mounts as the screen's
+        # FloatingActionButton, like <appbar>.
+        def extract_fab(element)
+          props = element_props(element, except: %w[icon label])
+          props[:icon] = element["icon"] if element["icon"]
+          label = element["label"] || collapse_whitespace(element.text)
+          props[:content] = text(label) unless label.to_s.empty?
+          handler =
+            if element["on-click"]
+              action_handler(element["on-click"])
+            elsif element["href"]
+              navigation_handler(element["href"], element["nav"] || "push")
+            end
+          props[:on_click] = handler if handler
+          @result.fab = floating_action_button(**props)
+          nil
+        end
+
+        # <bottom-nav>
+        #   <nav-item icon="chat" label="Chats" href="/chats" selected></nav-item>
+        #   <nav-item icon="call" label="Calls" href="/calls"></nav-item>
+        # </bottom-nav>
+        # Mounts as the screen's NavigationBar; a destination tap resets to that
+        # URL as a new root (tab semantics), like the WebView shell's bottomnav.
+        def extract_bottom_nav(element)
+          items = element.elements.select { |el| el.tag == "nav-item" }
+          return nil if items.length < 2
+
+          destinations = items.filter_map do |item|
+            icon = item["icon"].to_s
+            next if icon.empty?
+
+            navigation_bar_destination(icon: icon, label: item["label"].to_s)
+          end
+          return nil if destinations.length < 2
+
+          urls = items.map { |item| item["href"].to_s }
+          handlers = @handlers
+          @result.bottom_nav = navigation_bar(
+            destinations: destinations,
+            selected_index: items.index { |item| item.key?("selected") } || 0,
+            on_change: lambda do |event|
+              url = urls[nav_event_index(event)].to_s
+              handlers.navigate(url, "root") unless url.empty?
+            end
+          )
+          nil
+        end
+
+        def nav_event_index(event)
+          data = event.respond_to?(:data) ? event.data : event
+          return (data["selected_index"] || data["value"] || data["i"] || 0).to_i if data.is_a?(Hash)
+
+          data.to_i
+        end
+
+        # A non-visual platform service (`<camera>`, `<geolocator>`, `<battery>`,
+        # …). It mounts on the page's service registry instead of the visible
+        # tree, so it registers with the client without rendering anything.
+        # Streaming sensors emit continuously. With no `interval` the client
+        # pushes readings at the device's native rate — tens to hundreds per
+        # second — and each one round-trips a status update, flooding the wire
+        # and making the screen janky. Default to Studio's calm 200ms cadence
+        # unless the author sets their own.
+        STREAMING_SENSORS = %w[
+          accelerometer gyroscope magnetometer barometer useraccelerometer
+        ].to_set.freeze
+        SENSOR_DEFAULT_INTERVAL = 200
+
+        def extract_service(element)
+          type = element.tag.tr("-", "_")
+          props = element_props(element)
+          props[:interval] ||= SENSOR_DEFAULT_INTERVAL if STREAMING_SENSORS.include?(type.delete("_"))
+          attach_declared_events(element, props, registry_props(type))
+          service = Ruflet::UI::ControlFactory.build(type, **props)
+          @result.services << service
+          nil
+        end
+
+        # --- generic control passthrough ----------------------------------------
+
+        # Any tag without a dedicated builder maps straight onto the ruflet_core
+        # control registry, so the whole Ruflet catalog is reachable from
+        # markup. Text and child controls are routed into whichever prop the
+        # control's schema actually accepts (content / controls / label /
+        # title), instead of blindly assuming `value` — most controls have no
+        # `value`, and a wrong prop would fail strict-schema validation.
+        TEXT_SLOTS = %w[content label title text message value].freeze
+
+        # Chart controls carry their data in named props, not `content`/`controls`.
+        # Nested chart tags (`<bar-chart-group>`, `<line-chart-data>`, …) build the
+        # matching control, and this maps each one into the slot its parent expects
+        # — so a whole chart can be authored as plain nested HTML.
+        CHART_SLOT_FOR_CHILD = {
+          "barchartgroup" => :groups,
+          "barchartrod" => :rods,
+          "barchartrodstackitem" => :rod_stack_items,
+          "linechartdata" => :data_series,
+          "linechartdatapoint" => :points,
+          "piechartsection" => :sections,
+          "candlestickchartspot" => :spots,
+          "scatterchartspot" => :spots,
+          "radardataset" => :data_sets,
+          "radardatasetentry" => :entries,
+          "radarcharttitle" => :titles,
+          "chartaxislabel" => :labels
+        }.freeze
+
+        # Extension controls whose nested controls live in a named collection.
+        # These cannot use the generic `children` array because their Flutter
+        # renderers explicitly read the named property (Map reads `layers`,
+        # MarkerLayer reads `markers`, and so on).
+        CHILD_SLOT_FOR_PARENT = {
+          "map" => :layers,
+          "marker_layer" => :markers,
+          "markerlayer" => :markers,
+          "circle_layer" => :circles,
+          "circlelayer" => :circles,
+          "polyline_layer" => :polylines,
+          "polylinelayer" => :polylines,
+          "polygon_layer" => :polygons,
+          "polygonlayer" => :polygons
+        }.freeze
+
+        # Chart controls have no `expand` and don't inherit their parent's box:
+        # a chart with no width/height renders as an empty (zero-size) widget.
+        # Studio always sizes charts explicitly; default to studio-typical dims
+        # so a chart authored without them still shows. Authors can override.
+        CHART_TYPES = %w[
+          barchart linechart piechart scatterchart candlestickchart radarchart
+        ].to_set.freeze
+        CHART_DEFAULT_WIDTH = 320
+        CHART_DEFAULT_HEIGHT = 240
+
+        # Map controls that wrap a single child in `content` (not the generic
+        # `controls` list): a Marker holds one icon/widget, the way Studio's
+        # `marker(content: icon(...))` does.
+        CONTENT_CHILD_TYPES = %w[marker].to_set.freeze
+
+        # Props that hold a `[lat, lng]` pair. Studio's `marker`/`circle_marker`/
+        # `map` builders normalise these to `{latitude:, longitude:}`; the Map
+        # control constructor does it for `initial_center` but the layer controls
+        # don't, so a raw array reaches the client and the marker never places.
+        # Normalise them here so every map control gets Studio's wire shape.
+        MAP_COORDINATE_PROPS = %i[coordinates initial_center center].freeze
+
+        def build_generic(element, form:)
+          type = element.tag.tr("-", "_")
+          allowed = registry_props(type)
+          props = element_props(element).merge(schema_style_props(element, type))
+          apply_chart_defaults(type, props)
+          normalize_map_coordinates(props)
+          attach_declared_events(element, props, allowed)
+          child_elements = element.elements
+
+          if child_elements.empty?
+            assign_text_content(props, allowed, collapse_whitespace(element.text))
+            return Ruflet::UI::ControlFactory.build(type, **props)
+          end
+
+          children = build_children(element.children, form: form)
+          if CONTENT_CHILD_TYPES.include?(type)
+            props[:content] = children.length == 1 ? children.first : column(children)
+            return Ruflet::UI::ControlFactory.build(type, **props)
+          end
+          if (slot = CHILD_SLOT_FOR_PARENT[type])
+            props[slot] = children
+            return Ruflet::UI::ControlFactory.build(type, **props)
+          end
+          slotted = chart_slots(children)
+          unless slotted.empty?
+            slotted.each { |slot, controls| props[slot] = controls }
+            return Ruflet::UI::ControlFactory.build(type, **props)
+          end
+          assign_child_content(type, props, allowed, children)
+        end
+
+        # Translate extension callbacks from ERB attributes into native event
+        # handlers. This is the HTML equivalent of Studio's Ruby lambdas.
+        # Example: on-tap-target="map-status" on-tap-prefix="Map tap: ".
+        def attach_declared_events(element, props, allowed)
+          event_names = element.attrs.keys.filter_map do |attribute|
+            match = attribute.match(/\Aon-(.+)-(?:target|service)\z/)
+            match && match[1]
+          end.uniq
+
+          event_names.each do |event_name|
+            prop_name = "on_#{event_name.tr('-', '_')}"
+            next if allowed && !allowed.include?(prop_name)
+
+            prefix = "on-#{event_name}-"
+            spec = {
+              "target" => element["#{prefix}target"],
+              "message" => element["#{prefix}message"],
+              "prefix" => element["#{prefix}prefix"],
+              "control" => element["#{prefix}control"],
+              "property" => element["#{prefix}property"],
+              # An event can re-run a whole service (Studio's battery refreshes on
+              # every `on_state_change`), reporting into `result-target`.
+              "service" => element["#{prefix}service"],
+              "result-target" => element["#{prefix}result-target"] || element["#{prefix}target"]
+            }.compact
+            handlers = @handlers
+            props[prop_name.to_sym] = ->(event) { handlers.control_event(spec, event) }
+          end
+        end
+
+        def apply_chart_defaults(type, props)
+          return unless CHART_TYPES.include?(type.delete("_"))
+
+          props[:width] ||= CHART_DEFAULT_WIDTH
+          props[:height] ||= CHART_DEFAULT_HEIGHT
+        end
+
+        def normalize_map_coordinates(props)
+          MAP_COORDINATE_PROPS.each do |key|
+            props[key] = map_coordinate(props[key]) if props.key?(key)
+          end
+        end
+
+        # Mirror ruflet_core's `map_coordinates`: accept `[lat, lng]` or a hash
+        # with lat/lng-ish keys and emit the `{latitude:, longitude:}` shape the
+        # client's flutter_map layers expect.
+        def map_coordinate(value)
+          case value
+          when Array
+            value.length >= 2 ? { "latitude" => value[0], "longitude" => value[1] } : value
+          when Hash
+            lat = value["latitude"] || value[:latitude] || value["lat"] || value[:lat]
+            lng = value["longitude"] || value[:longitude] || value["lng"] ||
+                  value[:lng] || value["lon"] || value[:lon]
+            lat.nil? || lng.nil? ? value : { "latitude" => lat, "longitude" => lng }
+          else
+            value
+          end
+        end
+
+        # Group chart-primitive children by the named prop their parent reads them
+        # from. Returns {} when none are chart primitives, so non-chart controls
+        # fall through to the usual content/controls routing.
+        def chart_slots(children)
+          children.each_with_object({}) do |child, slots|
+            next unless child.is_a?(Ruflet::Control)
+
+            slot = CHART_SLOT_FOR_CHILD[child.type]
+            (slots[slot] ||= []) << child if slot
+          end
+        end
+
+        # Route leaf text into the best available string/content slot.
+        def assign_text_content(props, allowed, value)
+          return if value.empty? || props.key?(:value)
+
+          if allowed.nil? || allowed.include?("content")
+            props[:content] = text(value)
+          elsif (slot = (TEXT_SLOTS & allowed.to_a).first)
+            props[slot.to_sym] = value
+          elsif allowed.include?("controls")
+            props[:controls] = [text(value)]
+          end
+        end
+
+        # Route child controls into `controls` (list-like) or `content`
+        # (single-child) depending on what the control accepts.
+        def assign_child_content(type, props, allowed, children)
+          if allowed.nil?
+            control = Ruflet::UI::ControlFactory.build(type, **props)
+            children.each { |child| control.children << child }
+            return control
+          end
+
+          list_slot = allowed.include?("controls")
+          content_slot = allowed.include?("content")
+          if list_slot && !(children.length == 1 && content_slot)
+            props[:controls] = children
+          elsif content_slot
+            props[:content] = children.length == 1 ? children.first : column(children)
+          elsif list_slot
+            props[:controls] = children
+          elsif allowed.include?("children")
+            props[:children] = children
+          else
+            control = Ruflet::UI::ControlFactory.build(type, **props)
+            children.each { |child| control.children << child }
+            return control
+          end
+          Ruflet::UI::ControlFactory.build(type, **props)
+        end
+
+        # Allowed property names for a registry type, or nil when the control
+        # uses a non-strict schema (attach children directly). Mirrors how
+        # Ruflet::Control derives its schema, without touching ruflet_core.
+        def registry_props(type)
+          @registry_props_cache ||= {}
+          return @registry_props_cache[type] if @registry_props_cache.key?(type)
+
+          klass = Ruflet::UI::ControlFactory::CLASS_MAP[type]
+          names =
+            if klass.nil?
+              []
+            elsif klass.const_defined?(:KEYWORDS)
+              klass::KEYWORDS
+            else
+              params = klass.instance_method(:initialize).parameters.select { |kind, _| %i[key keyreq].include?(kind) }
+              params.any? { |_, name| name.nil? } ? [] : params.map { |_, name| name }
+            end
+          set = names.empty? ? nil : names.map(&:to_s).to_set
+          @registry_props_cache[type] = set
+        end
+
+        # --- appbar ---------------------------------------------------------------
+
+        # `<appbar title="Inbox" leading-icon="menu">` with optional
+        # `<action icon="search" href="/search"/>` children becomes the native
+        # AppBar of the screen.
+        def extract_appbar(element)
+          actions = element.elements.select { |child| child.tag == "action" }.filter_map do |action|
+            next if action["icon"].to_s.empty?
+
+            icon_button(action["icon"], on_click: appbar_action_handler(action))
+          end
+
+          leading = nil
+          leading_icon = element["leading-icon"]
+          if leading_icon
+            leading_mode = element["leading-nav"] || "back"
+            leading = icon_button(leading_icon, on_click: navigation_handler(element["leading-href"].to_s,
+                                                                             leading_mode))
+          end
+
+          args = {}
+          args[:title] = text(element["title"].to_s)
+          if leading
+            args[:leading] = leading
+            args[:automatically_imply_leading] = false
+          end
+          args[:actions] = actions unless actions.empty?
+          args[:bgcolor] = Styles.color_for(element["bgcolor"]) || element["bgcolor"] if element["bgcolor"]
+          @result.appbar = appbar(**args)
+          nil
+        end
+
+        def appbar_action_handler(action)
+          if action["on-click"]
+            action_handler(action["on-click"])
+          else
+            navigation_handler(action["href"].to_s, action["nav"] || "push")
+          end
+        end
+
+        # --- events / handlers ----------------------------------------------------
+
+        def navigation_handler(url, mode)
+          handlers = @handlers
+          ->(_event) { handlers.navigate(url, mode) }
+        end
+
+        # `on-click="post:/counter/increment"`, `on-click="/refresh"` (POST by
+        # default), `on-click="get:/search"`.
+        # An on-click names the screen path whose method to run. It used to
+        # carry an HTTP verb ("post:/x"); nothing dispatches a request now, so
+        # a leading verb is stripped rather than obeyed.
+        def action_handler(spec)
+          url = spec.to_s.sub(%r{\A(?:get|post|put|patch|delete):}i, "")
+          handlers = @handlers
+          ->(_event) { handlers.action(url: url) }
+        end
+
+        def submit_handler(form)
+          handlers = @handlers
+          ->(_event) { handlers.submit_form(form) }
+        end
+
+        def field_handler(name)
+          return nil if name.to_s.empty?
+
+          handlers = @handlers
+          ->(event) { handlers.field_changed(name, event_value(event)) }
+        end
+
+        def register_field(form, name, initial)
+          return if name.to_s.empty?
+
+          form[:fields][name] = initial if form
+          @handlers.field_changed(name, initial) if @handlers.respond_to?(:field_changed)
+        end
+
+
+        def event_value(event)
+          data = event.respond_to?(:data) ? event.data : event
+          # Not `||`: a switch reports value `false`, which `||` would discard.
+          if data.is_a?(Hash)
+            return data["value"] if data.key?("value")
+            return data[:value] if data.key?(:value)
+          end
+          data
+        end
+
+        # Generic `on-click` on non-interactive elements gets a tap wrapper.
+        def finalize(control, element)
+          spec = element["on-click"] || element["on-tap"]
+          return control unless spec
+          return control if SELF_CLICKING_TAGS.include?(element.tag)
+
+          gesture_detector(content: control, on_tap: action_handler(spec))
+        end
+
+        # --- props & styling -------------------------------------------------------
+
+        # Remaining element attributes become control props: kebab-case turns
+        # into snake_case, values parse as JSON scalars/structures when they
+        # look like one.
+        def element_props(element, except: [])
+          skip = RESERVED_ATTRIBUTES + except
+          element.attrs.each_with_object({}) do |(name, value), props|
+            next if skip.include?(name) || HTML_NOISE_ATTRIBUTES.include?(name)
+            next if name.start_with?("on-", "data-", "aria-")
+            # Browser JS handlers (onclick, onchange, ...) are not DSL events.
+            next if name.match?(/\Aon[a-z]+\z/)
+
+            value = resolve_asset_url(value) if name.match?(ASSET_URL_ATTRIBUTE)
+            props[name.tr("-", "_").to_sym] = coerce_value(value)
+          end
+        end
+
+        # Style-derived props (from `class`) that a given control actually
+        # accepts. Lets non-container controls — list/grid/inputs/buttons — pick
+        # up `flex-1`, `w-64`, `p-3`, `gap-2`, `bg-*`, etc. (element_props only
+        # forwards raw attributes, never the parsed class).
+        def schema_style_props(element, type)
+          styles = Styles.parse(element["class"])
+          return {} if styles.empty?
+
+          allowed = registry_props(type)
+          styles.slice(*SCHEMA_STYLE_KEYS).select { |key, _| allowed.nil? || allowed.include?(key.to_s) }
+        end
+
+        # element_props plus the schema-valid style props for `type`.
+        def control_props(element, type, except: [])
+          element_props(element, except: except).merge(schema_style_props(element, type))
+        end
+
+        def coerce_value(value)
+          case value
+          when "true", "" then true
+          when "false" then false
+          when /\A-?\d+\z/ then value.to_i
+          when /\A-?\d+\.\d+\z/ then value.to_f
+          when /\A[\[{]/
+            begin
+              JSON.parse(value)
+            rescue JSON::ParserError
+              value
+            end
+          else
+            value
+          end
+        end
+
+        def flex_props(styles, axis: "column")
+          props = {}
+          props[:spacing] = styles[:spacing] if styles[:spacing]
+          props[:run_spacing] = styles[:run_spacing] if styles[:run_spacing]
+          props[:scroll] = styles[:scroll] if styles[:scroll]
+          props[:expand] = true if styles[:expand]
+          props[:wrap] = true if styles[:wrap]
+          if styles[:main_alignment]
+            props[:alignment] = styles[:main_alignment]
+          end
+          if styles[:cross_alignment]
+            key = axis == "row" ? :vertical_alignment : :horizontal_alignment
+            props[key] = styles[:cross_alignment]
+          end
+          props
+        end
+
+        def box_props(styles)
+          props = styles.slice(*BOX_STYLE_KEYS)
+          props[:expand] = true if styles[:expand]
+          props
+        end
+
+        # Text/flex controls carry no box styling of their own; give them a
+        # container wrapper when the class list asks for one.
+        def wrap_in_box(control, styles)
+          boxed = box_props(styles)
+          boxed.delete(:expand)
+          return control if boxed.empty?
+
+          boxed[:expand] = true if styles[:expand]
+          container(content: control, **boxed)
+        end
+
+        def collapse_whitespace(text)
+          text.to_s.gsub(/\s+/, " ").strip
+        end
+      end
+    end
+  end
+end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/view_helpers.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/view_helpers.rb
new file mode 100644
index 00000000..ce20cb6d
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/view_helpers.rb
@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require "erb"
+require "json"
+
+module Ruflet
+  module Rails
+    module HtmlDsl
+      # ERB helpers for authoring HTML DSL screens in Ruby instead of raw
+      # tags. Auto-included into ActionView (see Railtie):
+      #
+      #   <%= column class: "p-6 gap-4 items-center" do %>
+      #     <%= text @count, class: "text-5xl font-bold" %>
+      #     <%= row class: "gap-3" do %>
+      #       <%= button "Up", variant: "filled", icon: "add",
+      #                  on_click: counter_increment_path %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # Helpers emit the same markup the tag DSL uses, so both styles mix
+      # freely in one template. Attribute keys are snake_case and become
+      # kebab-case (`on_click:` -> `on-click`); Hash/Array values serialize
+      # as JSON; `true` renders a bare attribute and nil/false are dropped.
+      module ViewHelpers
+        # --- layout -----------------------------------------------------------
+
+        def column(content = nil, **attrs, &block) = ruflet_dsl_tag("column", content, attrs, &block)
+        def row(content = nil, **attrs, &block) = ruflet_dsl_tag("row", content, attrs, &block)
+        def stack(content = nil, **attrs, &block) = ruflet_dsl_tag("stack", content, attrs, &block)
+        def container(content = nil, **attrs, &block) = ruflet_dsl_tag("container", content, attrs, &block)
+        def section(content = nil, **attrs, &block) = ruflet_dsl_tag("section", content, attrs, &block)
+        def card(content = nil, **attrs, &block) = ruflet_dsl_tag("card", content, attrs, &block)
+        def center(content = nil, **attrs, &block) = ruflet_dsl_tag("center", content, attrs, &block)
+        def list(content = nil, **attrs, &block) = ruflet_dsl_tag("list", content, attrs, &block)
+        def grid(content = nil, **attrs, &block) = ruflet_dsl_tag("grid", content, attrs, &block)
+        def spacer(**attrs) = ruflet_dsl_tag("spacer", nil, attrs)
+        def divider(**attrs) = ruflet_dsl_tag("divider", nil, attrs)
+
+        # --- content ----------------------------------------------------------
+
+        def text(value = nil, **attrs, &block) = ruflet_dsl_tag("text", value, attrs, &block)
+        def markdown(value = nil, **attrs, &block) = ruflet_dsl_tag("markdown", value, attrs, &block)
+        def icon(name, **attrs) = ruflet_dsl_tag("icon", nil, attrs.merge(name: name))
+        def image(src, **attrs) = ruflet_dsl_tag("img", nil, attrs.merge(src: src))
+
+        def heading(value = nil, level: 1, **attrs, &block)
+          ruflet_dsl_tag("h#{level.to_i.clamp(1, 6)}", value, attrs, &block)
+        end
+
+        (1..6).each do |level|
+          define_method("h#{level}") do |value = nil, **attrs, &block|
+            heading(value, level: level, **attrs, &block)
+          end
+        end
+
+        # --- interactive ------------------------------------------------------
+
+        # button "Up", on_click: "/counter/increment"       (POST + re-render)
+        # button "Open", href: "/settings"                  (push a screen)
+        # button "Remove", on_click: "delete:/items/3", variant: "outlined"
+        # button "Copy", service: "copy", text: "Hello"     (run a native service)
+        def button(label = nil, **attrs, &block) = ruflet_dsl_tag("button", label, attrs, &block)
+
+        # link "Settings", "/settings"
+        # link "Home", "/", nav: "root"
+        def link(label, href, **attrs, &block)
+          ruflet_dsl_tag("a", label, attrs.merge(href: href), &block)
+        end
+
+        # --- app chrome ---------------------------------------------------------
+
+        # appbar "Inbox", leading_icon: "menu" do
+        #   appbar_action "search", "/search"
+        # end
+        def appbar(title = nil, **attrs, &block)
+          ruflet_dsl_tag("appbar", nil, attrs.merge(title: title), &block)
+        end
+
+        def appbar_action(icon, href = nil, **attrs)
+          ruflet_dsl_tag("action", nil, attrs.merge(icon: icon, href: href))
+        end
+
+        # fab icon: "add", href: "/items/new"  (mounts as the screen's FAB)
+        def fab(label = nil, **attrs, &block)
+          ruflet_dsl_tag("fab", label, attrs, &block)
+        end
+
+        # bottom_nav do
+        #   nav_item icon: "chat", label: "Chats", href: "/chats", selected: true
+        #   nav_item icon: "call", label: "Calls", href: "/calls"
+        # end
+        def bottom_nav(**attrs, &block) = ruflet_dsl_tag("bottom-nav", nil, attrs, &block)
+        def nav_item(**attrs) = ruflet_dsl_tag("nav-item", nil, attrs)
+
+        # --- richer components --------------------------------------------------
+
+        def badge(label = nil, **attrs, &block)
+          ruflet_dsl_tag("badge", nil, attrs.merge(label: label), &block)
+        end
+
+        def tooltip(message, **attrs, &block)
+          ruflet_dsl_tag("tooltip", nil, attrs.merge(message: message), &block)
+        end
+
+        def avatar(content = nil, **attrs)
+          ruflet_dsl_tag("avatar", content, attrs)
+        end
+
+        def chip(label = nil, **attrs, &block)
+          ruflet_dsl_tag("chip", label, attrs, &block)
+        end
+
+        def progress(**attrs) = ruflet_dsl_tag("progress", nil, attrs)
+        def switch(**attrs) = ruflet_dsl_tag("switch", nil, attrs)
+        def checkbox(**attrs) = ruflet_dsl_tag("checkbox", nil, attrs)
+        def slider(**attrs) = ruflet_dsl_tag("slider", nil, attrs)
+        def radio(**attrs) = ruflet_dsl_tag("radio", nil, attrs)
+
+        # list_tile title: "Inbox", subtitle: "12 unread", leading: "mail", href: "/inbox"
+        def list_tile(**attrs, &block) = ruflet_dsl_tag("list-tile", nil, attrs, &block)
+
+        # expansion_tile title: "Details" do … end
+        def expansion_tile(title = nil, **attrs, &block)
+          ruflet_dsl_tag("expansion-tile", nil, attrs.merge(title: title), &block)
+        end
+
+        # radio_group "plan", value: "pro" do
+        #   radio value: "free", label: "Free"
+        #   radio value: "pro", label: "Pro"
+        # end
+        def radio_group(name = nil, **attrs, &block)
+          ruflet_dsl_tag("radio-group", nil, attrs.merge(name: name), &block)
+        end
+
+        # segmented_button "view", value: "list",
+        #   segments: [{ value: "list", label: "List", icon: "list" }, …]
+        def segmented_button(name = nil, segments: [], value: nil, **attrs)
+          rendered = Array(segments).map do |seg|
+            seg = { value: seg } unless seg.is_a?(Hash)
+            ruflet_dsl_tag("segment", seg[:label], { value: seg[:value], icon: seg[:icon] })
+          end.join
+          ruflet_dsl_tag("segmented-button", rendered, attrs.merge(name: name, value: value), raw: true)
+        end
+
+        # tabs do
+        #   tab "Overview" do … end
+        #   tab "Details", icon: "info" do … end
+        # end
+        def tabs(**attrs, &block) = ruflet_dsl_tag("tabs", nil, attrs, &block)
+
+        def tab(label = nil, **attrs, &block)
+          ruflet_dsl_tag("tab", nil, attrs.merge(label: label), &block)
+        end
+
+        # --- forms ----------------------------------------------------------------
+
+        def form(action:, method: "post", **attrs, &block)
+          ruflet_dsl_tag("form", nil, attrs.merge(action: action, method: method), &block)
+        end
+
+        def input(name = nil, **attrs)
+          ruflet_dsl_tag("input", nil, attrs.merge(name: name))
+        end
+
+        def textarea(name = nil, value = nil, **attrs)
+          ruflet_dsl_tag("textarea", value, attrs.merge(name: name))
+        end
+
+        def submit(label = "Submit", **attrs)
+          ruflet_dsl_tag("input", nil, attrs.merge(type: "submit", value: label))
+        end
+
+        # dropdown "locale", options: [["fr", "Français"], ["en", "English"]],
+        #          value: "en", label: "Language"
+        def dropdown(name = nil, options: [], value: nil, **attrs)
+          rendered = options.map do |option|
+            option_value, option_label = option.is_a?(Array) ? option : [option, option]
+            selected = !value.nil? && option_value.to_s == value.to_s
+            ruflet_dsl_tag("option", option_label, { value: option_value, selected: selected || nil })
+          end.join
+          ruflet_dsl_tag("select", rendered, attrs.merge(name: name), raw: true)
+        end
+
+        # --- services & extensions -----------------------------------------------
+
+        # Non-visual platform services. Drop one on a screen to make it available:
+        #   <%= geolocator %>        <%= battery %>        <%= connectivity %>
+        SERVICE_HELPERS = %w[
+          audio audio_recorder barometer battery clipboard connectivity
+          file_picker flashlight geolocator gyroscope accelerometer magnetometer
+          haptic_feedback permission_handler screen_brightness secure_storage
+          shake_detector share shared_preferences storage_paths url_launcher
+          user_accelerometer wakelock semantics_service
+        ].freeze
+
+        # Visible extension controls — they render inline like any other control.
+        # Use each control's real attributes (a wrong one renders a small inline
+        # placeholder instead of crashing the screen):
+        #   <%= lottie src: "loader.json" %>   <%= code_editor "puts 1", language: "ruby" %>
+        #   <%= video playlist: [{ resource: "clip.mp4" }] %>   <%= map %>
+        EXTENSION_HELPERS = %w[
+          video lottie code_editor map web_view color_picker camera
+          bar_chart line_chart pie_chart scatter_chart candlestick_chart radar_chart
+        ].freeze
+
+        # Named extension children used by Map and similar compound controls.
+        # These helpers allow Studio expressions such as marker_layer([...]) to
+        # be translated directly into nested ERB tags.
+        EXTENSION_CHILD_HELPERS = %w[
+          tile_layer marker_layer marker circle_layer circle_marker
+          polyline_layer polyline_marker polygon_layer polygon_marker
+          simple_attribution
+        ].freeze
+
+        # Chart data primitives. Nest them inside a chart to supply its data:
+        #   <%= bar_chart width: 320, height: 180 do %>
+        #     <%= bar_chart_group x: 0 do %>
+        #       <%= bar_chart_rod from_y: 0, to_y: 40, color: "#69db7c" %>
+        #     <% end %>
+        #   <% end %>
+        CHART_HELPERS = %w[
+          bar_chart_group bar_chart_rod bar_chart_rod_stack_item
+          line_chart_data line_chart_data_point pie_chart_section
+          candlestick_chart_spot scatter_chart_spot
+          radar_dataset radar_dataset_entry radar_chart_title
+          chart_axis chart_axis_label
+        ].freeze
+
+        (SERVICE_HELPERS + EXTENSION_HELPERS + EXTENSION_CHILD_HELPERS + CHART_HELPERS).each do |name|
+          tag = name.tr("_", "-")
+          define_method(name) do |content = nil, **attrs, &block|
+            ruflet_dsl_tag(tag, content, attrs, &block)
+          end
+        end
+
+        # Rive takes its animation URL as `src`, like `image` — the auto-generated
+        # helper would put the URL in the element body (text content) instead, so
+        # the animation never loads. Give it a dedicated helper.
+        #   <%= rive "https://cdn.rive.app/animations/vehicles.riv", fit: "contain" %>
+        def rive(src = nil, **attrs, &block)
+          ruflet_dsl_tag("rive", nil, attrs.merge(src: src), &block)
+        end
+
+        # Preserve Ruflet Studio's public API in ERB:
+        #   <%= spinkit wave: { color: "#74c0fc", size: 48 } %>
+        # The native control receives normalized variant/color/size props.
+        def spinkit(**variants)
+          allowed = Ruflet::UI::MaterialControlMethods::SPINKIT_VARIANTS
+          selected = variants.select { |name, _value| allowed.include?(name.to_sym) }
+          raise ArgumentError, "spinkit requires exactly one variant" unless selected.length == 1 && selected.length == variants.length
+
+          variant, options = selected.first
+          raise ArgumentError, "spinkit variant options must be a Hash" unless options.is_a?(Hash)
+
+          ruflet_dsl_tag("spinkit", nil, options.merge(variant: variant.to_s))
+        end
+
+        # --- anything in the control registry ------------------------------------
+
+        # widget "progress-bar", value: 0.4
+        # widget "switch", label: "Dark mode", on_change: "/theme/toggle"
+        def widget(tag_name, content = nil, **attrs, &block)
+          ruflet_dsl_tag(tag_name.to_s.tr("_", "-"), content, attrs, &block)
+        end
+
+        private
+
+        def ruflet_dsl_tag(tag_name, content, attrs, raw: false, &block)
+          inner = raw ? content : ruflet_dsl_content(content, &block)
+          markup = +"<#{tag_name}"
+          attrs.each do |key, value|
+            next if value.nil? || value == false
+
+            name = key.to_s.tr("_", "-")
+            if value == true
+              markup << " #{name}"
+            else
+              value = JSON.generate(value) if value.is_a?(Hash) || value.is_a?(Array)
+              markup << %( #{name}="#{ERB::Util.html_escape(value)}")
+            end
+          end
+          markup << ">"
+          markup << inner.to_s
+          markup << "</#{tag_name}>"
+          ruflet_dsl_safe(markup)
+        end
+
+        def ruflet_dsl_content(content, &block)
+          if block
+            respond_to?(:capture) ? capture(&block) : block.call
+          elsif content.respond_to?(:html_safe?) && content.html_safe?
+            content
+          elsif content.nil?
+            nil
+          else
+            ERB::Util.html_escape(content.to_s)
+          end
+        end
+
+        def ruflet_dsl_safe(string)
+          string.respond_to?(:html_safe) ? string.html_safe : string
+        end
+      end
+    end
+  end
+end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/install_support.rb b/packages/ruflet_rails/lib/ruflet/rails/install_support.rb
index 0194fad4..2e0681a3 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/install_support.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/install_support.rb
@@ -13,7 +13,7 @@ def default_app_template(app_title:)
 
           # The home screen for this Ruflet app. You own this file; nothing is
           # auto-discovered. It is mounted explicitly in config/routes.rb:
-          #   match "/ws", to: Ruflet::Rails.app(Rails.root.join("app/views/ruflet/main.rb")), via: :all
+          #   match "/ws", to: Ruflet::Rails.native(Rails.root.join("app/views/ruflet/main.rb")), via: :all
           Ruflet.run do |page|
             page.title = #{app_title.inspect}
             page.add(
@@ -124,14 +124,9 @@ def normalize_build_platform(platform)
         value
       end
 
-      # ruflet_rails builds only native clients. The web client is installed
-      # prebuilt (rake ruflet:web), never compiled, so "web" is not a build
-      # target here.
-      def build_args_for_platform(platform, ruflet_url: nil)
+      def build_args_for_platform(platform)
         normalized = normalize_build_platform(platform)
         return [] if normalized.to_s.empty?
-        return [] if normalized == "web"
-
         [normalized]
       end
 
@@ -139,15 +134,11 @@ def default_entrypoint_path
         File.join("app", "views", "ruflet", "main.rb")
       end
 
-      def route_snippet(entrypoint: default_entrypoint_path, mount_path: "/ws", helper: "app")
+      def route_snippet(entrypoint: default_entrypoint_path, mount_path: "/ws", helper: "native")
         %(match "#{mount_path}", to: Ruflet::Rails.#{helper}(Rails.root.join("#{entrypoint}")), via: :all)
       end
 
-      def web_route_snippet(entrypoint: default_entrypoint_path, mount_path: "/ruflet")
-        %(mount Ruflet::Rails.web_app(app_file: Rails.root.join("#{entrypoint}")), at: "#{mount_path}")
-      end
-
-      def install_next_steps(target:, entrypoint:, client:, mount_path: "/ws")
+      def install_next_steps(entrypoint:, client:, mount_path: "/ws")
         lines = [
           "Ruflet Rails installed.",
           "Generated entrypoint: #{entrypoint}",
@@ -167,13 +158,6 @@ def install_next_steps(target:, entrypoint:, client:, mount_path: "/ws")
           ]
         end
 
-        if %w[web all].include?(client.to_s)
-          lines += [
-            "Web client installed into frontend/.",
-            "Open the mounted Ruflet web app at http://localhost:3000/ruflet"
-          ]
-        end
-
         lines
       end
     end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/native_app.rb b/packages/ruflet_rails/lib/ruflet/rails/native_app.rb
index b9346f04..f39a01ff 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/native_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/native_app.rb
@@ -49,8 +49,10 @@ module Ruflet
   module Rails
     module_function
 
-    # Start a managed webview app. See NativeApp.
-    def native_app(page, **opts)
+    # Wrap your Rails web pages in a native shell: the body stays a WebView
+    # while Ruflet owns the native chrome (app bar, drawer, navigation, sheets,
+    # dialogs, services). See NativeApp.
+    def native_shell(page, **opts)
       NativeApp.new(page, **opts).start
     end
   end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/native_screens.rb b/packages/ruflet_rails/lib/ruflet/rails/native_screens.rb
new file mode 100644
index 00000000..7b39472b
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/native_screens.rb
@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Ruflet
+  module Rails
+    # Screens without route declarations.
+    #
+    # A native app has one public route, the WebSocket. The screens behind it
+    # are not endpoints anybody dials — they are reached only from inside a
+    # session — so declaring a Rails route per screen adds a routing table that
+    # nothing outside the app is allowed to use. This resolves a screen path to
+    # a controller action by convention instead:
+    #
+    #   /native                    -> NativeController#home   (or #index)
+    #   /native/counter            -> NativeController#counter
+    #   /native/counter/increment  -> NativeController#counter_increment
+    #   /native/device_feature/camera -> NativeController#device_feature, params[:id]
+    #
+    # The last two show the rule for extra segments: they are first tried as
+    # part of the action name, and otherwise become positional params. That is
+    # what lets one convention cover both an action that happens to live under
+    # another ("counter/increment") and a parameterised screen ("device/:id"),
+    # which is the pair a per-screen routing table normally exists to express.
+    module NativeScreens
+      # Actions to try for the root of a feature folder, in order.
+      INDEX_ACTIONS = %w[home index show].freeze
+
+      module_function
+
+      # "/native/counter/increment" -> ["native", ["counter", "increment"]]
+      def split_path(path)
+        segments = path.to_s.split("/").reject(&:empty?)
+        [segments.first, segments[1..] || []]
+      end
+
+      def controller_for(scope)
+        return nil if scope.to_s.empty?
+
+        name = "#{camelize(scope)}Controller"
+        klass = constantize(name)
+        klass if klass.respond_to?(:action)
+      end
+
+      # Longest action name first, so "counter/increment" prefers
+      # #counter_increment over #counter with a stray param.
+      def resolve(path)
+        scope, rest = split_path(path)
+        controller = controller_for(scope)
+        return nil unless controller
+
+        rest.length.downto(1) do |take|
+          action = rest.first(take).join("_")
+          next unless action_on?(controller, action)
+
+          return { controller: controller, action: action, params: rest.drop(take) }
+        end
+
+        return index_screen(controller) if rest.empty?
+
+        # No action matched the segments, so treat the first as the action and
+        # the rest as its params: /native/device/camera -> #device, id "camera".
+        action = rest.first
+        return nil unless action_on?(controller, action)
+
+        { controller: controller, action: action, params: rest.drop(1) }
+      end
+
+      def index_screen(controller)
+        action = INDEX_ACTIONS.find { |candidate| action_on?(controller, candidate) }
+        return nil unless action
+
+        { controller: controller, action: action, params: [] }
+      end
+
+      def action_on?(controller, action)
+        return false if action.to_s.empty?
+        return false unless controller.respond_to?(:action_methods)
+
+        controller.action_methods.include?(action.to_s)
+      end
+
+      def camelize(value)
+        value.to_s.split(/[_\-]/).map { |part| part.sub(/\A./, &:upcase) }.join
+      end
+
+      def constantize(name)
+        Object.const_get(name)
+      rescue NameError
+        nil
+      end
+    end
+  end
+end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/protocol.rb b/packages/ruflet_rails/lib/ruflet/rails/protocol.rb
index 59914efc..6abbb5a1 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/protocol.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/protocol.rb
@@ -6,4 +6,3 @@
 require_relative "protocol/endpoint"
 require_relative "protocol/mobile_loader"
 require_relative "protocol/runner"
-require_relative "protocol/web_app"
diff --git a/packages/ruflet_rails/lib/ruflet/rails/protocol/web_app.rb b/packages/ruflet_rails/lib/ruflet/rails/protocol/web_app.rb
deleted file mode 100644
index c30009de..00000000
--- a/packages/ruflet_rails/lib/ruflet/rails/protocol/web_app.rb
+++ /dev/null
@@ -1,243 +0,0 @@
-# frozen_string_literal: true
-
-module Ruflet
-  module Rails
-    module Protocol
-      # Self-contained Rack application for a Ruflet web frontend: serves the
-      # built Flutter web client AND speaks the Ruflet WebSocket protocol on
-      # the same mount point, so it mounts like any Rack app:
-      #
-      #   # config/routes.rb
-      #   mount Ruflet::Rails.web_app(app_file: Rails.root.join("app/views/ruflet/main.rb")), at: "/myfrontend"
-      #
-      #   # or with an explicit entrypoint and build directory:
-      #   mount Ruflet::Rails.web_app(build_dir: Rails.root.join("frontend")) { |page|
-      #     CounterView.render(page)
-      #   }, at: "/myfrontend"
-      #
-      # How it stays mount-point independent: the Flutter web client derives
-      # both its asset URLs and its WebSocket URL from `Uri.base`, which comes
-      # from index.html's <base href>. This app rewrites <base href> to the
-      # actual mount point on the fly, so the same build works under any
-      # route — the client then connects its WebSocket back to the mount
-      # point, where the upgrade is answered via Rack hijack by the shared
-      # Ruflet::ConnectionProtocol engine running on the Rails server itself.
-      class WebApp
-        include WebSocketDetection
-
-        CONTENT_TYPES = {
-          ".html" => "text/html; charset=utf-8",
-          ".js" => "application/javascript",
-          ".mjs" => "application/javascript",
-          ".css" => "text/css",
-          ".json" => "application/json",
-          ".wasm" => "application/wasm",
-          ".png" => "image/png",
-          ".jpg" => "image/jpeg",
-          ".jpeg" => "image/jpeg",
-          ".gif" => "image/gif",
-          ".webp" => "image/webp",
-          ".svg" => "image/svg+xml",
-          ".ico" => "image/x-icon",
-          ".otf" => "font/otf",
-          ".ttf" => "font/ttf",
-          ".woff" => "font/woff",
-          ".woff2" => "font/woff2",
-          ".map" => "application/json",
-          ".txt" => "text/plain"
-        }.freeze
-
-        def initialize(build_dir: nil, entrypoint: nil, &app_block)
-          @explicit_build_dir = build_dir
-          @entrypoint_option = entrypoint
-          @app_block = app_block
-          @endpoint = nil
-          @endpoint_mutex = Mutex.new
-        end
-
-        def call(env)
-          return websocket_endpoint.call(env) if websocket_upgrade?(env)
-
-          path = env["PATH_INFO"].to_s
-          return serve_index(env) if ["", "/", "/index.html"].include?(path)
-
-          serve_static(path)
-        end
-
-        private
-
-        def websocket_endpoint
-          @endpoint_mutex.synchronize do
-            @endpoint ||= Runner.new(&entrypoint).build_endpoint
-          end
-        end
-
-        def entrypoint
-          @entrypoint_option || @app_block ||
-            raise(ArgumentError, "web_app requires one of app_file: or a block")
-        end
-
-        # The web build must NOT live under public/, or Rails' static
-        # middleware would serve it directly (e.g. /app/index.html) and bypass
-        # the mount — making it reachable at a path no route declares. The
-        # default is Rails.root/frontend, exactly where `rake ruflet:web`
-        # installs the prebuilt web client, which Rails never serves statically.
-        # An explicit build_dir: under public/ is rejected.
-        def build_dir
-          dir = resolve_build_dir
-          reject_public_build_dir!(dir)
-          dir
-        end
-
-        def resolve_build_dir
-          explicit = @explicit_build_dir.to_s
-          return explicit unless explicit.empty?
-
-          return ::Rails.root.join("frontend").to_s if defined?(::Rails.root) && ::Rails.root
-
-          ""
-        end
-
-        def reject_public_build_dir!(dir)
-          return if dir.to_s.empty?
-          return unless defined?(::Rails.root) && ::Rails.root
-
-          public_root = File.expand_path(::Rails.public_path.to_s)
-          full = File.expand_path(dir.to_s)
-          return unless full == public_root || full.start_with?(public_root + File::SEPARATOR)
-
-          raise ArgumentError,
-                "Ruflet web build dir (#{dir}) is under public/, which Rails serves " \
-                "statically and would expose the app outside its mount. Use a " \
-                "non-public directory such as #{::Rails.root.join('frontend')}."
-        end
-
-        def serve_index(env)
-          index_path = File.join(build_dir, "index.html")
-          unless File.file?(index_path)
-            return [404, { "content-type" => "text/plain" },
-                    ["Ruflet web client not found at #{index_path}. Run `rake ruflet:web`."]]
-          end
-
-          html = rewrite_base_href(File.read(index_path), mount_base(env))
-          html = inject_mount_websocket(html)
-          html = inject_service_worker_cleanup(html)
-          [200,
-           { "content-type" => "text/html; charset=utf-8",
-             "cache-control" => "no-cache",
-             "content-length" => html.bytesize.to_s },
-           [html]]
-        end
-
-        def inject_mount_websocket(html)
-          return html if html.include?("window.flet.webSocketEndpoint")
-
-          html.sub(%r{(<base\s+href="[^"]*"\s*/?>)}) { "#{::Regexp.last_match(1)}\n#{mount_websocket_bootstrap}" }
-        end
-
-        # Mounted Rails apps are server-driven and must always load the client
-        # shipped by the Rails app. Remove service workers previously installed
-        # for this mount so they cannot keep serving a stale connection client.
-        def inject_service_worker_cleanup(html)
-          return html if html.include?("ruflet-rails-service-worker-cleanup")
-
-          script = <<~HTML
-            <script id="ruflet-rails-service-worker-cleanup">
-              if ("serviceWorker" in navigator) {
-                navigator.serviceWorker.getRegistrations().then(function (registrations) {
-                  registrations.forEach(function (registration) {
-                    if (registration.scope.indexOf(document.baseURI) === 0) registration.unregister();
-                  });
-                });
-              }
-            </script>
-          HTML
-          html.include?("</head>") ? html.sub("</head>", "#{script}</head>") : "#{script}#{html}"
-        end
-
-        # Pins Ruflet clients to <mount>/ws (derived from the rewritten
-        # <base href>) instead of the origin's /ws. The Ruflet client itself
-        # uses the mounted page URL, so Rails needs no separate backend URL.
-        def mount_websocket_bootstrap
-          <<~HTML
-            <script>
-              (function () {
-                window.flet = window.flet || {};
-                if (!window.flet.webSocketEndpoint) {
-                  var basePath = new URL(document.baseURI).pathname;
-                  window.flet.webSocketEndpoint = (basePath + "ws").replace(/^\\/+/, "");
-                }
-              })();
-            </script>
-          HTML
-        end
-
-        # <base href> drives the Flutter client's asset and WebSocket URLs;
-        # pin it to the actual mount point so one build serves any route.
-        def rewrite_base_href(html, base)
-          if html =~ %r{<base\s+href="[^"]*"\s*/?>}
-            html.sub(%r{<base\s+href="[^"]*"\s*/?>}, "<base href=\"#{base}\">")
-          else
-            html.sub(/<head>/i, "<head>\n  <base href=\"#{base}\">")
-          end
-        end
-
-        def mount_base(env)
-          script = env["SCRIPT_NAME"].to_s
-          return "/" if script.empty? || script == "/"
-
-          script.end_with?("/") ? script : "#{script}/"
-        end
-
-        def serve_static(path)
-          return retire_service_worker if path == "/flutter_service_worker.js"
-
-          root = File.expand_path(build_dir)
-          full = File.expand_path(File.join(root, path))
-          unless full.start_with?(root + File::SEPARATOR) && File.file?(full)
-            return [404, { "content-type" => "text/plain" }, ["Not Found"]]
-          end
-
-          body = File.binread(full)
-          body = disable_service_worker(body) if path == "/flutter_bootstrap.js"
-          [200,
-           { "content-type" => content_type_for(full),
-             "cache-control" => "no-cache",
-             "content-length" => body.bytesize.to_s },
-           [body]]
-        end
-
-        def disable_service_worker(body)
-          body.sub(
-            /serviceWorkerSettings:\s*\{\s*serviceWorkerVersion:\s*[^}]+\}\s*,?/m,
-            ""
-          )
-        end
-
-        def retire_service_worker
-          body = <<~JS
-            self.addEventListener("install", function () { self.skipWaiting(); });
-            self.addEventListener("activate", function (event) {
-              event.waitUntil((async function () {
-                await self.registration.unregister();
-                for (const key of await caches.keys()) await caches.delete(key);
-                for (const client of await self.clients.matchAll({ type: "window" })) {
-                  client.navigate(client.url);
-                }
-              })());
-            });
-          JS
-          [200,
-           { "content-type" => "application/javascript",
-             "cache-control" => "no-store",
-             "content-length" => body.bytesize.to_s },
-           [body]]
-        end
-
-        def content_type_for(path)
-          CONTENT_TYPES.fetch(File.extname(path).downcase, "application/octet-stream")
-        end
-      end
-    end
-  end
-end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/protocol/web_socket_connection.rb b/packages/ruflet_rails/lib/ruflet/rails/protocol/web_socket_connection.rb
deleted file mode 100644
index dc32eb54..00000000
--- a/packages/ruflet_rails/lib/ruflet/rails/protocol/web_socket_connection.rb
+++ /dev/null
@@ -1,126 +0,0 @@
-# frozen_string_literal: true
-
-module Ruflet
-  module Rails
-    module Protocol
-      class WebSocketConnection
-        def initialize(socket)
-          @socket = socket
-          @write_mutex = Mutex.new
-        end
-
-        def session_key
-          @socket.object_id
-        end
-
-        def closed?
-          @socket.closed?
-        rescue IOError
-          true
-        end
-
-        def send_binary(payload)
-          send_frame(0x2, payload.to_s.b)
-        end
-
-        def read_message
-          frame = read_frame
-          return nil if frame.nil?
-
-          opcode = frame[:opcode]
-          payload = frame[:payload]
-
-          case opcode
-          when 0x8
-            close
-            nil
-          when 0x9
-            send_frame(0xA, payload)
-            read_message
-          when 0xA
-            read_message
-          when 0x1, 0x2
-            payload
-          else
-            read_message
-          end
-        end
-
-        def close
-          return if closed?
-
-          @socket.close
-        rescue IOError
-          nil
-        end
-
-        private
-
-        def read_frame
-          header = read_exact(2)
-          return nil if header.nil?
-
-          b1 = header.getbyte(0)
-          b2 = header.getbyte(1)
-
-          masked = (b2 & 0x80) != 0
-          payload_len = b2 & 0x7f
-
-          payload_len = read_exact(2).unpack1("n") if payload_len == 126
-          payload_len = read_exact(8).unpack1("Q>") if payload_len == 127
-
-          masking_key = masked ? read_exact(4) : nil
-          payload = payload_len.zero? ? "".b : read_exact(payload_len)
-          return nil if payload.nil?
-
-          payload = unmask(payload, masking_key) if masked
-
-          { opcode: b1 & 0x0f, payload: payload }
-        end
-
-        def send_frame(opcode, payload)
-          bytes = payload.to_s.b
-          len = bytes.bytesize
-          header = [0x80 | (opcode & 0x0f)].pack("C")
-
-          header <<
-            if len <= 125
-              [len].pack("C")
-            elsif len <= 0xffff
-              [126].pack("C") + [len].pack("n")
-            else
-              [127].pack("C") + [len].pack("Q>")
-            end
-
-          @write_mutex.synchronize do
-            @socket.write(header)
-            @socket.write(bytes) unless bytes.empty?
-          end
-        end
-
-        def unmask(payload, mask)
-          out = +""
-          out.force_encoding(Encoding::BINARY)
-          payload.bytes.each_with_index do |byte, idx|
-            out << (byte ^ mask.getbyte(idx % 4))
-          end
-          out
-        end
-
-        def read_exact(length)
-          chunk = +""
-          chunk.force_encoding(Encoding::BINARY)
-
-          while chunk.bytesize < length
-            part = @socket.read(length - chunk.bytesize)
-            return nil if part.nil? || part.empty?
-
-            chunk << part
-          end
-
-          chunk
-        end
-      end
-    end
-  end
-end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/protocol/wire_codec.rb b/packages/ruflet_rails/lib/ruflet/rails/protocol/wire_codec.rb
deleted file mode 100644
index 49b260ee..00000000
--- a/packages/ruflet_rails/lib/ruflet/rails/protocol/wire_codec.rb
+++ /dev/null
@@ -1,268 +0,0 @@
-# frozen_string_literal: true
-
-module Ruflet
-  module Rails
-    module Protocol
-      class WireCodec
-        class << self
-          def pack(value)
-            case value
-            when ::Ruflet::Protocol::DateTimeValue
-              pack_extension(1, value)
-            when ::Ruflet::Protocol::TimeOfDayValue
-              pack_extension(2, value)
-            when ::Ruflet::Protocol::DurationValue
-              pack_extension(3, value)
-            when NilClass
-              "\xc0".b
-            when TrueClass
-              "\xc3".b
-            when FalseClass
-              "\xc2".b
-            when Integer
-              pack_integer(value)
-            when Float
-              "\xcb".b + [value].pack("G")
-            when String
-              binary_string?(value) ? pack_binary(value) : pack_string(value)
-            when Symbol
-              pack_string(value.to_s)
-            when Array
-              pack_array(value)
-            when Hash
-              pack_map(value)
-            else
-              pack_string(value.to_s)
-            end
-          end
-
-          def unpack(bytes)
-            reader = ByteReader.new(bytes)
-            read_value(reader)
-          end
-
-          private
-
-          def pack_extension(type, value)
-            bytes = value.to_s.b
-            length = bytes.bytesize
-            header =
-              if length <= 0xff
-                "\xc7".b + [length].pack("C")
-              elsif length <= 0xffff
-                "\xc8".b + [length].pack("n")
-              else
-                "\xc9".b + [length].pack("N")
-              end
-            header + [type].pack("c") + bytes
-          end
-
-          def pack_integer(value)
-            if value >= 0
-              return [value].pack("C") if value <= 0x7f
-              return "\xcc".b + [value].pack("C") if value <= 0xff
-              return "\xcd".b + [value].pack("n") if value <= 0xffff
-              return "\xce".b + [value].pack("N") if value <= 0xffff_ffff
-
-              "\xcf".b + [value].pack("Q>")
-            else
-              return [value & 0xff].pack("C") if value >= -32
-              return "\xd0".b + [value].pack("c") if value >= -128
-              return "\xd1".b + [value].pack("s>") if value >= -32_768
-              return "\xd2".b + [value].pack("l>") if value >= -2_147_483_648
-
-              "\xd3".b + [value].pack("q>")
-            end
-          end
-
-          def pack_string(value)
-            str = value.to_s.dup.force_encoding("UTF-8")
-            bytes = str.b
-            len = bytes.bytesize
-
-            if len <= 31
-              [0xA0 | len].pack("C") + bytes
-            elsif len <= 0xff
-              "\xd9".b + [len].pack("C") + bytes
-            elsif len <= 0xffff
-              "\xda".b + [len].pack("n") + bytes
-            else
-              "\xdb".b + [len].pack("N") + bytes
-            end
-          end
-
-          def pack_binary(value)
-            bytes = value.to_s.b
-            len = bytes.bytesize
-
-            if len <= 0xff
-              "\xc4".b + [len].pack("C") + bytes
-            elsif len <= 0xffff
-              "\xc5".b + [len].pack("n") + bytes
-            else
-              "\xc6".b + [len].pack("N") + bytes
-            end
-          end
-
-          def binary_string?(value)
-            value.encoding == Encoding::BINARY || !value.valid_encoding?
-          end
-
-          def pack_array(value)
-            len = value.length
-            head =
-              if len <= 15
-                [0x90 | len].pack("C")
-              elsif len <= 0xffff
-                "\xdc".b + [len].pack("n")
-              else
-                "\xdd".b + [len].pack("N")
-              end
-
-            body = +"".b
-            value.each { |item| body << pack(item) }
-            head + body
-          end
-
-          def pack_map(value)
-            pairs = value.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
-            len = pairs.length
-            head =
-              if len <= 15
-                [0x80 | len].pack("C")
-              elsif len <= 0xffff
-                "\xde".b + [len].pack("n")
-              else
-                "\xdf".b + [len].pack("N")
-              end
-
-            body = +"".b
-            pairs.each do |k, v|
-              body << pack(k)
-              body << pack(v)
-            end
-            head + body
-          end
-
-          def read_value(reader)
-            marker = reader.read_u8
-
-            return marker if marker <= 0x7f
-            return marker - 256 if marker >= 0xe0
-
-            case marker
-            when 0xc0 then nil
-            when 0xc2 then false
-            when 0xc3 then true
-            when 0xcc then reader.read_u8
-            when 0xcd then reader.read_u16
-            when 0xce then reader.read_u32
-            when 0xcf then reader.read_u64
-            when 0xd0 then reader.read_i8
-            when 0xd1 then reader.read_i16
-            when 0xd2 then reader.read_i32
-            when 0xd3 then reader.read_i64
-            when 0xca then reader.read_f32
-            when 0xcb then reader.read_f64
-            when 0xd9 then reader.read_string(reader.read_u8)
-            when 0xda then reader.read_string(reader.read_u16)
-            when 0xdb then reader.read_string(reader.read_u32)
-            when 0xc4 then reader.read_binary(reader.read_u8)
-            when 0xc5 then reader.read_binary(reader.read_u16)
-            when 0xc6 then reader.read_binary(reader.read_u32)
-            when 0xdc then read_array(reader, reader.read_u16)
-            when 0xdd then read_array(reader, reader.read_u32)
-            when 0xde then read_map(reader, reader.read_u16)
-            when 0xdf then read_map(reader, reader.read_u32)
-            when 0xd4
-              read_ext(reader, 1)
-            when 0xd5
-              read_ext(reader, 2)
-            when 0xd6
-              read_ext(reader, 4)
-            when 0xd7
-              read_ext(reader, 8)
-            when 0xd8
-              read_ext(reader, 16)
-            when 0xc7
-              read_ext(reader, reader.read_u8)
-            when 0xc8
-              read_ext(reader, reader.read_u16)
-            when 0xc9
-              read_ext(reader, reader.read_u32)
-            else
-              if (marker & 0xf0) == 0x90
-                read_array(reader, marker & 0x0f)
-              elsif (marker & 0xf0) == 0x80
-                read_map(reader, marker & 0x0f)
-              elsif (marker & 0xe0) == 0xa0
-                reader.read_string(marker & 0x1f)
-              else
-                raise "Unsupported MessagePack marker: 0x#{marker.to_s(16)}"
-              end
-            end
-          end
-
-          def read_array(reader, size)
-            Array.new(size) { read_value(reader) }
-          end
-
-          def read_map(reader, size)
-            out = {}
-            size.times do
-              key = read_value(reader)
-              out[key.to_s] = read_value(reader)
-            end
-            out
-          end
-
-          def read_ext(reader, size)
-            type = reader.read_i8
-            value = reader.read_exact(size).force_encoding("UTF-8")
-            case type
-            when 1 then ::Ruflet::Protocol.date_time(value)
-            when 2 then ::Ruflet::Protocol.time_of_day(value)
-            when 3 then ::Ruflet::Protocol.duration(value)
-            else value
-            end
-          end
-        end
-
-        class ByteReader
-          def initialize(bytes)
-            @data = bytes.to_s.b
-            @offset = 0
-          end
-
-          def read_u8
-            value = @data.getbyte(@offset)
-            raise "Unexpected EOF" if value.nil?
-
-            @offset += 1
-            value
-          end
-
-          def read_exact(size)
-            chunk = @data.byteslice(@offset, size)
-            raise "Unexpected EOF" if chunk.nil? || chunk.bytesize != size
-
-            @offset += size
-            chunk
-          end
-
-          def read_u16 = read_exact(2).unpack1("n")
-          def read_u32 = read_exact(4).unpack1("N")
-          def read_u64 = read_exact(8).unpack1("Q>")
-          def read_i8 = read_exact(1).unpack1("c")
-          def read_i16 = read_exact(2).unpack1("s>")
-          def read_i32 = read_exact(4).unpack1("l>")
-          def read_i64 = read_exact(8).unpack1("q>")
-          def read_f32 = read_exact(4).unpack1("g")
-          def read_f64 = read_exact(8).unpack1("G")
-          def read_string(size) = read_exact(size).force_encoding("UTF-8")
-          def read_binary(size) = read_exact(size)
-        end
-      end
-    end
-  end
-end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/railtie.rb b/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
index ef5ac37c..ebafbf8d 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
@@ -3,10 +3,11 @@
 module Ruflet
   module Rails
     class Railtie < ::Rails::Railtie
-      # Make ruflet_frame and friends available in every .erb template.
+      # Make the native view helpers available in every .erb template.
       initializer "ruflet_rails.view_helpers" do
         ActiveSupport.on_load(:action_view) do
           include Ruflet::Rails::ViewHelpers
+          include Ruflet::Rails::HtmlDsl::ViewHelpers
         end
       end
 
@@ -25,14 +26,8 @@ class Railtie < ::Rails::Railtie
           task :build, [:platform] do |_task, args|
             platform = args[:platform].to_s.strip.downcase
 
-            if platform == "web"
-              warn "ruflet_rails does not build the web client. Install the prebuilt web client with: rake ruflet:web"
-              next
-            end
-
-            cfg        = Ruflet::Rails.config
-            ruflet_url = cfg.backend_url.to_s.strip
-            build_args = Ruflet::Rails::InstallSupport.build_args_for_platform(platform, ruflet_url: ruflet_url)
+            cfg = Ruflet::Rails.config
+            build_args = Ruflet::Rails::InstallSupport.build_args_for_platform(platform)
 
             if build_args.empty?
               warn "Usage: rake ruflet:build[apk|android|ios|aab|desktop|macos|windows|linux]"
@@ -65,12 +60,6 @@ class Railtie < ::Rails::Railtie
             raise SystemExit, exit_code unless exit_code.to_i.zero?
           end
 
-          desc "Install the prebuilt Ruflet web client into frontend/. Usage: rake ruflet:web"
-          task :web do
-            ok = Ruflet::Rails::WebInstaller.install!(root: ::Rails.root)
-            raise SystemExit, 1 unless ok
-          end
-
           desc "Download/update prebuilt Ruflet clients from GitHub releases. Usage: rake ruflet:update[target]"
           task :update, [:target] do |_task, args|
             target = args[:target].to_s.strip
@@ -101,24 +90,6 @@ class Railtie < ::Rails::Railtie
         end
       end
 
-      rake_tasks do
-        namespace :ruflet do
-          desc "Build Ruflet client for this Rails app. Usage: rake ruflet:build[web]"
-          task :build, [:platform] do |_task, args|
-            platform = args[:platform].to_s.strip
-            if platform.empty?
-              warn "Usage: rake ruflet:build[apk|android|ios|aab|web|macos|windows|linux]"
-              next
-            end
-
-            require "ruflet/cli"
-            exit_code = Dir.chdir(::Rails.root) do
-              Ruflet::CLI.command_build([platform])
-            end
-            raise SystemExit, exit_code unless exit_code.to_i.zero?
-          end
-        end
-      end
     end
   end
 end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb b/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
index 586cc211..6fcb44a3 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
@@ -5,51 +5,16 @@
 
 module Ruflet
   module Rails
-    # ERB view helpers for dropping a Ruflet native UI into a server-rendered
-    # Rails page. Auto-included into ActionView (see Railtie), so they are
-    # available in any .erb template.
-    #
-    # A Ruflet web frontend is a Flutter app mounted at a route (see
-    # Ruflet::Rails.web_app in config/routes.rb). To embed that native UI inside
-    # an HTML page, render it in an isolated frame pointed at the mount:
-    #
-    #   <%= ruflet_frame "/products", height: 640 %>
-    #   <%= ruflet_frame "/showcase", height: "80vh", width: "100%" %>
-    #
-    # The frame is same-origin by default (a relative path), so the Ruflet
-    # WebSocket and assets resolve against this host with no extra config. Pass a
-    # full URL to embed a Ruflet app on another host.
+    # Annotations for Ruflet::Rails.native_shell, where the body of a screen
+    # stays a Rails page in a WebView and Ruflet owns the native chrome around
+    # it. Auto-included into ActionView (see Railtie), so they are available in
+    # any .erb template.
     module ViewHelpers
-      # Embed a mounted Ruflet route as an isolated, responsive frame.
-      #
-      # path    - the Ruflet mount route ("/products") or a full URL.
-      # height  - CSS height; a number is treated as pixels (default 600).
-      # width   - CSS width; a number is treated as pixels (default "100%").
-      # title   - iframe title for accessibility (default "Ruflet").
-      # style   - extra CSS appended to the frame's inline style.
-      # attrs   - any other iframe attributes (underscores become dashes).
-      def ruflet_frame(path, height: 600, width: "100%", title: "Ruflet", style: nil, **attrs)
-        base_style = "border:0;width:#{ruflet_css_dimension(width)};height:#{ruflet_css_dimension(height)};"
-
-        attributes = {
-          "src" => path.to_s,
-          "title" => title.to_s,
-          "loading" => "lazy",
-          "style" => [base_style, style].compact.join(" ").strip
-        }
-        attrs.each { |key, value| attributes[key.to_s.tr("_", "-")] = value }
-
-        markup = +"<iframe"
-        attributes.each { |key, value| markup << %( #{key}="#{ERB::Util.html_escape(value)}") }
-        markup << "></iframe>"
-        ruflet_html_safe(markup)
-      end
-
       # --- Native annotations ------------------------------------------------
       #
       # These emit plain HTML decorated with `ruflet-*` attributes. In a normal
       # browser they render and behave as ordinary HTML; inside the Ruflet
-      # native shell (Ruflet::Rails.native_app) the HTML adapter reads the
+      # native shell (Ruflet::Rails.native_shell) the HTML adapter reads the
       # attributes and drives native navigation/chrome instead. They degrade
       # gracefully — no JavaScript required for the web rendering.
 
@@ -160,7 +125,7 @@ def ruflet_rail_item(label, href, icon:, selected: false, nav: nil, payload: {},
       end
 
       # Native platform services from ERB. These are normal HTML elements in a
-      # browser and native service calls inside Ruflet::Rails.native_app.
+      # browser and native service calls inside Ruflet::Rails.native_shell.
       def ruflet_share_link(label, href = "#", text: nil, title: nil, subject: nil, url: nil, files: nil, **attrs)
         payload = ruflet_compact_hash(component: "share", text: text, title: title, subject: subject,
                                       url: url || href, files: files)
@@ -213,7 +178,6 @@ def ruflet_build_tag(name, content, attributes)
       end
 
       # Turn extra helper kwargs (data_role:) into dashed attribute keys
-      # (data-role), mirroring ruflet_frame.
       def ruflet_dash_attrs(attrs)
         attrs.each_with_object({}) do |(key, value), out|
           if value.is_a?(Hash)
@@ -251,9 +215,6 @@ def ruflet_json(value)
         JSON.generate(value)
       end
 
-      def ruflet_css_dimension(value)
-        value.is_a?(Numeric) ? "#{value}px" : value.to_s
-      end
 
       def ruflet_html_safe(string)
         string.respond_to?(:html_safe) ? string.html_safe : string
diff --git a/packages/ruflet_rails/lib/ruflet/rails/web_installer.rb b/packages/ruflet_rails/lib/ruflet/rails/web_installer.rb
deleted file mode 100644
index 3eb9215a..00000000
--- a/packages/ruflet_rails/lib/ruflet/rails/web_installer.rb
+++ /dev/null
@@ -1,137 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "fileutils"
-require "tmpdir"
-require "open3"
-
-module Ruflet
-  module Rails
-    # Installs the prebuilt Ruflet web client into a Rails app's frontend/
-    # directory. The web client is the `ruflet_client-web.tar.gz` release asset
-    # (the same prebuilt Flutter web build shipped on GitHub releases) — so the
-    # Rails app serves a web frontend without ever running a Flutter build.
-    #
-    #   rake ruflet:web
-    #
-    # The extracted build is what Ruflet::Rails.web_app serves (its default
-    # build dir is <Rails.root>/frontend).
-    module WebInstaller
-      module_function
-
-      REPO       = "AdamMusa/Ruflet"
-      ASSET_NAME = "ruflet_client-web.tar.gz"
-      TARGET_DIR = "frontend"
-
-      # Downloads and extracts the web client into <root>/<dir>. Returns true on
-      # success. The asset name and release tag are overridable via ENV so a
-      # project can pin a specific build.
-      def install!(root:, dir: TARGET_DIR, asset_name: env_asset_name, tag: env_tag, force: true)
-        target = File.join(root.to_s, dir)
-
-        url = release_asset_url(asset_name, tag: tag)
-        unless url
-          warn "Ruflet web client asset #{asset_name.inspect} not found in the #{REPO} release#{tag ? " #{tag}" : " (latest)"}."
-          return false
-        end
-
-        Dir.mktmpdir("ruflet-web-") do |tmp|
-          archive = File.join(tmp, asset_name)
-          return false unless download(url, archive)
-
-          staging = File.join(tmp, "frontend")
-          FileUtils.mkdir_p(staging)
-          unless safe_archive?(archive) && extract(archive, staging)
-            warn "Failed to safely extract #{asset_name}."
-            return false
-          end
-
-          unless File.file?(File.join(staging, "index.html"))
-            warn "Extracted web client but no index.html was found."
-            return false
-          end
-
-          return false if Dir.exist?(target) && !force
-
-          replace_target(staging, target)
-        end
-
-        puts "Installed Ruflet web client into #{target} (#{asset_name})."
-        true
-      rescue SystemCallError => e
-        warn "Failed to install Ruflet web client into #{target}: #{e.message}"
-        false
-      end
-
-      def release_asset_url(asset_name, tag: nil)
-        api = tag ? "releases/tags/#{tag}" : "releases/latest"
-        release = github_json("https://api.github.com/repos/#{REPO}/#{api}")
-        return nil unless release
-
-        asset = Array(release["assets"]).find { |a| a["name"] == asset_name }
-        unless asset
-          names = Array(release["assets"]).map { |a| a["name"] }
-          warn "Available release assets: #{names.join(', ')}" unless names.empty?
-        end
-        asset && asset["browser_download_url"]
-      end
-
-      def github_json(url)
-        out, status = Open3.capture2(
-          "curl", "-sSL", "--fail",
-          "-H", "Accept: application/vnd.github+json",
-          "-H", "User-Agent: ruflet_rails",
-          url
-        )
-        return nil unless status.success?
-
-        JSON.parse(out)
-      rescue JSON::ParserError
-        nil
-      end
-
-      def download(url, path)
-        ok = system("curl", "-sSL", "--fail", "-o", path, url)
-        warn "Download failed: #{url}" unless ok
-        ok
-      end
-
-      def extract(archive, target)
-        system("tar", "-xzf", archive, "-C", target)
-      end
-
-      def safe_archive?(archive)
-        out, status = Open3.capture2("tar", "-tzf", archive)
-        return false unless status.success?
-
-        out.lines.all? do |line|
-          path = line.strip
-          !path.start_with?("/") && path.split("/").none?("..")
-        end
-      end
-
-      def replace_target(staging, target)
-        FileUtils.mkdir_p(File.dirname(target))
-        backup = "#{target}.ruflet-backup"
-        FileUtils.rm_rf(backup)
-        FileUtils.mv(target, backup) if File.exist?(target)
-        FileUtils.mv(staging, target)
-        FileUtils.rm_rf(backup)
-      rescue StandardError
-        FileUtils.rm_rf(target)
-        FileUtils.mv(backup, target) if File.exist?(backup)
-        raise
-      end
-
-      def env_asset_name
-        value = ENV["RUFLET_RAILS_WEB_ARTIFACT"].to_s.strip
-        value.empty? ? ASSET_NAME : value
-      end
-
-      def env_tag
-        value = ENV["RUFLET_RAILS_WEB_TAG"].to_s.strip
-        value.empty? ? nil : value
-      end
-    end
-  end
-end
diff --git a/packages/ruflet_rails/lib/ruflet_rails.rb b/packages/ruflet_rails/lib/ruflet_rails.rb
index 9747a027..bb416ebd 100644
--- a/packages/ruflet_rails/lib/ruflet_rails.rb
+++ b/packages/ruflet_rails/lib/ruflet_rails.rb
@@ -11,11 +11,12 @@
 require "ruflet_server"
 require_relative "ruflet/rails/session_registry"
 require_relative "ruflet/rails/native_app"
+require_relative "ruflet/rails/html_dsl"
 require_relative "ruflet/rails/view_helpers"
+require_relative "ruflet/rails/native_screens"
 require_relative "ruflet/rails/desktop_launcher"
 require_relative "ruflet/rails/protocol"
 require_relative "ruflet/rails/assets"
-require_relative "ruflet/rails/web_installer"
 require_relative "ruflet/rails/configuration"
 require_relative "ruflet/rails/install_support"
 require_relative "ruflet/rails"
diff --git a/packages/ruflet_rails/ruflet_rails.gemspec b/packages/ruflet_rails/ruflet_rails.gemspec
index 8ad54d78..55bd09d9 100644
--- a/packages/ruflet_rails/ruflet_rails.gemspec
+++ b/packages/ruflet_rails/ruflet_rails.gemspec
@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "rails", ">= 7.0"
-  spec.add_dependency "ruflet", ">= 0.0.19"
-  spec.add_dependency "ruflet_core", ">= 0.0.19"
-  spec.add_dependency "ruflet_server", ">= 0.0.19"
+  spec.add_dependency "ruflet", ">= 0.0.21"
+  spec.add_dependency "ruflet_core", ">= 0.0.21"
+  spec.add_dependency "ruflet_server", ">= 0.0.21"
 end
diff --git a/packages/ruflet_rails/test/desktop_launcher_test.rb b/packages/ruflet_rails/test/desktop_launcher_test.rb
index 772448ee..f22204c4 100644
--- a/packages/ruflet_rails/test/desktop_launcher_test.rb
+++ b/packages/ruflet_rails/test/desktop_launcher_test.rb
@@ -37,14 +37,14 @@ def test_backend_url_replaces_yaml_port_with_rails_server_port_flag
 
   def test_desktop_enabled_by_env_or_flag_not_initializer_file
     Dir.mktmpdir do |dir|
-      refute Ruflet::Rails::DesktopLauncher.desktop_enabled?(root: dir, argv: ["server"], env: {})
+      refute Ruflet::Rails::DesktopLauncher.desktop_enabled?(argv: ["server"], env: {})
 
       FileUtils.mkdir_p(File.join(dir, "config", "initializers"))
       File.write(File.join(dir, "config", "initializers", "ruflet_desktop.rb"), "")
 
-      refute Ruflet::Rails::DesktopLauncher.desktop_enabled?(root: dir, argv: ["server"], env: {})
-      assert Ruflet::Rails::DesktopLauncher.desktop_enabled?(root: dir, argv: ["server"], env: { "RUFLET_RAILS_DESKTOP_SERVER" => "true" })
-      assert Ruflet::Rails::DesktopLauncher.desktop_enabled?(root: dir, argv: ["server", "--desktop"], env: {})
+      refute Ruflet::Rails::DesktopLauncher.desktop_enabled?(argv: ["server"], env: {})
+      assert Ruflet::Rails::DesktopLauncher.desktop_enabled?(argv: ["server"], env: { "RUFLET_RAILS_DESKTOP_SERVER" => "true" })
+      assert Ruflet::Rails::DesktopLauncher.desktop_enabled?(argv: ["server", "--desktop"], env: {})
     end
   end
 
diff --git a/packages/ruflet_rails/test/endpoint_declaration_test.rb b/packages/ruflet_rails/test/endpoint_declaration_test.rb
index 8d748871..cd0700bd 100644
--- a/packages/ruflet_rails/test/endpoint_declaration_test.rb
+++ b/packages/ruflet_rails/test/endpoint_declaration_test.rb
@@ -14,44 +14,32 @@ def test_endpoint_with_an_app_file_is_a_rack_endpoint
     Dir.mktmpdir do |dir|
       file = File.join(dir, "main.rb")
       File.write(file, "Ruflet.run { |page| page.add(Ruflet::UI::ControlFactory.build(:text, value: \"hi\")) }\n")
-      assert rack_app?(Ruflet::Rails.endpoint(app_file: file))
+      assert rack_app?(Ruflet::Rails.native(file))
     end
   end
 
   def test_endpoint_with_a_block_is_a_rack_endpoint
-    assert rack_app?(Ruflet::Rails.endpoint { |page| page.add(Ruflet::UI::ControlFactory.build(:text, value: "hi")) })
+    assert rack_app?(Ruflet::Rails.native { |page| page.add(Ruflet::UI::ControlFactory.build(:text, value: "hi")) })
   end
 
   def test_bare_endpoint_raises
     # No declared entry and no auto-discovery fallback — the developer must
     # declare app_file: or a block.
-    assert_raises(ArgumentError) { Ruflet::Rails.endpoint }
+    assert_raises(ArgumentError) { Ruflet::Rails.native }
   end
 
   def test_endpoint_rejects_more_than_one_source
     assert_raises(ArgumentError) do
-      Ruflet::Rails.endpoint(app_file: "x.rb") { |page| page }
+      Ruflet::Rails.native("x.rb") { |page| page }
     end
   end
 
-  def test_app_shorthand_delegates_to_endpoint_app_file
+  def test_native_accepts_an_app_file
     Dir.mktmpdir do |dir|
       file = File.join(dir, "main.rb")
       File.write(file, "Ruflet.run { |page| page.add(Ruflet::UI::ControlFactory.build(:text, value: \"hi\")) }\n")
-      assert rack_app?(Ruflet::Rails.app(file))
+      assert rack_app?(Ruflet::Rails.native(file))
     end
   end
 
-  def test_web_app_entrypoint_for_app_file_loads_the_ruflet_app
-    Dir.mktmpdir do |dir|
-      file = File.join(dir, "main.rb")
-      File.write(file, "Ruflet.run { |page| page.instance_variable_set(:@rendered, true) }\n")
-
-      page = Ruflet::Page.new(session_id: "e", client_details: { "route" => "/" },
-                              sender: ->(_a, _p) {})
-      Ruflet::Rails.web_app_entrypoint(app_file: file).call(page, {})
-
-      assert_equal true, page.instance_variable_get(:@rendered)
-    end
-  end
 end
diff --git a/packages/ruflet_rails/test/html_app_test.rb b/packages/ruflet_rails/test/html_app_test.rb
new file mode 100644
index 00000000..39e0e689
--- /dev/null
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -0,0 +1,952 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+# HTML-over-the-wire native app: pages fetched from Rails become screens of
+# real Ruflet controls, links push native screens, actions re-render in place.
+class RufletHtmlAppTest < Minitest::Test
+  # Serves canned HTML per path and records every screen asked for.
+  class StubFetcher
+    Response = Ruflet::Rails::HtmlDsl::TemplateSource::Response
+
+    attr_reader :requests
+
+    def initialize(pages)
+      @pages = pages
+      @requests = []
+    end
+
+    def fetch(url, params: nil)
+      @requests << { url: url, params: params }
+      path = URI.parse(url).path
+      body = @pages.fetch(path, "<text>missing #{path}</text>")
+      body = body.call(params) if body.respond_to?(:call)
+      Response.new(body: body, url: url)
+    end
+  end
+
+  def setup
+    @sent = []
+    @page = Ruflet::Page.new(session_id: "html", client_details: {},
+                             sender: ->(a, p) { @sent << [a, p] })
+  end
+
+  def find(node, type)
+    case node
+    when Ruflet::Control
+      return node if node.type == type
+
+      node.props.each_value { |v| (f = find(v, type)) and return f }
+      node.children.each { |c| (f = find(c, type)) and return f }
+      nil
+    when Array
+      node.each { |v| (f = find(v, type)) and return f }
+      nil
+    end
+  end
+
+  def start(pages)
+    @fetcher = StubFetcher.new(pages)
+    Ruflet::Rails.erb_to_native(@page, start_url: "https://app.test/", fetcher: @fetcher)
+  end
+
+  def test_renders_the_start_page_as_native_controls
+    start("/" => '<column class="p-4"><h1>Home</h1><text>Welcome</text></column>')
+
+    assert_equal 1, @page.views.length
+    view = @page.views.first
+    assert_equal "/", view.props["route"]
+
+    heading = find(view, "text")
+    assert_equal "Home", heading.props["value"]
+    assert_equal 32, heading.props["size"]
+  end
+
+  def test_link_pushes_a_second_screen_with_unique_route
+    app = start(
+      "/" => '<a href="/settings">Settings</a>',
+      "/settings" => "<html><head><title>Settings</title></head><body><text>prefs</text></body></html>"
+    )
+
+    find(@page.views.first, "textbutton").emit("click", nil)
+
+    assert_equal 2, @page.views.length
+    refute_equal @page.views.first.props["route"], @page.views.last.props["route"]
+    body = @page.views.last.props["controls"] || @page.views.last.children
+    assert_equal "prefs", find(body, "text").props["value"]
+
+    # Pushed screen gets a titled AppBar (so native back exists).
+    appbar = @page.views.last.props["appbar"]
+    assert_equal "Settings", appbar.props["title"].props["value"]
+
+    app.pop
+    assert_equal 1, @page.views.length
+  end
+
+  def test_action_rerenders_the_screen_in_place
+    count = 0
+    pages = {
+      "/" => -> (_params) { "<text>count #{count}</text><button on-click=\"/inc\">+</button>" },
+      "/inc" => -> (_params) { count += 1; "<text>count #{count}</text><button on-click=\"/inc\">+</button>" }
+    }
+    start(pages)
+
+    assert_equal "count 0", find(@page.views.first, "text").props["value"]
+    find(@page.views.first, "button").emit("click", nil)
+
+    assert_equal 1, @page.views.length
+    assert_equal "count 1", find(@page.views.first, "text").props["value"]
+  end
+
+  def test_form_submits_tracked_field_values
+    submitted = nil
+    pages = {
+      "/" => <<~HTML,
+        <html><head><meta name="csrf-token" content="tok-1"></head><body>
+          <form action="/session" method="post">
+            <input type="text" name="email" value="old@x.y">
+            <input type="hidden" name="token" value="h1">
+            <input type="submit" value="Go">
+          </form>
+        </body></html>
+      HTML
+      "/session" => ->(params) { submitted = params; "<text>done</text>" }
+    }
+    start(pages)
+
+    view = @page.views.first
+    find(view, "textfield").emit("change", { "value" => "new@x.y" })
+    find(view, "filledbutton").emit("click", nil)
+
+    assert_equal({ "email" => "new@x.y", "token" => "h1" }, submitted)
+    assert_equal "done", find(@page.views.first, "text").props["value"]
+  end
+
+  def test_root_navigation_resets_the_stack
+    start(
+      "/" => '<a href="/a">A</a>',
+      "/a" => '<a href="/b" nav="root">B</a>',
+      "/b" => "<text>b</text>"
+    )
+
+    find(@page.views.first, "textbutton").emit("click", nil)
+    assert_equal 2, @page.views.length
+
+    find(@page.views.last, "textbutton").emit("click", nil)
+    assert_equal 1, @page.views.length
+    assert_equal "b", find(@page.views.first, "text").props["value"]
+  end
+
+  def test_bottom_nav_mounts_on_the_view_and_switches_tabs
+    start(
+      "/" => <<~HTML,
+        <appbar title="Chats"></appbar>
+        <text>chats</text>
+        <bottom-nav>
+          <nav-item icon="chat" label="Chats" href="/" selected></nav-item>
+          <nav-item icon="call" label="Calls" href="/calls"></nav-item>
+        </bottom-nav>
+      HTML
+      "/calls" => <<~HTML
+        <appbar title="Calls"></appbar>
+        <text>calls</text>
+        <bottom-nav>
+          <nav-item icon="chat" label="Chats" href="/"></nav-item>
+          <nav-item icon="call" label="Calls" href="/calls" selected></nav-item>
+        </bottom-nav>
+      HTML
+    )
+
+    nav = @page.views.first.props["navigation_bar"]
+    assert_equal "navigationbar", nav.type
+    assert_equal 2, nav.props["destinations"].length
+
+    nav.emit("change", { "selected_index" => 1 })
+    # Tab switch resets to a single root screen showing the Calls tab.
+    assert_equal 1, @page.views.length
+    # Scope to the body (children), so we don't match the app bar's title text.
+    assert_equal "calls", find(@page.views.first.children, "text").props["value"]
+    assert_equal "Calls", @page.views.first.props["appbar"].props["title"].props["value"]
+  end
+
+  # A `<button service="…">` tap runs a real native platform method on the
+  # page (clipboard, share, haptics, …) — not a round-trip to Rails.
+  def test_service_button_invokes_a_native_page_method
+    calls = []
+    @page.define_singleton_method(:set_clipboard) { |value, **_| calls << [:set_clipboard, value] }
+    @page.define_singleton_method(:share_text) { |text, **_| calls << [:share_text, text] }
+    @page.define_singleton_method(:heavy_impact) { calls << [:heavy_impact] }
+    @page.define_singleton_method(:launch_url) { |url, **_| calls << [:launch_url, url] }
+    @page.define_singleton_method(:show_dialog) { |_dialog| calls << [:dialog] }
+    @page.define_singleton_method(:close_dialog) { |_dialog| nil }
+
+    start(
+      "/" => <<~HTML
+        <button service="copy" text="Ruflet 🚀">Copy</button>
+        <button service="share" text="Look at this">Share</button>
+        <button service="haptic" style="heavy">Buzz</button>
+        <button service="launch" url="https://ruflet.dev">Open</button>
+      HTML
+    )
+
+    buttons = find_all(@page.views.first, "button")
+    buttons.each { |button| button.emit("click", nil) }
+
+    assert_includes calls, [:set_clipboard, "Ruflet 🚀"]
+    assert_includes calls, [:share_text, "Look at this"]
+    assert_includes calls, [:heavy_impact]
+    assert_includes calls, [:launch_url, "https://ruflet.dev"]
+    # Service feedback is presented in a native dialog.
+    assert_includes calls, [:dialog]
+  end
+
+  # Query services report the returned value in a native result dialog.
+  def test_service_button_reports_a_query_result_in_a_dialog
+    dialogs = []
+    @page.define_singleton_method(:get_clipboard) do |on_result: nil, **_|
+      on_result&.call("remembered text", nil)
+    end
+    @page.define_singleton_method(:show_dialog) do |dialog|
+      dialogs << [
+        dialog.props["title"].props["value"],
+        dialog.props["content"].props["value"]
+      ]
+    end
+    @page.define_singleton_method(:close_dialog) { |_dialog| nil }
+
+    start("/" => '<button service="paste">Read clipboard</button>')
+    find_all(@page.views.first, "button").first.emit("click", nil)
+
+    assert_includes dialogs, ["Clipboard", "remembered text"]
+  end
+
+  # A failed native call surfaces the error instead of failing silently.
+  def test_service_button_reports_an_error_in_a_dialog
+    dialogs = []
+    @page.define_singleton_method(:get_connectivity) do |on_result: nil, **_|
+      on_result&.call(nil, "radio offline")
+    end
+    @page.define_singleton_method(:show_dialog) do |dialog|
+      dialogs << [
+        dialog.props["title"].props["value"],
+        dialog.props["content"].props["value"]
+      ]
+    end
+    @page.define_singleton_method(:close_dialog) { |_dialog| nil }
+
+    start("/" => '<button service="connectivity">Check</button>')
+    find_all(@page.views.first, "button").first.emit("click", nil)
+
+    assert_includes dialogs, ["Connectivity failed", "radio offline"]
+  end
+
+  def test_service_dialog_close_button_closes_and_later_results_reuse_it
+    value = "first result"
+    @page.define_singleton_method(:get_clipboard) do |on_result: nil, **_|
+      on_result&.call(value, nil)
+    end
+
+    start("/" => '<button service="paste">Read clipboard</button>')
+    button = find_all(@page.views.first, "button").first
+    button.emit("click", nil)
+
+    dialogs = @page.instance_variable_get(:@dialogs)
+    assert_equal 1, dialogs.length
+    dialog = dialogs.first
+    assert_equal true, dialog.props["open"]
+
+    find(dialog, "textbutton").emit("click", nil)
+    assert_equal false, dialog.props["open"]
+
+    value = "second result"
+    button.emit("click", nil)
+    assert_equal 1, dialogs.length
+    assert_same dialog, dialogs.first
+    assert_equal true, dialog.props["open"]
+    assert_equal "second result", dialog.props["content"].props["value"]
+  end
+
+  def test_an_older_timeout_cannot_replace_the_latest_service_result
+    callbacks = []
+    @page.define_singleton_method(:get_connectivity) do |on_result: nil, **_|
+      callbacks << on_result
+    end
+
+    start("/" => '<button service="connectivity">Check</button>')
+    button = find_all(@page.views.first, "button").first
+    button.emit("click", nil)
+    button.emit("click", nil)
+
+    callbacks.first.call(nil, "execution expired")
+    assert_empty @page.instance_variable_get(:@dialogs)
+
+    callbacks.last.call("wifi", nil)
+    dialog = @page.instance_variable_get(:@dialogs).first
+    assert_equal "Connectivity", dialog.props["title"].props["value"]
+    assert_equal "wifi", dialog.props["content"].props["value"]
+  end
+
+  def test_camera_helper_flow_updates_inline_status_and_enables_capture
+    calls = []
+    @page.define_singleton_method(:invoke) do |control, method, args: nil, timeout: 10, on_result: nil|
+      calls << [control.id, method, args, timeout]
+      case method
+      when "get_available_cameras"
+        on_result&.call([{ "name" => "back", "lens_direction" => "back" }], nil)
+      when "initialize"
+        on_result&.call(nil, nil)
+      end
+    end
+
+    start(
+      "/" => <<~HTML
+        <text id="camera-status">Waiting</text>
+        <camera id="demo-camera" preview-enabled></camera>
+        <button service="camera-open" target="demo-camera"
+                result-target="camera-status"
+                capture-target="camera-capture-button">Open</button>
+        <button id="camera-capture-button" disabled>Capture</button>
+      HTML
+    )
+    find_all(@page.views.first, "button").first.emit("click", nil)
+
+    assert_equal %w[get_available_cameras initialize], calls.map { |call| call[1] }
+    assert_equal "Camera initialized and preview is ready.",
+                 @page.get_control("camera-status").props["value"]
+    assert_equal false, @page.get_control("camera-capture-button").props["disabled"]
+    assert_empty @page.instance_variable_get(:@dialogs)
+  end
+
+  def test_studio_style_extension_event_updates_an_erb_status_target
+    start(
+      "/" => <<~HTML
+        <text id="rive-status">Ready</text>
+        <rive id="demo-rive" src="sample.riv"
+              on-state-change-target="rive-status"
+              on-state-change-prefix="State: "></rive>
+      HTML
+    )
+
+    rive = @page.get_control("demo-rive")
+    event = Struct.new(:data).new({ "state" => "playing" })
+    assert rive.emit("state_change", event)
+    assert_equal "State: playing", @page.get_control("rive-status").props["value"]
+  end
+
+  def test_service_result_can_update_inline_like_ruflet_studio
+    @page.define_singleton_method(:get_connectivity) do |on_result: nil, **_|
+      on_result&.call(["wifi"], nil)
+    end
+    start(
+      "/" => <<~HTML
+        <text id="connectivity-status">Ready</text>
+        <button service="connectivity" result-target="connectivity-status">Refresh</button>
+      HTML
+    )
+
+    find_all(@page.views.first, "button").first.emit("click", nil)
+    assert_equal "wifi", @page.get_control("connectivity-status").props["value"]
+    assert_empty @page.instance_variable_get(:@dialogs)
+  end
+
+  def test_generic_service_button_invokes_any_registered_service_method
+    calls = []
+    @page.define_singleton_method(:invoke) do |control, method, args: nil, timeout: 10, on_result: nil|
+      calls << [control.type, method, args, timeout]
+      on_result&.call("granted", nil)
+    end
+    @page.define_singleton_method(:show_dialog) { |_dialog| nil }
+    @page.define_singleton_method(:close_dialog) { |_dialog| nil }
+
+    start(
+      "/" => <<~HTML
+        <button service="permission-handler" method="request"
+                args='{"permission":"camera"}' timeout="4">Allow camera</button>
+      HTML
+    )
+    find_all(@page.views.first, "button").first.emit("click", nil)
+
+    assert_equal [["permissionhandler", "request", { "permission" => "camera" }, 4.0]], calls
+  end
+
+  def test_audio_recorder_requests_microphone_then_records_in_documents
+    calls = []
+    @page.define_singleton_method(:get_application_documents_directory) do |on_result: nil, **_|
+      on_result&.call("/device/Documents", nil)
+    end
+    @page.define_singleton_method(:invoke) do |control, method, args: nil, timeout: 10, on_result: nil|
+      calls << [control.type, method, args, timeout]
+      result = control.type == "permissionhandler" ? "granted" : true
+      on_result&.call(result, nil)
+    end
+
+    start(
+      "/" => <<~HTML
+        <audio-recorder></audio-recorder>
+        <permission-handler></permission-handler>
+        <storage-paths></storage-paths>
+        <text id="recorder-status">Ready</text>
+        <button service="audio-recorder-start" file-name="voice.wav"
+                result-target="recorder-status">Record</button>
+      HTML
+    )
+    find_all(@page.views.first, "button").first.emit("click", nil)
+
+    assert_equal ["permissionhandler", "request", { "permission" => "microphone" }], calls[0][0, 3]
+    assert_equal ["audiorecorder", "start_recording"], calls[1][0, 2]
+    assert_equal "/device/Documents/voice.wav", calls[1][2]["output_path"]
+    assert_equal({ "encoder" => "wav" }, calls[1][2]["configuration"])
+    assert_equal "Recording… Speak now.",
+                 @page.get_control("recorder-status").props["value"]
+  end
+
+  def test_audio_recorder_does_not_claim_recording_when_native_start_returns_false
+    @page.define_singleton_method(:get_application_documents_directory) do |on_result: nil, **_|
+      on_result&.call("/device/Documents", nil)
+    end
+    @page.define_singleton_method(:invoke) do |control, _method, args: nil, timeout: 10, on_result: nil|
+      on_result&.call(control.type == "permissionhandler" ? "granted" : false, nil)
+    end
+
+    start(
+      "/" => '<audio-recorder></audio-recorder><permission-handler></permission-handler>' \
+             '<text id="recorder-status">Ready</text>' \
+             '<button service="audio-recorder-start" result-target="recorder-status">Record</button>'
+    )
+    find_all(@page.views.first, "button").first.emit("click", nil)
+
+    assert_equal "The recorder could not start.",
+                 @page.get_control("recorder-status").props["value"]
+  end
+
+  def test_audio_recorder_animates_while_recording_and_autoplays_after_stop
+    recording_paths = []
+    documents_requests = 0
+    permission_requests = 0
+    @page.define_singleton_method(:get_application_documents_directory) do |on_result: nil, **_|
+      documents_requests += 1
+      on_result&.call("/device/Documents", nil)
+    end
+    @page.define_singleton_method(:invoke) do |control, method, args: nil, timeout: 10, on_result: nil|
+      # Completed audio players may never acknowledge release. Starting the
+      # next recording must not depend on that callback.
+      next if control.type == "audio" && method == "release"
+
+      result = if control.type == "permissionhandler"
+                 permission_requests += 1
+                 "granted"
+               elsif method == "start_recording"
+                 recording_paths << args["output_path"]
+                 true
+               elsif method == "stop_recording"
+                 recording_paths.last
+               else
+                 true
+               end
+      on_result&.call(result, nil)
+    end
+
+    start(
+      "/" => <<~HTML
+        <audio-recorder></audio-recorder>
+        <permission-handler></permission-handler>
+        <storage-paths></storage-paths>
+        <spinkit id="recorder-pulse" variant="pulse" visible="false"></spinkit>
+        <text id="recorder-status">Ready</text>
+        <button id="recorder-record" service="audio-recorder-start"
+                result-target="recorder-status" indicator-target="recorder-pulse"
+                record-target="recorder-record" stop-target="recorder-stop">Record</button>
+        <button id="recorder-stop" service="audio-recorder-stop" disabled
+                result-target="recorder-status" indicator-target="recorder-pulse"
+                record-target="recorder-record" stop-target="recorder-stop">Stop</button>
+      HTML
+    )
+
+    record, stop = find_all(@page.views.first, "button")
+    record.emit("click", nil)
+    assert_equal true, @page.get_control("recorder-pulse").props["visible"]
+    assert_equal true, record.props["disabled"]
+    assert_equal false, stop.props["disabled"]
+    assert_equal "Recording… Speak now.", @page.get_control("recorder-status").props["value"]
+
+    stop.emit("click", nil)
+    assert_equal false, @page.get_control("recorder-pulse").props["visible"]
+    assert_equal false, record.props["disabled"]
+    assert_equal true, stop.props["disabled"]
+    player = @page.services.find { |service| service.type == "audio" }
+    assert_equal "/device/Documents/ruflet_recording_1.wav", player.props["src"]
+    assert_equal true, player.props["autoplay"]
+    assert_equal "Saved. Playing your recording…",
+                 @page.get_control("recorder-status").props["value"]
+
+    player.emit("state_change", Struct.new(:data).new({ "state" => "completed" }))
+    assert_equal "Recording saved and playback finished.",
+                 @page.get_control("recorder-status").props["value"]
+
+    record.emit("click", nil)
+    assert_equal [
+      "/device/Documents/ruflet_recording_1.wav",
+      "/device/Documents/ruflet_recording_2.wav"
+    ], recording_paths
+    assert_equal 1, documents_requests
+    assert_equal 1, permission_requests
+    assert_equal true, @page.get_control("recorder-pulse").props["visible"]
+    assert_equal true, record.props["disabled"]
+    assert_equal false, stop.props["disabled"]
+    assert_equal "Recording… Speak now.", @page.get_control("recorder-status").props["value"]
+
+    # A late completion event from the released first playback cannot reset the
+    # status or controls for the second recording session.
+    player.emit("state_change", Struct.new(:data).new({ "state" => "completed" }))
+    assert_equal "Recording… Speak now.", @page.get_control("recorder-status").props["value"]
+  end
+
+  def test_service_button_can_invoke_a_mounted_extension_service_by_id
+    calls = []
+    @page.define_singleton_method(:invoke) do |control, method, args: nil, timeout: 10, on_result: nil|
+      calls << [control.id, method, args]
+      on_result&.call(nil, nil)
+    end
+    @page.define_singleton_method(:show_dialog) { |_dialog| nil }
+    @page.define_singleton_method(:close_dialog) { |_dialog| nil }
+
+    start(
+      "/" => <<~HTML
+        <audio id="player" src="https://example.test/song.mp3"></audio>
+        <button service="control" target="player" method="seek" position="2000">Seek</button>
+      HTML
+    )
+    assert_equal ["audio"], @page.services.map(&:type)
+    assert_nil find(@page.views.first, "audio")
+    find_all(@page.views.first, "button").first.emit("click", nil)
+
+    assert_equal [["player", "seek", { "position" => 2000 }]], calls
+  end
+
+  def find_all(node, type, found = [])
+    case node
+    when Ruflet::Control
+      found << node if node.type == type
+      node.props.each_value { |v| find_all(v, type, found) }
+      node.children.each { |c| find_all(c, type, found) }
+    when Array
+      node.each { |v| find_all(v, type, found) }
+    end
+    found
+  end
+
+  # A slow service result that lands after the user has navigated away must not
+  # pop a stray dialog on the new screen (the "flash expired" alert bug).
+  def test_service_result_after_navigation_is_dropped_not_shown_as_dialog
+    dialogs = []
+    captured = nil
+    @page.define_singleton_method(:show_dialog) { |dialog| dialogs << dialog }
+    @page.define_singleton_method(:get_clipboard) { |on_result: nil, **_| captured = on_result }
+
+    start(
+      "/" => '<a href="/next">Go</a>' \
+             '<button service="paste" result-target="s">Read</button>' \
+             '<text id="s">ready</text>',
+      "/next" => "<text>next screen</text>"
+    )
+
+    find(@page.views.first, "button").emit("click", nil) # taps paste, captures the async callback
+    find(@page.views.first, "textbutton").emit("click", nil) # navigates to /next
+    assert_equal 2, @page.views.length
+
+    # The clipboard result finally arrives — from the screen we already left.
+    captured.call("late clipboard value", nil)
+
+    assert_empty dialogs, "a result for a screen we navigated away from must not open a dialog"
+  end
+
+  # `on-load` runs a service the moment the screen mounts — Studio's build-time
+  # `refresh_info.call` that populates a panel (battery, …) before any tap.
+  def test_on_load_service_runs_when_the_screen_mounts
+    @page.define_singleton_method(:get_battery_level) { |on_result: nil, **_| on_result&.call(88, nil) }
+    @page.define_singleton_method(:get_battery_state) { |on_result: nil, **_| on_result&.call("full", nil) }
+    @page.define_singleton_method(:is_in_battery_save_mode) { |on_result: nil, **_| on_result&.call(false, nil) }
+
+    start(
+      "/" => '<text id="battery-status">Battery level: -</text>' \
+             '<button service="battery" result-target="battery-status" on-load>Refresh</button>'
+    )
+
+    # No tap — the battery panel is already populated, in Studio's exact format.
+    status = find(@page.views.first, "text")
+    assert_equal "Battery level: 88%\nBattery state: FULL\nBattery saver: OFF", status.props["value"]
+  end
+
+  def test_declared_appbar_wins_and_actions_navigate
+    start(
+      "/" => <<~HTML,
+        <appbar title="Inbox">
+          <action icon="search" href="/search"/>
+        </appbar>
+        <text>list</text>
+      HTML
+      "/search" => "<text>search</text>"
+    )
+
+    appbar = @page.views.first.props["appbar"]
+    assert_equal "Inbox", appbar.props["title"].props["value"]
+
+    appbar.props["actions"].first.emit("click", nil)
+    assert_equal 2, @page.views.length
+  end
+
+  # An expanding screen (flex-1 vertical centering) must get a fixed-viewport
+  # root: an Expanded inside a scrollable column collapses to an empty body.
+  def test_expanding_screens_do_not_scroll_but_normal_screens_do
+    start(
+      "/" => '<column class="flex-1 items-center justify-center"><text>centered</text></column>'
+    )
+    body = find(@page.views.first, "column")
+    refute body.props.key?("scroll")
+    assert_equal true, body.props["expand"]
+
+    start("/" => "<text>long page</text>")
+    body = find(@page.views.first, "column")
+    assert_equal "auto", body.props["scroll"]
+  end
+
+  # A template can hand back an ASCII-8BIT body; binary text values would be
+  # packed as msgpack bin and render as byte arrays on the client.
+  def test_binary_response_bodies_become_utf8_text
+    fetcher = Object.new
+    def fetcher.fetch(url, params: nil)
+      body = "<text>Ruflet Native — démo</text>".dup.force_encoding(Encoding::ASCII_8BIT)
+      Ruflet::Rails::HtmlDsl::TemplateSource::Response.new(body: body, url: url)
+    end
+    Ruflet::Rails.erb_to_native(@page, start_url: "https://app.test/", fetcher: fetcher)
+
+    value = find(@page.views.first, "text").props["value"]
+    assert_equal Encoding::UTF_8, value.encoding
+    assert_equal "Ruflet Native — démo", value
+  end
+
+
+  def find_all_text_values(node, values = [])
+    case node
+    when Ruflet::Control
+      values << node.props["value"] if node.type == "text"
+      node.props.each_value { |v| find_all_text_values(v, values) }
+      node.children.each { |c| find_all_text_values(c, values) }
+    when Array
+      node.each { |v| find_all_text_values(v, values) }
+    end
+    values.compact
+  end
+
+  def test_fetch_errors_render_an_error_screen
+    fetcher = Object.new
+    def fetcher.fetch(*, **) = raise "connection refused"
+    Ruflet::Rails.erb_to_native(@page, start_url: "https://app.test/", fetcher: fetcher)
+
+    texts = []
+    collect = lambda do |node|
+      case node
+      when Ruflet::Control
+        texts << node.props["value"] if node.type == "text"
+        node.props.each_value { |v| collect.call(v) }
+        node.children.each { |c| collect.call(c) }
+      when Array then node.each { |v| collect.call(v) }
+      end
+    end
+    collect.call(@page.views.first)
+    assert_includes texts.join(" "), "connection refused"
+  end
+
+  # --- one session, many screens ------------------------------------------
+  #
+  # The screens are Rails renders, but the *session* is not per screen: one
+  # Ruflet page, one screen stack held in memory, one fetcher (so one Rails
+  # session) for the whole WebSocket connection. These pin that down.
+
+  def test_back_restores_the_retained_view_without_refetching
+    app = start(
+      "/" => '<a href="/settings">Settings</a>',
+      "/settings" => "<text>prefs</text>"
+    )
+
+    home_view = @page.views.first
+    find(home_view, "textbutton").emit("click", nil)
+    assert_equal 2, @page.views.length
+
+    requests_before_back = @fetcher.requests.length
+    app.pop
+
+    assert_equal 1, @page.views.length
+    assert_equal requests_before_back, @fetcher.requests.length,
+                 "going back must not re-fetch the previous screen"
+    assert_same home_view, @page.views.first,
+                "going back must restore the retained view, not rebuild it"
+  end
+
+  def test_one_page_and_one_fetcher_serve_every_screen
+    app = start(
+      "/" => '<a href="/a">A</a>',
+      "/a" => '<a href="/b">B</a>',
+      "/b" => "<text>b</text>"
+    )
+
+    find(@page.views.first, "textbutton").emit("click", nil)
+    find(@page.views.last, "textbutton").emit("click", nil)
+
+    assert_equal 3, @page.views.length
+    assert_equal 3, @fetcher.requests.length
+    assert_equal %w[/ /a /b], @fetcher.requests.map { |r| URI.parse(r[:url]).path }
+
+    # Every screen went through the one fetcher this session owns, which is
+    # what carries the Rails session cookie from screen to screen.
+    assert_same @fetcher, app.instance_variable_get(:@fetcher)
+  end
+
+  # --- in-place re-render patches, it does not replace ---------------------
+
+  def test_rerender_patches_only_the_controls_whose_props_changed
+    count = 0
+    markup = lambda { |_params|
+      "<column><text>#{count}</text><button on-click=\"post:/up\">Up</button></column>"
+    }
+    start(
+      "/" => markup,
+      "/up" => lambda { |params|
+        count += 1
+        markup.call(params)
+      }
+    )
+
+    label = find(@page.views.first, "text")
+    assert_equal "0", label.props["value"]
+
+    @sent.clear
+    find(@page.views.first, "button").emit("click", nil)
+
+    # The shape did not move, so the whole body must not be re-sent: the
+    # mounted text control is patched in place.
+    assert_equal "1", label.props["value"], "the mounted control must carry the new value"
+    refute(@sent.any? { |(_action, payload)| payload.to_s.include?("Up") },
+           "a value change must not re-send the button")
+  end
+
+  def test_rerender_replaces_the_body_when_the_shape_changes
+    shape = "<column><text>one</text></column>"
+    app = start(
+      "/" => ->(_params) { shape },
+      "/toggle" => lambda { |_params|
+        shape = "<column><text>one</text><text>two</text></column>"
+        shape
+      }
+    )
+
+    app.action(url: "/toggle")
+
+    texts = []
+    collect = lambda do |node|
+      case node
+      when Ruflet::Control
+        texts << node.props["value"] if node.type == "text"
+        node.props.each_value { |v| collect.call(v) }
+        node.children.each { |c| collect.call(c) }
+      when Array then node.each { |v| collect.call(v) }
+      end
+    end
+    collect.call(@page.views.last)
+
+    assert_includes texts, "two", "a new control must appear when the shape grows"
+  end
+
+  def test_state_written_on_one_screen_is_visible_on_the_next
+    store = []
+    app = start(
+      "/" => '<button on-click="post:/items">Add</button>',
+      "/items" => lambda { |_params|
+        store << "item"
+        "<text>added</text>"
+      },
+      "/list" => ->(_params) { "<text>#{store.length} items</text>" }
+    )
+
+    find(@page.views.first, "button").emit("click", nil)
+    app.navigate("/list", "push")
+
+    texts = []
+    collect = lambda do |node|
+      case node
+      when Ruflet::Control
+        texts << node.props["value"] if node.type == "text"
+        node.props.each_value { |v| collect.call(v) }
+        node.children.each { |c| collect.call(c) }
+      when Array then node.each { |v| collect.call(v) }
+      end
+    end
+    collect.call(@page.views.last)
+
+    assert_includes texts, "1 items",
+                    "server state written by one screen must be readable by the next"
+  end
+
+  # --- path-only screens ---------------------------------------------------
+  #
+  # Nothing here travels over the network, so a screen can be named by path
+  # alone. The host, when one is needed at all, comes from the live WebSocket.
+
+  def test_a_path_start_url_renders_without_naming_a_host
+    @fetcher = StubFetcher.new("/native" => "<text>Native home</text>")
+    Ruflet::Rails.erb_to_native(@page, start_url: "/native", fetcher: @fetcher)
+
+    assert_equal "/native", @fetcher.requests.first[:url]
+    body = @page.views.first.props["controls"] || @page.views.first.children
+    assert_equal "Native home", find(body, "text").props["value"]
+  end
+
+  def test_a_path_start_url_resolves_absolute_and_relative_links
+    @fetcher = StubFetcher.new(
+      "/native" => '<a href="/native/counter">Counter</a>',
+      "/native/counter" => '<a href="detail">Detail</a>',
+      "/native/detail" => "<text>Detail screen</text>"
+    )
+    app = Ruflet::Rails.erb_to_native(@page, start_url: "/native", fetcher: @fetcher)
+
+    find(@page.views.first, "textbutton").emit("click", nil)
+    find(@page.views.last, "textbutton").emit("click", nil)
+
+    assert_equal %w[/native /native/counter /native/detail], @fetcher.requests.map { |r| r[:url] }
+    body = @page.views.last.props["controls"] || @page.views.last.children
+    assert_equal "Detail screen", find(body, "text").props["value"]
+    assert_equal 3, @page.views.length
+    app.pop
+  end
+
+  # Dot segments follow ordinary URI rules: the base directory of
+  # /native/counter is /native/, so ".." lands at the root.
+  def test_a_path_start_url_walks_up_a_relative_segment
+    @fetcher = StubFetcher.new(
+      "/native/counter" => '<a href="../form">Form</a>',
+      "/form" => "<text>Form screen</text>"
+    )
+    Ruflet::Rails.erb_to_native(@page, start_url: "/native/counter", fetcher: @fetcher)
+    find(@page.views.first, "textbutton").emit("click", nil)
+
+    assert_equal "/form", @fetcher.requests.last[:url]
+    body = @page.views.last.props["controls"] || @page.views.last.children
+    assert_equal "Form screen", find(body, "text").props["value"]
+  end
+
+  def test_a_path_start_url_keeps_query_strings_on_relative_links
+    @fetcher = StubFetcher.new("/native" => '<a href="search?q=ada">Search</a>',
+                               "/search" => "<text>Results</text>")
+    Ruflet::Rails.erb_to_native(@page, start_url: "/native", fetcher: @fetcher)
+    find(@page.views.first, "textbutton").emit("click", nil)
+
+    assert_equal "/search?q=ada", @fetcher.requests.last[:url]
+  end
+
+  # A service tap invokes a native method, so anything that is not one of its
+  # arguments must be filtered out: the client matches the call against the
+  # method signature and a stray key makes the whole tap do nothing.
+  def test_control_targets_are_never_sent_as_service_arguments
+    app = Ruflet::Rails::HtmlDsl::HtmlApp.allocate
+    spec = {
+      "service" => "audio-recorder-start", "icon" => "mic", "variant" => "outlined",
+      "result-target" => "recorder-status", "indicator-target" => "recorder-pulse",
+      "record-target" => "recorder-record", "stop-target" => "recorder-stop",
+      "on-error-target" => "recorder-status", "output-path" => "/tmp/take.wav"
+    }
+
+    assert_empty app.send(:service_args, spec)
+  end
+
+  # …while a real argument still reaches the device.
+  def test_service_arguments_that_are_not_markup_survive
+    app = Ruflet::Rails::HtmlDsl::HtmlApp.allocate
+    args = app.send(:service_args, { "service" => "gyroscope-start", "interval" => "200",
+                                     "result-target" => "readout" })
+
+    assert_equal({ "interval" => "200" }, args)
+  end
+
+  # --- media URLs ----------------------------------------------------------
+  #
+  # Screens are dispatched in-process, but the client loads media itself over
+  # HTTP, so those URLs — and only those — still need a real host.
+
+  def with_backend_url(url)
+    previous = Ruflet::Rails.config.backend_url
+    Ruflet::Rails.config.backend_url = url
+    yield
+  ensure
+    Ruflet::Rails.config.backend_url = previous
+  end
+
+  def render_and_find(markup, type)
+    @fetcher = StubFetcher.new("/native" => markup)
+    Ruflet::Rails.erb_to_native(@page, start_url: "/native", fetcher: @fetcher)
+    find(@page.views.first, type)
+  end
+
+  def test_a_rails_hosted_image_is_resolved_against_the_connection_host
+    with_backend_url("https://app.test") do
+      image = render_and_find('<img src="/assets/logo.png">', "image")
+
+      assert_equal "https://app.test/assets/logo.png", image.props["src"]
+    end
+  end
+
+  def test_an_avatar_image_is_resolved_too
+    with_backend_url("https://app.test") do
+      avatar = render_and_find('<avatar src="/me.png">AM</avatar>', "circleavatar")
+
+      assert_equal "https://app.test/me.png", avatar.props["foreground_image_src"]
+    end
+  end
+
+  def test_an_external_media_url_is_left_alone
+    with_backend_url("https://app.test") do
+      image = render_and_find('<img src="https://cdn.example.com/a.png">', "image")
+
+      assert_equal "https://cdn.example.com/a.png", image.props["src"]
+    end
+  end
+
+  def test_a_data_uri_and_a_bundled_asset_name_are_left_alone
+    with_backend_url("https://app.test") do
+      assert_equal "data:image/png;base64,AAAA",
+                   render_and_find('<img src="data:image/png;base64,AAAA">', "image").props["src"]
+      assert_equal "logo.png", render_and_find('<img src="logo.png">', "image").props["src"]
+      assert_equal "//cdn.example.com/a.png",
+                   render_and_find('<img src="//cdn.example.com/a.png">', "image").props["src"]
+    end
+  end
+
+  def test_media_urls_on_other_controls_are_resolved_by_attribute_name
+    with_backend_url("https://app.test") do
+      rive = render_and_find('<rive src="/anim.riv" url="/fallback.riv"></rive>', "rive")
+
+      assert_equal "https://app.test/anim.riv", rive.props["src"]
+      assert_equal "https://app.test/fallback.riv", rive.props["url"]
+    end
+  end
+
+  def test_navigation_hrefs_are_never_turned_into_media_urls
+    with_backend_url("https://app.test") do
+      @fetcher = StubFetcher.new("/native" => '<a href="/settings">Settings</a>',
+                                 "/settings" => "<text>prefs</text>")
+      Ruflet::Rails.erb_to_native(@page, start_url: "/native", fetcher: @fetcher)
+      find(@page.views.first, "textbutton").emit("click", nil)
+
+      assert_equal "/settings", @fetcher.requests.last[:url],
+                   "navigation stays a path — it is dispatched in-process, not fetched"
+    end
+  end
+
+  def test_an_absolute_start_url_still_produces_absolute_screen_urls
+    @fetcher = StubFetcher.new("/" => '<a href="/settings">Settings</a>',
+                               "/settings" => "<text>prefs</text>")
+    Ruflet::Rails.erb_to_native(@page, start_url: "https://app.test/", fetcher: @fetcher)
+    find(@page.views.first, "textbutton").emit("click", nil)
+
+    assert_equal "https://app.test/settings", @fetcher.requests.last[:url]
+  end
+end
diff --git a/packages/ruflet_rails/test/html_dsl_helpers_test.rb b/packages/ruflet_rails/test/html_dsl_helpers_test.rb
new file mode 100644
index 00000000..819d9db7
--- /dev/null
+++ b/packages/ruflet_rails/test/html_dsl_helpers_test.rb
@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+# ERB helper DSL: Ruby helpers that emit HTML DSL markup, round-tripped
+# through the transformer to prove both authoring styles are equivalent.
+class RufletHtmlDslHelpersTest < Minitest::Test
+  class Template
+    include Ruflet::Rails::HtmlDsl::ViewHelpers
+  end
+
+  class RecordingHandlers
+    attr_reader :navigations, :actions, :submissions, :control_events
+
+    def initialize
+      @navigations = []
+      @actions = []
+      @submissions = []
+      @control_events = []
+    end
+
+    def navigate(url, mode) = @navigations << [url, mode]
+    def action(url:) = @actions << url
+    def submit_form(form) = @submissions << form
+    def field_changed(name, value); end
+    def control_event(spec, event) = @control_events << [spec, event]
+  end
+
+  def setup
+    @view = Template.new
+  end
+
+  def transform(html)
+    handlers = RecordingHandlers.new
+    result = Ruflet::Rails::HtmlDsl::Transformer.new(handlers: handlers).transform(html)
+    [result, handlers]
+  end
+
+  def find(node, type)
+    case node
+    when Ruflet::Control
+      return node if node.type == type
+
+      node.props.each_value { |v| (f = find(v, type)) and return f }
+      node.children.each { |c| (f = find(c, type)) and return f }
+      nil
+    when Array
+      node.each { |v| (f = find(v, type)) and return f }
+      nil
+    end
+  end
+
+  def test_layout_helpers_emit_dsl_tags
+    markup = @view.column(class: "p-6 gap-4") do
+      @view.text("Hello", class: "text-xl font-bold") + @view.row(class: "gap-2") { @view.text("a") }
+    end
+
+    assert_includes markup, '<column class="p-6 gap-4">'
+    assert_includes markup, '<text class="text-xl font-bold">Hello</text>'
+    assert_includes markup, '<row class="gap-2"><text>a</text></row>'
+  end
+
+  def test_snake_case_attributes_become_kebab_case
+    markup = @view.button("Up", variant: "filled", icon: "add", on_click: "/counter/up")
+    assert_equal '<button variant="filled" icon="add" on-click="/counter/up">Up</button>', markup
+  end
+
+  def test_service_button_emits_a_service_attribute
+    markup = @view.button("Copy", service: "copy", text: "Hello 🚀")
+    assert_equal '<button service="copy" text="Hello 🚀">Copy</button>', markup
+  end
+
+  def test_rive_maps_its_url_to_the_src_attribute
+    markup = @view.rive("https://cdn.rive.app/animations/vehicles.riv", fit: "contain")
+    assert_includes markup, 'src="https://cdn.rive.app/animations/vehicles.riv"'
+    # The URL must not end up as element body text (which never loads).
+    refute_includes markup, ">https://cdn.rive.app"
+  end
+
+  def test_content_is_escaped_and_booleans_render_bare
+    markup = @view.text("<script>alert(1)</script>")
+    assert_includes markup, "&lt;script&gt;"
+
+    markup = @view.input("remember", type: "checkbox", checked: true, label: "Remember")
+    assert_includes markup, " checked "
+    refute_includes markup, 'checked="'
+  end
+
+  def test_hash_attributes_serialize_as_json
+    markup = @view.widget("chart", data: { points: [1, 2] })
+    assert_includes markup, "data=\"{&quot;points&quot;:[1,2]}\""
+  end
+
+  def test_spinkit_preserves_the_ruflet_studio_variant_api
+    markup = @view.spinkit(wave: { color: "#74c0fc", size: 48 })
+    assert_includes markup, 'variant="wave"'
+
+    result, = transform(markup)
+    spinner = result.controls.first
+    assert_equal "spinkit", spinner.type
+    assert_equal "wave", spinner.props["variant"]
+    assert_equal "#74c0fc", spinner.props["color"]
+    assert_equal 48, spinner.props["size"]
+  end
+
+  def test_map_child_helpers_build_the_same_named_layers_as_studio
+    markup = @view.map(initial_center: [51.505, -0.09]) do
+      @view.tile_layer(url_template: "https://tiles/{z}/{x}/{y}.png") +
+        @view.marker_layer do
+          @view.marker(coordinates: [51.505, -0.09]) { @view.icon("location_on") }
+        end
+    end
+
+    result, = transform(markup)
+    map = result.controls.first
+    assert_equal %w[tile_layer marker_layer], map.props["layers"].map(&:type)
+    assert_equal "marker", map.props["layers"].last.props["markers"].first.type
+  end
+
+  def test_extension_event_attributes_translate_to_native_callbacks
+    markup = @view.rive(
+      id: "animation",
+      src: "sample.riv",
+      on_state_change_target: "status",
+      on_state_change_prefix: "State: "
+    )
+    result, handlers = transform(markup)
+    event = Struct.new(:data).new("playing")
+    assert result.controls.first.emit("state_change", event)
+    assert_equal "status", handlers.control_events.first[0]["target"]
+    assert_equal "State: ", handlers.control_events.first[0]["prefix"]
+  end
+
+  def test_helper_markup_round_trips_through_the_transformer
+    markup = @view.column(class: "p-4 gap-3") do
+      [
+        @view.h1("Counter"),
+        @view.text("42", class: "text-5xl font-bold"),
+        @view.row(class: "gap-2") do
+          @view.button("Up", variant: "filled", on_click: "/inc") +
+            @view.link("Settings", "/settings")
+        end
+      ].join
+    end
+
+    result, handlers = transform(markup)
+    # p-4 wraps the column in a padded container by design.
+    boxed = result.controls.first
+    assert_equal "container", boxed.type
+    assert_equal 16, boxed.props["padding"]
+    column = find(boxed, "column")
+    assert_equal 12, column.props["spacing"]
+
+    heading = column.children.first
+    assert_equal 32, heading.props["size"]
+
+    find(column, "filledbutton").emit("click", nil)
+    assert_equal ["/inc"], handlers.actions
+
+    find(column, "textbutton").emit("click", nil)
+    assert_equal [["/settings", "push"]], handlers.navigations
+  end
+
+  def test_appbar_helper_round_trips
+    markup = @view.appbar("Inbox", leading_icon: "menu") do
+      @view.appbar_action("search", "/search")
+    end
+    markup += @view.text("body")
+
+    result, = transform(markup)
+    assert_equal "Inbox", result.appbar.props["title"].props["value"]
+    assert_equal 1, result.appbar.props["actions"].length
+  end
+
+  def test_form_helpers_round_trip
+    markup = @view.form(action: "/session") do
+      @view.input("email", type: "email", label: "Email", value: "a@b.c") +
+        @view.dropdown("locale", options: [%w[fr Français], %w[en English]], value: "en") +
+        @view.submit("Sign in")
+    end
+
+    result, handlers = transform(markup)
+    assert_equal "en", find(result.controls, "dropdown").props["value"]
+
+    find(result.controls, "filledbutton").emit("click", nil)
+    form = handlers.submissions.first
+    assert_equal "/session", form[:action]
+    assert_equal %w[email locale], form[:fields].keys.sort
+  end
+
+  def test_widget_reaches_the_control_registry
+    result, = transform(@view.widget("progress_bar", value: 0.4))
+    assert_equal "progressbar", result.controls.first.type
+    assert_equal 0.4, result.controls.first.props["value"]
+  end
+
+  def test_rich_component_helpers_round_trip
+    markup = @view.column do
+      [
+        @view.badge("3") { @view.icon("notifications") },
+        @view.list_tile(title: "Inbox", subtitle: "12 unread", leading: "mail", href: "/inbox"),
+        @view.segmented_button("view", value: "list",
+                               segments: [{ value: "list", label: "List", icon: "list" },
+                                          { value: "grid", label: "Grid", icon: "grid_view" }]),
+        @view.tabs do
+          @view.tab("Overview") { @view.text("a") } + @view.tab("Details", icon: "info") { @view.text("b") }
+        end
+      ].join
+    end
+
+    result, = transform(markup)
+    assert_equal "3", find(result.controls, "icon").props["badge"]
+    assert_equal "Inbox", find(result.controls, "listtile").props["title"]
+    assert_equal 2, Array(find(result.controls, "segmentedbutton").props["segments"]).length
+    assert_equal 2, find(result.controls, "tabs").props["length"]
+  end
+
+  def test_fab_helper_round_trips
+    result, handlers = transform(@view.fab(icon: "add", href: "/items/new") + @view.text("list"))
+    refute_nil result.fab
+    result.fab.emit("click", nil)
+    assert_equal [["/items/new", "push"]], handlers.navigations
+  end
+
+  def test_service_and_extension_helpers
+    assert_equal "<camera></camera>", @view.camera
+    assert_equal "<geolocator></geolocator>", @view.geolocator
+    assert_equal '<lottie src="loader.json"></lottie>', @view.lottie(src: "loader.json")
+    assert_equal '<web-view url="https://x.test"></web-view>', @view.web_view(url: "https://x.test")
+
+    result, = transform(@view.camera + @view.battery + @view.lottie(src: "x.json"))
+    assert_equal %w[battery], result.services.map(&:type)
+    assert_equal %w[camera lottie], result.controls.map(&:type)
+  end
+
+  def test_bottom_nav_and_container_helpers_round_trip
+    markup = @view.container(class: "p-4") do
+      @view.bottom_nav do
+        @view.nav_item(icon: "chat", label: "Chats", href: "/wa", selected: true) +
+          @view.nav_item(icon: "call", label: "Calls", href: "/wa/calls")
+      end + @view.text("body")
+    end
+
+    result, handlers = transform(markup)
+    assert_equal 2, result.bottom_nav.props["destinations"].length
+    result.bottom_nav.emit("change", { "selected_index" => 1 })
+    assert_equal [["/wa/calls", "root"]], handlers.navigations
+    # container helper produced a real Container wrapping the body.
+    assert_equal "container", result.controls.first.type
+  end
+end
diff --git a/packages/ruflet_rails/test/html_dsl_test.rb b/packages/ruflet_rails/test/html_dsl_test.rb
new file mode 100644
index 00000000..666a87b2
--- /dev/null
+++ b/packages/ruflet_rails/test/html_dsl_test.rb
@@ -0,0 +1,822 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+# HTML DSL: parser, style mapping, and HTML -> Ruflet control transformation.
+class RufletHtmlDslTest < Minitest::Test
+  Parser = Ruflet::Rails::HtmlDsl::Parser
+  Styles = Ruflet::Rails::HtmlDsl::Styles
+
+  class RecordingHandlers
+    attr_reader :navigations, :actions, :submissions, :fields, :services
+
+    def initialize
+      @navigations = []
+      @actions = []
+      @submissions = []
+      @fields = {}
+      @services = []
+    end
+
+    def navigate(url, mode) = @navigations << [url, mode]
+    def action(url:) = @actions << url
+    def submit_form(form) = @submissions << form
+    def field_changed(name, value) = @fields[name] = value
+    def service(spec) = @services << spec
+  end
+
+  def transform(html)
+    handlers = RecordingHandlers.new
+    result = Ruflet::Rails::HtmlDsl::Transformer.new(handlers: handlers).transform(html)
+    [result, handlers]
+  end
+
+  def find(node, type)
+    case node
+    when Ruflet::Control
+      return node if node.type == type
+
+      node.props.each_value { |v| (f = find(v, type)) and return f }
+      node.children.each { |c| (f = find(c, type)) and return f }
+      nil
+    when Array
+      node.each { |v| (f = find(v, type)) and return f }
+      nil
+    end
+  end
+
+  def find_all(node, type, matches = [])
+    case node
+    when Ruflet::Control
+      matches << node if node.type == type
+      node.props.each_value { |v| find_all(v, type, matches) }
+      node.children.each { |c| find_all(c, type, matches) }
+    when Array
+      node.each { |v| find_all(v, type, matches) }
+    end
+    matches
+  end
+
+  # --- parser ---------------------------------------------------------------
+
+  def test_parser_builds_a_tree_with_attributes
+    nodes = Parser.parse('<column class="p-4"><text bold>Hi &amp; bye</text><br><img src="/a.png"/></column>')
+    column = nodes.first
+    assert_equal "column", column.tag
+    assert_equal "p-4", column["class"]
+
+    text = column.elements.first
+    assert_equal "text", text.tag
+    assert text.key?("bold")
+    assert_equal "Hi & bye", text.text
+
+    img = column.elements.last
+    assert_equal "img", img.tag
+    assert_equal "/a.png", img["src"]
+  end
+
+  def test_parser_skips_comments_doctype_scripts_and_styles
+    nodes = Parser.parse(<<~HTML)
+      <!DOCTYPE html>
+      <!-- a comment -->
+      <script>var x = "<column>ignored</column>";</script>
+      <style>.a { color: red; }</style>
+      <text>kept</text>
+    HTML
+    tags = nodes.select(&:element?).map(&:tag)
+    assert_equal %w[text], tags
+  end
+
+  def test_parser_tolerates_unclosed_and_stray_tags
+    nodes = Parser.parse("<column><row><text>a</text></column>")
+    assert_equal "column", nodes.first.tag
+    assert_equal "a", nodes.first.text
+  end
+
+  # --- styles ---------------------------------------------------------------
+
+  def test_styles_map_spacing_colors_and_typography
+    props = Styles.parse("p-4 px-6 gap-2 bg-slate-100 text-xl font-bold text-white rounded-lg shadow flex-1")
+    assert_equal({ "left" => 24, "top" => 16, "right" => 24, "bottom" => 16 }, props[:padding])
+    assert_equal 8, props[:spacing]
+    assert_equal "#f1f5f9", props[:bgcolor]
+    assert_equal 20, props[:size]
+    assert_equal "bold", props[:weight]
+    assert_equal "#ffffff", props[:color]
+    assert_equal 8, props[:border_radius]
+    assert props[:shadow]
+    assert_equal true, props[:expand]
+  end
+
+  def test_styles_map_alignment_and_arbitrary_values
+    props = Styles.parse("items-center justify-between text-[42] w-[320px] bg-[#123456]")
+    assert_equal "center", props[:cross_alignment]
+    assert_equal "spaceBetween", props[:main_alignment]
+    assert_equal 42, props[:size]
+    assert_equal 320, props[:width]
+    assert_equal "#123456", props[:bgcolor]
+  end
+
+  def test_styles_map_transforms_positioning_and_effects
+    props = Styles.parse("rotate-45 scale-95 top-4 left-2 blur-md opacity-75 overflow-hidden aspect-video")
+    assert_in_delta 0.7854, props[:rotate], 0.001
+    assert_equal 0.95, props[:scale]
+    assert_equal 16, props[:top]
+    assert_equal 8, props[:left]
+    assert_equal 8, props[:blur]
+    assert_equal 0.75, props[:opacity]
+    assert_equal "hardEdge", props[:clip_behavior]
+    assert_in_delta 1.777, props[:aspect_ratio], 0.01
+  end
+
+  def test_styles_map_gradients_borders_and_corners
+    grad = Styles.parse("bg-gradient-to-r from-blue-500 to-cyan-400")[:gradient]
+    assert_equal "linear", grad["_type"]
+    assert_equal({ "x" => -1, "y" => 0 }, grad["begin"])
+    assert_equal ["#3b82f6", "#22d3ee"], grad["colors"]
+
+    border = Styles.parse("border-2 border-red-500")[:border]
+    assert_equal 2, border["top"]["width"]
+    assert_equal "#ef4444", border["left"]["color"]
+
+    # per-side border and per-corner radius
+    assert_equal %w[top], Styles.parse("border-t")[:border].keys
+    assert_equal({ "top_left" => 12, "bottom_right" => 2 },
+                 Styles.parse("rounded-tl-xl rounded-br-sm")[:border_radius])
+  end
+
+  def test_styles_map_typography_details_and_transitions
+    props = Styles.parse("tracking-wide leading-relaxed underline uppercase")
+    assert_equal 0.4, props[:letter_spacing]
+    assert_equal 1.625, props[:line_height]
+    assert_equal 1, props[:decoration]
+    assert_equal "uppercase", props[:text_transform]
+    assert_equal 5, Styles.parse("underline line-through")[:decoration] # 1|4
+
+    assert_equal 300, Styles.parse("duration-300")[:animate]
+    assert_equal({ "duration" => 200, "curve" => "easeInOut" },
+                 Styles.parse("transition ease-in-out duration-200")[:animate])
+    assert_equal({ "x" => 0, "y" => 0 }, Styles.parse("place-center")[:alignment])
+  end
+
+  def test_styles_map_size_gap_and_screen_helpers
+    assert_equal({ width: 48, height: 48 }, Styles.parse("size-12").slice(:width, :height))
+    assert_equal 12, Styles.parse("gap-x-3")[:spacing]
+    assert_equal 8, Styles.parse("gap-y-2")[:run_spacing]
+    assert_equal 256, Styles.parse("max-w-64")[:width]
+    assert_equal true, Styles.parse("w-screen")[:expand]
+    assert_equal true, Styles.parse("min-h-screen")[:expand]
+    assert_equal({ left: 16, right: 16 }, Styles.parse("inset-x-4").slice(:left, :right))
+  end
+
+  def test_text_style_details_reach_the_control
+    result, = transform('<text class="tracking-wide leading-loose underline uppercase">hi there</text>')
+    text = find(result.controls, "text")
+    assert_equal "HI THERE", text.props["value"]
+    assert_equal 0.4, text.props["style"]["letter_spacing"]
+    assert_equal 2.0, text.props["style"]["height"]
+    assert_equal 1, text.props["style"]["decoration"]
+
+    result, = transform('<container class="transition duration-300 place-center"><text>x</text></container>')
+    box = result.controls.first
+    assert_equal 300, box.props["animate"]
+    assert_equal({ "x" => 0, "y" => 0 }, box.props["alignment"])
+  end
+
+  def test_styles_map_text_truncation_and_fit
+    text = Styles.parse("truncate line-clamp-2 font-mono whitespace-nowrap select-none")
+    assert_equal 2, text[:max_lines]
+    assert_equal "ellipsis", text[:overflow]
+    assert_equal "monospace", text[:font_family]
+    assert_equal true, text[:no_wrap]
+    assert_equal false, text[:selectable]
+
+    assert_equal "cover", Styles.parse("object-cover")[:fit]
+    assert_equal false, Styles.parse("hidden")[:visible]
+  end
+
+  def test_rich_utilities_reach_the_control
+    result, = transform(<<~HTML)
+      <container class="rotate-3 scale-105 blur-sm overflow-hidden bg-gradient-to-br from-indigo-500 to-pink-500 border-2 border-white">
+        <text class="truncate font-mono">Hi</text>
+      </container>
+    HTML
+    box = result.controls.first
+    assert_equal "container", box.type
+    assert_in_delta 0.0524, box.props["rotate"], 0.001
+    assert_equal 1.05, box.props["scale"]
+    assert_equal "linear", box.props["gradient"]["_type"]
+    assert box.props["border"].is_a?(Hash)
+
+    text = find(box, "text")
+    assert_equal 1, text.props["max_lines"]
+    assert_equal "monospace", text.props["font_family"]
+  end
+
+  def test_styles_map_theme_color_tokens
+    props = Styles.parse("bg-primary text-on-surface")
+    assert_equal "primary", props[:bgcolor]
+    assert_equal "onsurface", props[:color]
+  end
+
+  # --- transformer: structure ------------------------------------------------
+
+  def test_layout_tags_become_flex_controls
+    result, = transform(<<~HTML)
+      <column class="gap-4 items-center justify-center">
+        <text class="text-3xl font-bold">42</text>
+        <row class="gap-2"><text>a</text><text>b</text></row>
+      </column>
+    HTML
+
+    column = result.controls.first
+    assert_equal "column", column.type
+    assert_equal 16, column.props["spacing"]
+    assert_equal "center", column.props["horizontal_alignment"]
+    assert_equal "center", column.props["alignment"]
+
+    headline = column.children.first
+    assert_equal "text", headline.type
+    assert_equal "42", headline.props["value"]
+    assert_equal 30, headline.props["size"]
+    assert_equal "bold", headline.props["weight"]
+
+    row = column.children.last
+    assert_equal "row", row.type
+    assert_equal 8, row.props["spacing"]
+  end
+
+  def test_headings_paragraphs_and_box_styles
+    result, = transform('<h1>Title</h1><p class="p-4 bg-white rounded">Body</p>')
+
+    h1 = result.controls.first
+    assert_equal "text", h1.type
+    assert_equal 32, h1.props["size"]
+
+    boxed = result.controls.last
+    assert_equal "container", boxed.type
+    assert_equal 16, boxed.props["padding"]
+    assert_equal "#ffffff", boxed.props["bgcolor"]
+    assert_equal "Body", boxed.props["content"].props["value"]
+  end
+
+  def test_full_rails_layout_unwraps_to_body_and_reads_metadata
+    result, = transform(<<~HTML)
+      <html>
+        <head>
+          <title>Inbox</title>
+          <meta name="csrf-token" content="tok123">
+        </head>
+        <body><text>hello</text></body>
+      </html>
+    HTML
+
+    assert_equal "Inbox", result.title
+    assert_equal 1, result.controls.length
+    assert_equal "hello", result.controls.first.props["value"]
+  end
+
+  def test_unknown_tags_fall_through_to_the_control_registry
+    result, = transform('<progress-bar value="0.4"></progress-bar><divider></divider>')
+
+    bar = result.controls.first
+    assert_equal "progressbar", bar.type
+    assert_equal 0.4, bar.props["value"]
+    assert_equal "divider", result.controls.last.type
+  end
+
+  # The generic passthrough is schema-aware: text and children route into the
+  # prop the control actually accepts, so the whole registry works from markup.
+  def test_generic_passthrough_routes_text_into_the_right_prop
+    # Button variants take `content`, not `value`.
+    result, = transform("<filled-button>Save</filled-button>")
+    button = result.controls.first
+    assert_equal "filledbutton", button.type
+    assert_equal "Save", find(button, "text").props["value"]
+    refute button.props.key?("value")
+
+    # A container-like control takes `content`.
+    result, = transform("<card>Hello</card>")
+    assert_equal "Hello", find(result.controls.first, "text").props["value"]
+  end
+
+  def test_generic_passthrough_routes_children_into_content_or_controls
+    # bottom_app_bar accepts `content` (single child).
+    result, = transform("<bottom-app-bar><text>bar</text></bottom-app-bar>")
+    bar = result.controls.first
+    assert_equal "bottomappbar", bar.type
+    assert_equal "bar", find(bar, "text").props["value"]
+
+    # responsive_row accepts `controls` (a list).
+    result, = transform("<responsive-row><text>a</text><text>b</text></responsive-row>")
+    rr = result.controls.first
+    assert_equal "responsiverow", rr.type
+    assert_equal 2, Array(rr.props["controls"]).length
+  end
+
+  def test_composite_controls_render_with_content
+    result, = transform("<banner><text>Heads up</text></banner>")
+    assert_equal "banner", result.controls.first.type
+    assert_equal "Heads up", find(result.controls.first, "text").props["value"]
+  end
+
+  # Every control in the ruflet_core registry must be reachable from markup
+  # without ever raising: it either builds, or (for genuinely-required-attribute
+  # controls used the wrong way) degrades to an inline placeholder.
+  def test_every_registry_control_is_reachable_from_markup
+    types = Ruflet::UI::ControlFactory::CLASS_MAP.keys
+    built = 0
+    types.each do |type|
+      tag = type.tr("_", "-")
+      %W[<#{tag}></#{tag}> <#{tag}><text>x</text></#{tag}>].each do |html|
+        result = Ruflet::Rails::HtmlDsl::Transformer.new(handlers: RecordingHandlers.new).transform(html)
+        assert_kind_of Array, result.controls
+        placeholder = result.controls.any? do |control|
+          control.type == "text" && control.props["value"].to_s.start_with?("⚠")
+        end
+        built += 1 unless placeholder
+      end
+    end
+    # The vast majority build cleanly; only a handful of required-attribute
+    # controls (icon/destination/segment) legitimately need more than a bare tag.
+    assert_operator built, :>=, types.length, "expected most catalog tags to build cleanly"
+  end
+
+  # Charts carry data in named props (groups/sections/points), so nested chart
+  # tags must route into the right slot with numeric attributes coerced.
+  def test_nested_chart_tags_build_typed_data
+    result, = transform(<<~HTML)
+      <bar-chart width="320" height="180" max-y="110">
+        <bar-chart-group x="0"><bar-chart-rod from-y="0" to-y="40" color="#69db7c"></bar-chart-rod></bar-chart-group>
+        <bar-chart-group x="1"><bar-chart-rod from-y="0" to-y="100" color="#4dabf7"></bar-chart-rod></bar-chart-group>
+      </bar-chart>
+    HTML
+
+    chart = result.controls.first
+    assert_equal "barchart", chart.type
+    assert_equal 320, chart.props["width"]
+    groups = chart.props["groups"]
+    assert_equal 2, groups.length
+    assert_equal "barchartgroup", groups.first.type
+    assert_equal 0, groups.first.props["x"]
+    rod = groups.first.props["rods"].first
+    assert_equal "barchartrod", rod.type
+    assert_equal 40, rod.props["to_y"]
+    assert_equal "#69db7c", rod.props["color"]
+  end
+
+  # A chart control has no `expand` and doesn't inherit its parent's box, so
+  # without width/height it renders as a zero-size (empty) widget. Default them.
+  def test_charts_get_default_dimensions_and_respect_overrides
+    result, = transform('<bar-chart><bar-chart-group x="0"><bar-chart-rod to-y="4"></bar-chart-rod></bar-chart-group></bar-chart>')
+    chart = result.controls.first
+    assert_equal 320, chart.props["width"]
+    assert_equal 240, chart.props["height"]
+
+    sized, = transform('<pie-chart width="150" height="150"><pie-chart-section value="1"></pie-chart-section></pie-chart>')
+    assert_equal 150, sized.controls.first.props["width"]
+    assert_equal 150, sized.controls.first.props["height"]
+  end
+
+  # Streaming sensors with no interval flood the wire at the device's native
+  # rate; default to a calm cadence so a mounted sensor doesn't cause jank.
+  def test_streaming_sensors_get_a_default_interval
+    result, = transform('<accelerometer on-reading-target="s"></accelerometer>')
+    assert_equal 200, result.services.first.props["interval"]
+
+    explicit, = transform('<gyroscope interval="500"></gyroscope>')
+    assert_equal 500, explicit.services.first.props["interval"]
+
+    # Non-streaming services are untouched.
+    clip, = transform("<clipboard></clipboard>")
+    refute clip.services.first.props.key?("interval")
+  end
+
+  def test_nested_pie_and_line_charts_build
+    pie, = transform('<pie-chart><pie-chart-section value="40" color="#4dabf7"></pie-chart-section></pie-chart>')
+    assert_equal 1, pie.controls.first.props["sections"].length
+
+    line, = transform(<<~HTML)
+      <line-chart>
+        <line-chart-data color="#51cf66"><line-chart-data-point x="1" y="1.5"></line-chart-data-point></line-chart-data>
+      </line-chart>
+    HTML
+    series = line.controls.first.props["data_series"]
+    assert_equal 1, series.length
+    assert_equal 1.5, series.first.props["points"].first.props["y"]
+  end
+
+  # Map layers need `[lat, lng]` normalized to `{latitude:, longitude:}` (the
+  # shape flutter_map reads), and a marker's child belongs in `content`, not the
+  # generic `controls` list — otherwise the marker never places on the map.
+  def test_map_normalizes_coordinates_and_marker_content
+    result, = transform(<<~HTML)
+      <map initial-center="[51.505,-0.09]" initial-zoom="13">
+        <tile-layer url-template="u"></tile-layer>
+        <marker coordinates="[51.5,-0.1]" width="44"><icon name="location_on"></icon></marker>
+        <circle-layer><circle-marker coordinates="[51.5,-0.1]" radius="400"></circle-marker></circle-layer>
+      </map>
+    HTML
+
+    map = result.controls.first
+    assert_equal({ "latitude" => 51.505, "longitude" => -0.09 }, map.props["initial_center"])
+
+    marker = map.props["layers"].find { |layer| layer.type == "marker" }
+    assert_equal({ "latitude" => 51.5, "longitude" => -0.1 }, marker.props["coordinates"])
+    assert_equal "icon", marker.props["content"].type
+    refute marker.props.key?("controls")
+
+    circle = map.props["layers"].find { |layer| layer.type == "circle_layer" }.props["circles"].first
+    assert_equal({ "latitude" => 51.5, "longitude" => -0.1 }, circle.props["coordinates"])
+  end
+
+  def test_unknown_attributes_render_a_placeholder_not_a_crash
+    result, = transform('<text nonsense-prop="1">x</text><text>next</text>')
+
+    placeholder = result.controls.first
+    assert_equal "text", placeholder.type
+    assert_includes placeholder.props["value"], "<text>"
+    assert_includes placeholder.props["value"], "nonsense_prop"
+    # Siblings keep rendering.
+    assert_equal "next", result.controls.last.props["value"]
+  end
+
+  def test_browser_js_attributes_are_ignored
+    result, = transform(<<~HTML)
+      <header>
+        <button onclick="location.reload()" style="color: red" aria-label="Reload"
+                data-turbo="false" tabindex="0">Reload</button>
+      </header>
+    HTML
+
+    button = find(result.controls, "button")
+    refute_nil button
+    refute button.props.key?("onclick")
+    refute button.props.key?("style")
+  end
+
+  # --- transformer: interactivity ---------------------------------------------
+
+  def test_links_navigate_natively
+    result, handlers = transform('<a href="/settings" nav="push">Settings</a>')
+
+    link = result.controls.first
+    assert_equal "textbutton", link.type
+    link.emit("click", nil)
+    assert_equal [["/settings", "push"]], handlers.navigations
+  end
+
+  def test_buttons_post_actions
+    result, handlers = transform('<button on-click="/counter/increment">+</button>')
+
+    button = result.controls.first
+    button.emit("click", nil)
+    assert_equal ["/counter/increment"], handlers.actions
+  end
+
+  def test_service_button_runs_a_native_service_on_tap
+    result, handlers = transform('<button service="copy" text="Ruflet 🚀">Copy</button>')
+
+    button = result.controls.first
+    assert_equal "button", button.type
+    # Service spec keys are consumed by the handler, not leaked as control props.
+    refute button.props.key?("service")
+    refute button.props.key?("text")
+    button.emit("click", nil)
+    assert_equal [{ "service" => "copy", "text" => "Ruflet 🚀" }], handlers.services
+    assert_empty handlers.actions
+  end
+
+  def test_button_variants_and_explicit_methods
+    result, handlers = transform('<button variant="outlined" on-click="delete:/items/3">Remove</button>')
+
+    button = result.controls.first
+    assert_equal "outlinedbutton", button.type
+    button.emit("click", nil)
+    assert_equal ["/items/3"], handlers.actions
+  end
+
+  def test_on_click_on_plain_elements_wraps_in_gesture_detector
+    result, handlers = transform('<card on-click="/open"><text>tap me</text></card>')
+
+    detector = result.controls.first
+    assert_equal "gesturedetector", detector.type
+    detector.emit("tap", nil)
+    assert_equal ["/open"], handlers.actions
+  end
+
+  def test_class_styles_apply_to_non_container_controls
+    # flex-1 / p-3 / gap-2 must reach list-view, text field, etc. (element_props
+    # alone ignores `class`).
+    result, = transform(<<~HTML)
+      <list class="flex-1 p-3 gap-2"><text>a</text></list>
+      <input name="q" class="flex-1">
+    HTML
+
+    listview = find(result.controls, "listview")
+    assert_equal true, listview.props["expand"]
+    assert_equal 8, listview.props["spacing"]
+    assert_equal 12, listview.props["padding"]
+
+    field = find(result.controls, "textfield")
+    assert_equal true, field.props["expand"]
+  end
+
+  def test_icon_only_button_becomes_an_icon_button
+    # A Material Button errors when `icon` is set without `content`, so an
+    # icon-only button must render as an IconButton instead.
+    result, handlers = transform('<button icon="send" on-click="/send"></button>')
+    button = result.controls.first
+    assert_equal "iconbutton", button.type
+    button.emit("click", nil)
+    assert_equal ["/send"], handlers.actions
+
+    # With a label it stays a Button (icon + content is valid).
+    result, = transform('<button icon="add" variant="filled">New</button>')
+    assert_equal "filledbutton", result.controls.first.type
+  end
+
+  def test_forms_track_fields_and_submit
+    result, handlers = transform(<<~HTML)
+      <form action="/session" method="post">
+        <input type="text" name="email" value="a@b.c" placeholder="Email">
+        <input type="hidden" name="token" value="t1">
+        <input type="submit" value="Sign in">
+      </form>
+    HTML
+
+    field = find(result.controls, "textfield")
+    assert_equal "a@b.c", field.props["value"]
+    assert_equal "Email", field.props["hint_text"]
+
+    field.emit("change", { "value" => "new@b.c" })
+    assert_equal "new@b.c", handlers.fields["email"]
+
+    submit = find(result.controls, "filledbutton")
+    submit.emit("click", nil)
+    form = handlers.submissions.first
+    assert_equal "/session", form[:action]
+    assert_equal %w[email token], form[:fields].keys.sort
+    assert_equal "t1", form[:fields]["token"]
+  end
+
+  def test_select_checkbox_and_slider_controls
+    result, = transform(<<~HTML)
+      <select name="locale" label="Language">
+        <option value="fr">Français</option>
+        <option value="en" selected>English</option>
+      </select>
+      <input type="checkbox" name="remember" label="Remember me" checked>
+      <input type="range" name="volume" min="0" max="10" value="4">
+    HTML
+
+    dropdown = find(result.controls, "dropdown")
+    assert_equal "en", dropdown.props["value"]
+    assert_equal 2, Array(dropdown.props["options"]).length
+
+    checkbox = find(result.controls, "checkbox")
+    assert_equal true, checkbox.props["value"]
+
+    slider = find(result.controls, "slider")
+    assert_equal 4.0, slider.props["value"]
+    assert_equal 10.0, slider.props["max"]
+  end
+
+  def test_appbar_extraction
+    result, handlers = transform(<<~HTML)
+      <appbar title="Inbox" leading-icon="menu">
+        <action icon="search" href="/search"/>
+      </appbar>
+      <text>body</text>
+    HTML
+
+    refute_nil result.appbar
+    assert_equal "appbar", result.appbar.type
+    assert_equal "Inbox", result.appbar.props["title"].props["value"]
+
+    action = result.appbar.props["actions"].first
+    action.emit("click", nil)
+    assert_equal [["/search", "push"]], handlers.navigations
+    assert_equal 1, result.controls.length
+  end
+
+  # --- richer component catalog ---------------------------------------------
+
+  def test_badge_and_tooltip_are_props_on_the_wrapped_control
+    # A plain label serializes as a scalar (the client renders a Hash as its
+    # toString, e.g. "{label: 3}"), so a bare label must not be a Hash.
+    result, = transform('<badge label="3"><icon name="notifications"></icon></badge>')
+    icon = result.controls.first
+    assert_equal "icon", icon.type
+    assert_equal "3", icon.props["badge"]
+    refute_kind_of Hash, icon.props["badge"]
+
+    # A styled badge becomes a real Badge control.
+    result, = transform('<badge label="9" bgcolor="red"><icon name="mail"></icon></badge>')
+    badge = result.controls.first.props["badge"]
+    assert_kind_of Ruflet::Control, badge
+    assert_equal "badge", badge.type
+
+    result, = transform('<tooltip message="Help"><icon name="help"></icon></tooltip>')
+    assert_equal "Help", result.controls.first.props["tooltip"]
+  end
+
+  def test_list_tile_maps_leading_title_subtitle
+    result, handlers = transform('<list-tile title="Inbox" subtitle="12 unread" leading="mail" on-click="/inbox"></list-tile>')
+    tile = find(result.controls, "listtile")
+    assert_equal "Inbox", tile.props["title"]
+    assert_equal "12 unread", tile.props["subtitle"]
+    # `leading` is an icon slot — the name is normalized to its codepoint.
+    refute_nil tile.props["leading"]
+    tile.emit("click", nil)
+    assert_equal ["/inbox"], handlers.actions
+  end
+
+  def test_switch_slider_checkbox_as_standalone_tags
+    result, handlers = transform(<<~HTML)
+      <switch name="dark" label="Dark mode" checked></switch>
+      <slider name="vol" min="0" max="10" value="4"></slider>
+      <checkbox name="ok" label="Agree"></checkbox>
+    HTML
+
+    switch = find(result.controls, "switch")
+    assert_equal true, switch.props["value"]
+    switch.emit("change", { "value" => false })
+    assert_equal false, handlers.fields["dark"]
+
+    assert_equal 4.0, find(result.controls, "slider").props["value"]
+    assert_equal "Agree", find(result.controls, "checkbox").props["label"]
+  end
+
+  def test_radio_group_wires_children_and_value
+    result, handlers = transform(<<~HTML)
+      <radio-group name="plan" value="pro">
+        <radio value="free" label="Free"></radio>
+        <radio value="pro" label="Pro"></radio>
+      </radio-group>
+    HTML
+
+    group = find(result.controls, "radiogroup")
+    assert_equal "pro", group.props["value"]
+    assert_equal 2, find_all(group, "radio").length
+    group.emit("change", { "value" => "free" })
+    assert_equal "free", handlers.fields["plan"]
+  end
+
+  def test_segmented_button_builds_segments
+    result, = transform(<<~HTML)
+      <segmented-button name="view" value="list">
+        <segment value="list" label="List" icon="list"></segment>
+        <segment value="grid" label="Grid" icon="grid_view"></segment>
+      </segmented-button>
+    HTML
+
+    button = find(result.controls, "segmentedbutton")
+    assert_equal 2, Array(button.props["segments"]).length
+    assert_equal ["list"], button.props["selected"]
+  end
+
+  def test_tabs_build_a_tabbar_and_panes
+    result, = transform(<<~HTML)
+      <tabs>
+        <tab label="Overview"><text>a</text></tab>
+        <tab label="Details" icon="info"><text>b</text></tab>
+      </tabs>
+    HTML
+
+    tabs = find(result.controls, "tabs")
+    assert_equal 2, tabs.props["length"]
+    assert_equal 2, find_all(tabs, "tab").length
+    assert find(tabs, "tabbar")
+    assert find(tabs, "tabbarview")
+  end
+
+  def test_expansion_tile_and_table
+    result, = transform(<<~HTML)
+      <expansion-tile title="More"><text>hidden</text></expansion-tile>
+      <table>
+        <thead><tr><th>Name</th><th>Role</th></tr></thead>
+        <tbody>
+          <tr><td>Ada</td><td>Eng</td></tr>
+          <tr><td>Alan</td><td>Math</td></tr>
+        </tbody>
+      </table>
+    HTML
+
+    tile = find(result.controls, "expansiontile")
+    assert_equal "More", tile.props["title"]
+
+    table = find(result.controls, "datatable")
+    assert_equal 2, Array(table.props["columns"]).length
+    assert_equal 2, Array(table.props["rows"]).length
+  end
+
+  def test_bottom_nav_is_extracted_and_tabs_navigate
+    result, handlers = transform(<<~HTML)
+      <bottom-nav>
+        <nav-item icon="chat" label="Chats" href="/wa" selected></nav-item>
+        <nav-item icon="donut_large" label="Status" href="/wa/status"></nav-item>
+        <nav-item icon="call" label="Calls" href="/wa/calls"></nav-item>
+      </bottom-nav>
+      <text>chats</text>
+    HTML
+
+    nav = result.bottom_nav
+    refute_nil nav
+    assert_equal "navigationbar", nav.type
+    assert_equal 3, nav.props["destinations"].length
+    assert_equal 0, nav.props["selected_index"]
+
+    nav.emit("change", { "selected_index" => 2 })
+    assert_equal [["/wa/calls", "root"]], handlers.navigations
+    assert_equal 1, result.controls.length
+  end
+
+  def test_non_visual_services_route_to_the_service_slot_while_camera_renders_inline
+    result, = transform(<<~HTML)
+      <camera></camera>
+      <audio id="player" src="track.mp3"></audio>
+      <geolocator></geolocator>
+      <text>Take a photo</text>
+      <battery></battery>
+    HTML
+
+    assert_equal %w[audio geolocator battery], result.services.map(&:type)
+    assert_equal "player", result.services.first.id
+    assert_equal "track.mp3", result.services.first.props["src"]
+    # Camera owns a native preview and is therefore an inline extension
+    # control; non-visual services stay out of the rendered body.
+    assert_equal "camera", find(result.controls, "camera").type
+    assert_equal "Take a photo", find(result.controls, "text").props["value"]
+  end
+
+  def test_extension_controls_render_inline
+    result, = transform('<video></video><lottie src="a.json"></lottie><map></map>')
+    assert_equal %w[video lottie map], result.controls.map(&:type)
+    assert_empty result.services
+  end
+
+  def test_service_button_keeps_id_and_disabled_without_leaking_service_metadata
+    result, = transform(<<~HTML)
+      <button id="capture" disabled service="camera-capture"
+              target="camera" result-target="status">Take picture</button>
+    HTML
+
+    button = find(result.controls, "button")
+    assert_equal "capture", button.id
+    assert_equal true, button.props["disabled"]
+    refute button.props.key?("service")
+    refute button.props.key?("target")
+  end
+
+  def test_map_routes_nested_extension_controls_to_layers
+    result, = transform(<<~HTML)
+      <map initial-center='[51.505,-0.09]' initial-zoom="13">
+        <tile-layer url-template="https://tile.openstreetmap.org/{z}/{x}/{y}.png"></tile-layer>
+      </map>
+    HTML
+
+    map = result.controls.first
+    assert_equal "map", map.type
+    assert_equal ["tile_layer"], map.props["layers"].map(&:type)
+    assert_equal(
+      "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
+      map.props["layers"].first.props["url_template"]
+    )
+  end
+
+  def test_fab_is_extracted_from_the_body
+    result, handlers = transform('<fab icon="add" href="/items/new"></fab><text>list</text>')
+    refute_nil result.fab
+    assert_equal "floatingactionbutton", result.fab.type
+    result.fab.emit("click", nil)
+    assert_equal [["/items/new", "push"]], handlers.navigations
+    assert_equal 1, result.controls.length
+  end
+
+  def test_chip_maps_text_to_label
+    result, = transform("<chip>Ruby</chip><chip label=\"Rails\" icon=\"star\"></chip>")
+    chips = find_all(result.controls, "chip")
+    assert_equal "Ruby", chips.first.props["label"]
+    assert_equal "Rails", chips.last.props["label"]
+    refute chips.first.props.key?("value")
+  end
+
+  def test_avatar_with_image_and_initials
+    result, = transform('<avatar src="/me.png"></avatar><avatar>AM</avatar>')
+    avatars = find_all(result.controls, "circleavatar")
+    assert_equal "/me.png", avatars.first.props["foreground_image_src"]
+    assert_equal "AM", find(avatars.last, "text").props["value"]
+  end
+
+  def test_images_and_icons
+    result, = transform('<img src="https://x.test/a.png" class="w-12 h-12 rounded-full"><icon name="home"></icon>')
+
+    image = find(result.controls, "image")
+    assert_equal "https://x.test/a.png", image.props["src"]
+    assert_equal 48, image.props["width"]
+    assert_equal 9999, image.props["border_radius"]
+
+    refute_nil find(result.controls, "icon")
+  end
+end
diff --git a/packages/ruflet_rails/test/install_generator_test.rb b/packages/ruflet_rails/test/install_generator_test.rb
index f862f425..8ebc4466 100644
--- a/packages/ruflet_rails/test/install_generator_test.rb
+++ b/packages/ruflet_rails/test/install_generator_test.rb
@@ -30,29 +30,7 @@ def test_client_option_overrides_desktop_flag
     refute generator.send(:desktop_requested?)
   end
 
-  def test_web_and_desktop_options_request_all_clients
-    generator = build_generator(web: true, desktop: true)
 
-    assert_equal "all", generator.send(:requested_client)
-    assert generator.send(:desktop_requested?)
-    assert generator.send(:web_requested?)
-  end
-
-  def test_web_option_installs_web_client_into_the_rails_app
-    generator = build_generator(web: true)
-    installed_root = nil
-    original = Ruflet::Rails::WebInstaller.method(:install!)
-    Ruflet::Rails::WebInstaller.define_singleton_method(:install!) do |root:, **|
-      installed_root = root
-      true
-    end
-
-    capture_io { generator.download_prebuilt_client }
-
-    assert_equal Dir.pwd, installed_root
-  ensure
-    Ruflet::Rails::WebInstaller.define_singleton_method(:install!, original)
-  end
 
   def test_install_generator_only_creates_the_ruflet_entrypoint
     generator = build_generator({})
@@ -70,7 +48,7 @@ def test_install_mounts_the_websocket_route_explicitly
 
       routes = File.read(File.join(dir, "config", "routes.rb"))
       assert_includes routes,
-                      'match "/ws", to: Ruflet::Rails.app(Rails.root.join("app/views/ruflet/main.rb")), via: :all',
+                      'match "/ws", to: Ruflet::Rails.native(Rails.root.join("app/views/ruflet/main.rb")), via: :all',
                       "the generator should mount /ws explicitly — no Railtie auto-mount magic"
     end
   end
@@ -85,25 +63,10 @@ def test_install_does_not_duplicate_the_websocket_route
       generator2 = Ruflet::Generators::InstallGenerator.new([], {}, destination_root: dir)
       capture_io { generator2.invoke_all }
 
-      assert_equal 1, File.read(File.join(dir, "config", "routes.rb")).scan("Ruflet::Rails.app(").length
+      assert_equal 1, File.read(File.join(dir, "config", "routes.rb")).scan("Ruflet::Rails.native(").length
     end
   end
 
-  def test_web_install_mounts_only_the_generated_app_at_ruflet
-    Dir.mktmpdir do |dir|
-      FileUtils.mkdir_p(File.join(dir, "config"))
-      File.write(File.join(dir, "config", "routes.rb"), "Rails.application.routes.draw do\nend\n")
-
-      generator = Ruflet::Generators::InstallGenerator.new([], { "web" => true }, destination_root: dir)
-      capture_io { generator.mount_websocket }
-      capture_io { generator.mount_web_app }
-
-      routes = File.read(File.join(dir, "config", "routes.rb"))
-      assert_includes routes,
-                      'mount Ruflet::Rails.web_app(app_file: Rails.root.join("app/views/ruflet/main.rb")), at: "/ruflet"'
-      refute_includes routes, "/products"
-    end
-  end
 
   def test_install_creates_ruflet_initializer_for_build_config
     Dir.mktmpdir do |dir|
diff --git a/packages/ruflet_rails/test/install_support_test.rb b/packages/ruflet_rails/test/install_support_test.rb
index d994e720..90efa5f0 100644
--- a/packages/ruflet_rails/test/install_support_test.rb
+++ b/packages/ruflet_rails/test/install_support_test.rb
@@ -40,19 +40,13 @@ def test_desktop_flag_bootstrap_templates
   def test_route_snippet_matches_exact_websocket_route
     route = Ruflet::Rails::InstallSupport.route_snippet(mount_path: "/ws")
 
-    assert_equal 'match "/ws", to: Ruflet::Rails.app(Rails.root.join("app/views/ruflet/main.rb")), via: :all', route
+    assert_equal 'match "/ws", to: Ruflet::Rails.native(Rails.root.join("app/views/ruflet/main.rb")), via: :all', route
   end
 
   def test_default_entrypoint_path_uses_ruflet_views_root
     assert_equal "app/views/ruflet/main.rb", Ruflet::Rails::InstallSupport.default_entrypoint_path
   end
 
-  def test_web_route_mounts_the_generated_entrypoint_at_ruflet
-    route = Ruflet::Rails::InstallSupport.web_route_snippet
-
-    assert_equal 'mount Ruflet::Rails.web_app(app_file: Rails.root.join("app/views/ruflet/main.rb")), at: "/ruflet"', route
-    refute_includes route, "/products"
-  end
 
   def test_app_template_uses_ruflet_run
     template = Ruflet::Rails::InstallSupport.default_app_template(app_title: "Demo")
@@ -84,13 +78,9 @@ def test_build_args_for_rails_desktop_are_server_driven
     refute_includes args, "--self"
   end
 
-  def test_build_args_for_web_are_empty_because_web_is_not_built
-    assert_empty Ruflet::Rails::InstallSupport.build_args_for_platform("web")
-  end
 
   def test_ruflet_install_steps_include_essentials
     steps = Ruflet::Rails::InstallSupport.install_next_steps(
-      target: "ruflet",
       entrypoint: "app/views/ruflet/main.rb",
       client: "none"
     ).join("\n")
@@ -103,7 +93,6 @@ def test_ruflet_install_steps_include_essentials
 
   def test_ruflet_install_steps_explain_desktop_support
     steps = Ruflet::Rails::InstallSupport.install_next_steps(
-      target: "ruflet",
       entrypoint: "app/views/ruflet/main.rb",
       client: "desktop"
     ).join("\n")
diff --git a/packages/ruflet_rails/test/native_app_test.rb b/packages/ruflet_rails/test/native_app_test.rb
index a4784d4c..b94d356a 100644
--- a/packages/ruflet_rails/test/native_app_test.rb
+++ b/packages/ruflet_rails/test/native_app_test.rb
@@ -60,7 +60,7 @@ def post(message, webview: top_webview)
   end
 
   def start(**opts)
-    Ruflet::Rails.native_app(@page, start_url: "https://myapp.com", **opts)
+    Ruflet::Rails.native_shell(@page, start_url: "https://myapp.com", **opts)
   end
 
   def wait_for_async_invokes
@@ -150,7 +150,7 @@ def test_page_ended_hides_the_loading_shimmer
   end
 
   def test_page_ended_updates_screen_url_before_chrome_sync
-    Ruflet::Rails.native_app(@page, start_url: "https://myapp.com/company/sign_in")
+    Ruflet::Rails.native_shell(@page, start_url: "https://myapp.com/company/sign_in")
     post(%(ruflet:appbar:#{JSON.generate({ "title" => "T4U", "actions" => [{ "icon" => "language" }] })}))
     post(%(ruflet:bottomnav:#{JSON.generate({ "items" => [
       { "label" => "Features", "icon" => "inventory_2", "url" => "/" },
diff --git a/packages/ruflet_rails/test/native_screens_test.rb b/packages/ruflet_rails/test/native_screens_test.rb
new file mode 100644
index 00000000..70d3d514
--- /dev/null
+++ b/packages/ruflet_rails/test/native_screens_test.rb
@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+# Screens resolve to controller actions by convention, so a native app needs no
+# route per screen.
+class RufletNativeScreensTest < Minitest::Test
+  # Stands in for an ActionController class: only action_methods and .action
+  # are used.
+  class FakeController
+    def self.action_methods = @action_methods ||= Set.new
+    def self.actions(*names) = names.each { |n| action_methods << n.to_s }
+    def self.action(name) = ->(env) { [200, {}, ["#{self}##{name}"]] }
+  end
+
+  class NativeController < FakeController
+    actions "home", "counter", "counter_increment", "counter_decrement", "device", "form", "form_submit"
+  end
+
+  class WhatsappController < FakeController
+    actions "index", "show", "status"
+  end
+
+  class ReportsController < FakeController
+    actions "show"
+  end
+
+  class DetailOnlyController < FakeController
+    actions "detail"
+  end
+
+  def setup
+    # The resolver looks constants up by name off Object, the way Rails
+    # resolves a top-level controller.
+    {
+      NativeController: NativeController, WhatsappController: WhatsappController,
+      ReportsController: ReportsController, DetailOnlyController: DetailOnlyController
+    }.each { |name, klass| Object.const_set(name, klass) unless Object.const_defined?(name) }
+  end
+
+  def resolve(path) = Ruflet::Rails::NativeScreens.resolve(path)
+
+  def test_the_folder_root_resolves_to_home
+    screen = resolve("/native")
+
+    assert_equal NativeController, screen[:controller]
+    assert_equal "home", screen[:action]
+    assert_empty screen[:params]
+  end
+
+  def test_the_folder_root_falls_back_to_index_then_show
+    assert_equal "index", resolve("/whatsapp")[:action]
+    assert_equal "show", resolve("/reports")[:action]
+  end
+
+  def test_a_single_segment_resolves_to_the_matching_action
+    screen = resolve("/native/counter")
+
+    assert_equal "counter", screen[:action]
+    assert_empty screen[:params]
+  end
+
+  # The case a routing table normally exists to express: an action that lives
+  # under another one's path.
+  def test_extra_segments_are_tried_as_part_of_the_action_name_first
+    assert_equal "counter_increment", resolve("/native/counter/increment")[:action]
+    assert_equal "counter_decrement", resolve("/native/counter/decrement")[:action]
+    assert_equal "form_submit", resolve("/native/form/submit")[:action]
+  end
+
+  # The other case: a parameterised screen.
+  def test_an_unmatched_trailing_segment_becomes_a_param
+    screen = resolve("/native/device/camera")
+
+    assert_equal "device", screen[:action]
+    assert_equal ["camera"], screen[:params]
+  end
+
+  def test_the_longest_matching_action_wins_over_a_param
+    # #counter_increment exists, so "increment" must not be read as a param.
+    screen = resolve("/native/counter/increment")
+
+    assert_equal "counter_increment", screen[:action]
+    assert_empty screen[:params]
+  end
+
+  def test_an_unknown_feature_folder_does_not_resolve
+    assert_nil resolve("/nope")
+    assert_nil resolve("/nope/counter")
+  end
+
+  def test_an_unknown_action_does_not_resolve
+    assert_nil resolve("/native/missing")
+  end
+
+  # A folder whose controller has no home/index/show has no root screen, even
+  # though the controller itself resolves.
+  def test_a_folder_with_no_index_action_does_not_resolve
+    assert_equal DetailOnlyController, Ruflet::Rails::NativeScreens.controller_for("detail_only")
+    assert_equal "detail", resolve("/detail_only/detail")[:action]
+    assert_nil resolve("/detail_only")
+  end
+
+  # Rails' own Request is not loaded here (the gem's tests run without Rails),
+  # and native_request? only ever asks for the header.
+
+end
diff --git a/packages/ruflet_rails/test/ruflet_rails_test.rb b/packages/ruflet_rails/test/ruflet_rails_test.rb
index d7b6f80b..fd1fe5f1 100644
--- a/packages/ruflet_rails/test/ruflet_rails_test.rb
+++ b/packages/ruflet_rails/test/ruflet_rails_test.rb
@@ -39,8 +39,8 @@ def view(_page); end
   def test_endpoint_without_an_entry_raises
     # A bare endpoint has no auto-discovery fallback — the developer must
     # declare an app file or a block.
-    error = assert_raises(ArgumentError) { Ruflet::Rails.endpoint }
-    assert_match(/requires one of app_file: or a block/, error.message)
+    error = assert_raises(ArgumentError) { Ruflet::Rails.native }
+    assert_match(/native requires an app file or a block/, error.message)
   end
 
   def test_configuration_serializes_declared_extensions
diff --git a/packages/ruflet_rails/test/view_helpers_test.rb b/packages/ruflet_rails/test/view_helpers_test.rb
index f5eb2c5b..c351fb52 100644
--- a/packages/ruflet_rails/test/view_helpers_test.rb
+++ b/packages/ruflet_rails/test/view_helpers_test.rb
@@ -7,45 +7,6 @@ def helper
     @helper ||= Class.new { include Ruflet::Rails::ViewHelpers }.new
   end
 
-  def test_renders_an_iframe_to_the_mount_route
-    html = helper.ruflet_frame("/products").to_s
-    assert_includes html, "<iframe"
-    assert_includes html, 'src="/products"'
-    assert_includes html, 'title="Ruflet"'
-    assert_includes html, 'loading="lazy"'
-    assert_includes html, "</iframe>"
-  end
-
-  def test_numeric_dimensions_become_pixels_strings_pass_through
-    html = helper.ruflet_frame("/showcase", height: 640, width: "80vw").to_s
-    assert_includes html, "height:640px;"
-    assert_includes html, "width:80vw;"
-    assert_includes html, "border:0;"
-  end
-
-  def test_extra_attributes_underscores_become_dashes
-    html = helper.ruflet_frame("/products", allow: "clipboard-read", data_role: "embed").to_s
-    assert_includes html, 'allow="clipboard-read"'
-    assert_includes html, 'data-role="embed"'
-  end
-
-  def test_extra_style_is_appended
-    html = helper.ruflet_frame("/products", style: "border-radius:8px;").to_s
-    assert_includes html, "border:0;"
-    assert_includes html, "border-radius:8px;"
-  end
-
-  def test_attribute_values_are_html_escaped
-    html = helper.ruflet_frame('/x"><script>alert(1)</script>').to_s
-    refute_includes html, "<script>alert(1)</script>"
-    assert_includes html, "&lt;script&gt;"
-  end
-
-  def test_full_urls_pass_through_for_cross_origin_embeds
-    html = helper.ruflet_frame("https://other.example/app").to_s
-    assert_includes html, 'src="https://other.example/app"'
-  end
-
   # --- native annotations ------------------------------------------------
 
   def test_ruflet_appbar_wraps_block_content_with_appbar_attributes
@@ -157,7 +118,7 @@ def test_native_annotation_values_are_html_escaped
   end
 
   def test_extra_kwargs_become_dashed_attributes
-    html = helper.ruflet_frame("/x", data_role: "cta").to_s
+    html = helper.ruflet_nav_item("Home", "/x", icon: "house", data_role: "cta").to_s
     assert_includes html, 'data-role="cta"'
   end
 end
diff --git a/packages/ruflet_rails/test/web_app_test.rb b/packages/ruflet_rails/test/web_app_test.rb
deleted file mode 100644
index 16705be4..00000000
--- a/packages/ruflet_rails/test/web_app_test.rb
+++ /dev/null
@@ -1,272 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "test_helper"
-require "socket"
-require "tmpdir"
-
-class RufletWebAppTest < Minitest::Test
-  def with_build_dir
-    Dir.mktmpdir do |dir|
-      File.write(File.join(dir, "index.html"), <<~HTML)
-        <!DOCTYPE html>
-        <html>
-        <head>
-          <base href="/">
-          <title>demo</title>
-        </head>
-        <body></body>
-        </html>
-      HTML
-      File.write(File.join(dir, "flutter.js"), "// flutter loader")
-      File.write(File.join(dir, "flutter_bootstrap.js"), <<~JS)
-        _flutter.loader.load({
-          serviceWorkerSettings: {
-            serviceWorkerVersion: "123"
-          }
-        });
-      JS
-      FileUtils.mkdir_p(File.join(dir, "assets"))
-      File.write(File.join(dir, "assets", "data.json"), "{}")
-      yield dir
-    end
-  end
-
-  def app_for(dir)
-    Ruflet::Rails.web_app(build_dir: dir) { |page| page.title = "Mounted" }
-  end
-
-  def test_index_base_href_follows_the_mount_point
-    with_build_dir do |dir|
-      app = app_for(dir)
-      status, headers, body = app.call("PATH_INFO" => "/", "SCRIPT_NAME" => "/myfrontend", "REQUEST_METHOD" => "GET")
-
-      assert_equal 200, status
-      assert_includes headers["content-type"], "text/html"
-      html = body.join
-      assert_includes html, '<base href="/myfrontend/">'
-      refute_includes html, '<base href="/">'
-    end
-  end
-
-  def test_index_pins_the_client_to_the_mount_without_backend_url_injection
-    with_build_dir do |dir|
-      app = app_for(dir)
-      _status, _headers, body = app.call("PATH_INFO" => "/", "SCRIPT_NAME" => "/myfrontend", "REQUEST_METHOD" => "GET")
-
-      html = body.join
-      assert_includes html, "window.flet.webSocketEndpoint",
-                      "index must steer the web client's WebSocket to the mount point"
-      assert html.index("<base href=") < html.index("window.flet.webSocketEndpoint"),
-             "bootstrap script must come after <base href> so baseURI is final"
-      refute_includes html, "searchParams.set"
-      refute_includes html, "history.replaceState"
-      assert_includes html, "ruflet-rails-service-worker-cleanup"
-    end
-  end
-
-  def test_index_served_at_mount_root_without_trailing_slash
-    with_build_dir do |dir|
-      app = app_for(dir)
-      status, _headers, body = app.call("PATH_INFO" => "", "SCRIPT_NAME" => "/counter", "REQUEST_METHOD" => "GET")
-
-      assert_equal 200, status
-      assert_includes body.join, '<base href="/counter/">'
-    end
-  end
-
-  def test_index_injects_base_when_missing
-    with_build_dir do |dir|
-      File.write(File.join(dir, "index.html"), "<html><head><title>x</title></head><body></body></html>")
-      app = app_for(dir)
-      _status, _headers, body = app.call("PATH_INFO" => "/", "SCRIPT_NAME" => "/m", "REQUEST_METHOD" => "GET")
-
-      assert_includes body.join, '<base href="/m/">'
-    end
-  end
-
-  def test_serves_static_files_with_content_type
-    with_build_dir do |dir|
-      app = app_for(dir)
-      status, headers, body = app.call("PATH_INFO" => "/flutter.js", "SCRIPT_NAME" => "/myfrontend", "REQUEST_METHOD" => "GET")
-
-      assert_equal 200, status
-      assert_equal "application/javascript", headers["content-type"]
-      assert_equal "// flutter loader", body.join
-
-      status, headers, = app.call("PATH_INFO" => "/assets/data.json", "SCRIPT_NAME" => "/myfrontend", "REQUEST_METHOD" => "GET")
-      assert_equal 200, status
-      assert_equal "application/json", headers["content-type"]
-    end
-  end
-
-  def test_disables_flutter_service_worker_for_mounted_rails_app
-    with_build_dir do |dir|
-      app = app_for(dir)
-      status, headers, body = app.call(
-        "PATH_INFO" => "/flutter_bootstrap.js",
-        "SCRIPT_NAME" => "/myfrontend",
-        "REQUEST_METHOD" => "GET"
-      )
-
-      assert_equal 200, status
-      assert_equal "no-cache", headers["cache-control"]
-      refute_includes body.join, "serviceWorkerSettings"
-      assert_includes body.join, "_flutter.loader.load({"
-    end
-  end
-
-  def test_retires_a_service_worker_previously_installed_for_the_mount
-    with_build_dir do |dir|
-      app = app_for(dir)
-      status, headers, body = app.call(
-        "PATH_INFO" => "/flutter_service_worker.js",
-        "SCRIPT_NAME" => "/myfrontend",
-        "REQUEST_METHOD" => "GET"
-      )
-
-      assert_equal 200, status
-      assert_equal "no-store", headers["cache-control"]
-      assert_includes body.join, "self.registration.unregister()"
-      assert_includes body.join, "caches.delete"
-      assert_includes body.join, "client.navigate(client.url)"
-    end
-  end
-
-  def test_blocks_path_traversal
-    with_build_dir do |dir|
-      app = app_for(dir)
-      status, = app.call("PATH_INFO" => "/../../etc/passwd", "SCRIPT_NAME" => "/m", "REQUEST_METHOD" => "GET")
-      assert_equal 404, status
-    end
-  end
-
-  def test_missing_build_reports_actionable_error
-    app = Ruflet::Rails.web_app(build_dir: "/nonexistent/build") { |page| page.title = "x" }
-    status, _headers, body = app.call("PATH_INFO" => "/", "SCRIPT_NAME" => "/m", "REQUEST_METHOD" => "GET")
-
-    assert_equal 404, status
-    assert_includes body.join, "rake ruflet:web"
-  end
-
-  def test_build_dir_under_public_is_rejected
-    with_rails_stub do |root|
-      public_app = File.join(root, "public", "app")
-      app = Ruflet::Rails.web_app(build_dir: public_app) { |page| page.title = "x" }
-
-      error = assert_raises(ArgumentError) do
-        app.call("PATH_INFO" => "/", "SCRIPT_NAME" => "/m", "REQUEST_METHOD" => "GET")
-      end
-      assert_includes error.message, "public/"
-    end
-  end
-
-  def test_default_build_dir_is_outside_public
-    with_rails_stub do |root|
-      FileUtils.mkdir_p(File.join(root, "frontend"))
-      File.write(File.join(root, "frontend", "index.html"), "<html><head></head><body></body></html>")
-
-      app = Ruflet::Rails.web_app { |page| page.title = "Default" }
-      status, _headers, body = app.call("PATH_INFO" => "/", "SCRIPT_NAME" => "/x", "REQUEST_METHOD" => "GET")
-
-      assert_equal 200, status
-      assert_includes body.join, "<base href=\"/x/\">"
-    end
-  end
-
-  def with_rails_stub
-    Dir.mktmpdir do |root|
-      stub = Module.new do
-        define_singleton_method(:root) { Pathname.new(root) }
-        define_singleton_method(:public_path) { Pathname.new(File.join(root, "public")) }
-      end
-      had_const = Object.const_defined?(:Rails)
-      previous = Object.const_get(:Rails) if had_const
-      Object.send(:remove_const, :Rails) if had_const
-      Object.const_set(:Rails, stub)
-      require "pathname"
-      yield root
-    ensure
-      Object.send(:remove_const, :Rails) if Object.const_defined?(:Rails)
-      Object.const_set(:Rails, previous) if had_const
-    end
-  end
-
-  def test_websocket_upgrade_runs_the_ruflet_protocol_under_the_mount
-    with_build_dir do |dir|
-      server_io, client_io = UNIXSocket.pair
-      app = app_for(dir)
-
-      env = {
-        "REQUEST_METHOD" => "GET",
-        "PATH_INFO" => "/",
-        "SCRIPT_NAME" => "/myfrontend",
-        "HTTP_UPGRADE" => "websocket",
-        "HTTP_CONNECTION" => "Upgrade",
-        "HTTP_SEC_WEBSOCKET_KEY" => "testkey",
-        "rack.hijack" => lambda { },
-        "rack.hijack_io" => server_io
-      }
-      status, = app.call(env)
-      assert_equal(-1, status, "upgrade should hijack the socket")
-
-      response = +""
-      response << client_io.readpartial(1024) until response.include?("\r\n\r\n")
-      assert_includes response, "101 Switching Protocols"
-
-      send_client_frame(client_io, Ruflet::WireCodec.pack([
-        Ruflet::Protocol::ACTIONS[:register_client],
-        { "session_id" => "", "page_name" => "",
-          "page" => { "route" => "/", "width" => 100, "height" => 100,
-                      "platform" => "web", "platform_brightness" => "light", "media" => {} } }
-      ]))
-
-      ack = Ruflet::WireCodec.unpack(read_server_frame(client_io))
-      assert_equal Ruflet::Protocol::ACTIONS[:register_client], ack[0]
-
-      patch = Ruflet::WireCodec.unpack(read_server_frame(client_io))
-      assert_equal Ruflet::Protocol::ACTIONS[:patch_control], patch[0]
-      assert_includes patch[1].inspect, "Mounted"
-    ensure
-      client_io&.close rescue nil
-      server_io&.close rescue nil
-    end
-  end
-
-  def test_web_app_rejects_multiple_entrypoint_sources
-    assert_raises(ArgumentError) do
-      Ruflet::Rails.web_app(app_file: "b.rb") { |page| page }
-    end
-  end
-
-  private
-
-  def ws_env(io)
-    {
-      "REQUEST_METHOD" => "GET",
-      "PATH_INFO" => "/",
-      "SCRIPT_NAME" => "/m",
-      "HTTP_UPGRADE" => "websocket",
-      "HTTP_CONNECTION" => "Upgrade",
-      "HTTP_SEC_WEBSOCKET_KEY" => "testkey",
-      "rack.hijack" => lambda { },
-      "rack.hijack_io" => io
-    }
-  end
-
-  def send_client_frame(io, payload)
-    mask = [1, 2, 3, 4]
-    header = [0x82, 0x80 | payload.bytesize].pack("CC")
-    masked = payload.bytes.each_with_index.map { |byte, index| byte ^ mask[index % 4] }
-    io.write(header + mask.pack("C4") + masked.pack("C*"))
-  end
-
-  def read_server_frame(io)
-    first = io.read(2)
-    raise "closed" unless first
-
-    length = first.getbyte(1) & 0x7f
-    length = io.read(2).unpack1("n") if length == 126
-    length = io.read(8).unpack1("Q>") if length == 127
-    io.read(length)
-  end
-end
diff --git a/packages/ruflet_rails/test/web_installer_test.rb b/packages/ruflet_rails/test/web_installer_test.rb
deleted file mode 100644
index 39d8219a..00000000
--- a/packages/ruflet_rails/test/web_installer_test.rb
+++ /dev/null
@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "test_helper"
-require "fileutils"
-require "tmpdir"
-
-class RufletWebInstallerTest < Minitest::Test
-  def test_install_extracts_prebuilt_web_client_into_frontend
-    Dir.mktmpdir do |root|
-      tarball = build_fake_web_tarball(root)
-
-      with_stubs(
-        release_asset_url: ->(*) { "https://example/ruflet_client-web.tar.gz" },
-        download: ->(_url, path) { FileUtils.cp(tarball, path); true }
-      ) do
-        assert Ruflet::Rails::WebInstaller.install!(root: root)
-      end
-
-      assert File.file?(File.join(root, "frontend", "index.html"))
-      assert File.file?(File.join(root, "frontend", "main.dart.js"))
-    end
-  end
-
-  def test_install_returns_false_when_release_asset_is_missing
-    Dir.mktmpdir do |root|
-      with_stubs(release_asset_url: ->(*) { nil }) do
-        refute Ruflet::Rails::WebInstaller.install!(root: root)
-      end
-      refute Dir.exist?(File.join(root, "frontend"))
-    end
-  end
-
-  def test_artifact_name_matches_the_release_web_client
-    assert_equal "ruflet_client-web.tar.gz", Ruflet::Rails::WebInstaller::ASSET_NAME
-    assert_equal "frontend", Ruflet::Rails::WebInstaller::TARGET_DIR
-  end
-
-  def test_failed_install_preserves_existing_frontend
-    Dir.mktmpdir do |root|
-      frontend = File.join(root, "frontend")
-      FileUtils.mkdir_p(frontend)
-      File.write(File.join(frontend, "index.html"), "working")
-
-      with_stubs(
-        release_asset_url: ->(*) { "https://example/broken.tar.gz" },
-        download: ->(_url, path) { File.write(path, "not a tarball"); true }
-      ) do
-        refute Ruflet::Rails::WebInstaller.install!(root: root)
-      end
-
-      assert_equal "working", File.read(File.join(frontend, "index.html"))
-    end
-  end
-
-  def test_force_false_preserves_existing_frontend
-    Dir.mktmpdir do |root|
-      frontend = File.join(root, "frontend")
-      FileUtils.mkdir_p(frontend)
-      File.write(File.join(frontend, "index.html"), "working")
-      tarball = build_fake_web_tarball(root)
-
-      with_stubs(
-        release_asset_url: ->(*) { "https://example/ruflet_client-web.tar.gz" },
-        download: ->(_url, path) { FileUtils.cp(tarball, path); true }
-      ) do
-        refute Ruflet::Rails::WebInstaller.install!(root: root, force: false)
-      end
-
-      assert_equal "working", File.read(File.join(frontend, "index.html"))
-    end
-  end
-
-  private
-
-  # Temporarily replace WebInstaller singleton methods (no minitest/mock dep).
-  def with_stubs(stubs)
-    mod = Ruflet::Rails::WebInstaller
-    originals = stubs.keys.to_h { |name| [name, mod.method(name)] }
-    stubs.each { |name, impl| mod.define_singleton_method(name, &impl) }
-    yield
-  ensure
-    originals&.each { |name, m| mod.define_singleton_method(name, m) }
-  end
-
-  def build_fake_web_tarball(root)
-    src = File.join(root, "src")
-    FileUtils.mkdir_p(src)
-    File.write(File.join(src, "index.html"), "<html><head></head><body>ok</body></html>")
-    File.write(File.join(src, "main.dart.js"), "// js")
-    tarball = File.join(root, "ruflet_client-web.tar.gz")
-    system("tar", "-C", src, "-czf", tarball, ".") || raise("tar failed building fixture")
-    tarball
-  end
-end