From 4aee5e06fe692b1183868752ccc78dd8f6b7fd1d Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Fri, 31 Jul 2026 00:44:41 -0400
Subject: [PATCH 01/30] Ship the HTML DSL in ruflet_rails

Rails ERB views compile into real native controls, so a Rails app can drive a
native UI without a Ruflet app file or a WebView. The feature previously lived
only in an uncommitted worktree; this lands it in the package.

  html_dsl/parser, styles, transformer   markup -> control tree
  html_dsl/html_app                      screens, navigation, services
  html_dsl/rack_fetcher                  in-process Rails dispatch, no socket
  html_dsl/view_helpers                  112 ERB helpers

Two fixes for how an in-place re-render costs:

  control_diff  patch only the props that changed instead of replacing the
                body. A counter tap went from 653 bytes and 11 controls to 53
                bytes and one prop, and the client no longer rebuilds the
                subtree (which was losing scroll position).

  render_native Post/Redirect/Get is for browsers with a reload button. The
                native client has neither, so the redirect doubled the work.
                Actions now answer the native session directly: two Rails
                cycles per tap became one.

Service calls that wait on a person -- permission prompts, file pickers, save
sheets -- no longer use the 10s default, which expired while the dialog was
still on screen ("execution expired"). 30s covers answering a dialog without
turning a broken call into a long hang.

save_file's src-bytes arrives from an HTML attribute as text; force it to
binary so msgpack sends it as bin and it lands as the Uint8List the client
declares, instead of raising a String/Uint8List cast error.

Mounting services no longer swallows its own errors: a failed mount used to
surface later as an unexplained invoke timeout.

Also removes the duplicated WireCodec and WebSocketConnection now provided by
ruflet_server, and adds a Gemfile/Rakefile so the package resolves against the
local sibling gems and runs its own suite.

282 runs, 1863 assertions, 0 failures.
---
 packages/ruflet_rails/Gemfile                 |   19 +
 packages/ruflet_rails/Gemfile.lock            |  338 +++++
 packages/ruflet_rails/README.md               |  213 ++-
 packages/ruflet_rails/Rakefile                |   12 +
 .../ruflet/install/install_generator.rb       |    5 +-
 packages/ruflet_rails/lib/ruflet/rails.rb     |   45 +-
 .../lib/ruflet/rails/controller_helpers.rb    |   55 +
 .../ruflet_rails/lib/ruflet/rails/html_dsl.rb |   38 +
 .../lib/ruflet/rails/html_dsl/control_diff.rb |  109 ++
 .../lib/ruflet/rails/html_dsl/html_app.rb     | 1169 +++++++++++++++++
 .../lib/ruflet/rails/html_dsl/parser.rb       |  208 +++
 .../lib/ruflet/rails/html_dsl/rack_fetcher.rb |  153 +++
 .../lib/ruflet/rails/html_dsl/styles.rb       |  433 ++++++
 .../lib/ruflet/rails/html_dsl/transformer.rb  | 1149 ++++++++++++++++
 .../lib/ruflet/rails/html_dsl/view_helpers.rb |  306 +++++
 .../lib/ruflet/rails/install_support.rb       |    6 +-
 .../lib/ruflet/rails/native_app.rb            |    6 +-
 .../lib/ruflet/rails/protocol/web_app.rb      |    6 +-
 .../rails/protocol/web_socket_connection.rb   |  126 --
 .../lib/ruflet/rails/protocol/wire_codec.rb   |  268 ----
 .../ruflet_rails/lib/ruflet/rails/railtie.rb  |   27 +-
 .../lib/ruflet/rails/view_helpers.rb          |    4 +-
 .../lib/ruflet/rails/web_installer.rb         |    2 +-
 packages/ruflet_rails/lib/ruflet_rails.rb     |    2 +
 packages/ruflet_rails/ruflet_rails.gemspec    |    6 +-
 .../test/controller_helpers_test.rb           |   61 +
 .../test/endpoint_declaration_test.rb         |   10 +-
 packages/ruflet_rails/test/html_app_test.rb   |  676 ++++++++++
 .../test/html_dsl_helpers_test.rb             |  251 ++++
 packages/ruflet_rails/test/html_dsl_test.rb   |  824 ++++++++++++
 .../test/install_generator_test.rb            |    6 +-
 .../ruflet_rails/test/install_support_test.rb |    4 +-
 packages/ruflet_rails/test/native_app_test.rb |    4 +-
 .../ruflet_rails/test/ruflet_rails_test.rb    |    4 +-
 packages/ruflet_rails/test/web_app_test.rb    |   10 +-
 35 files changed, 6077 insertions(+), 478 deletions(-)
 create mode 100644 packages/ruflet_rails/Gemfile
 create mode 100644 packages/ruflet_rails/Gemfile.lock
 create mode 100644 packages/ruflet_rails/Rakefile
 create mode 100644 packages/ruflet_rails/lib/ruflet/rails/controller_helpers.rb
 create mode 100644 packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
 create mode 100644 packages/ruflet_rails/lib/ruflet/rails/html_dsl/control_diff.rb
 create mode 100644 packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
 create mode 100644 packages/ruflet_rails/lib/ruflet/rails/html_dsl/parser.rb
 create mode 100644 packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb
 create mode 100644 packages/ruflet_rails/lib/ruflet/rails/html_dsl/styles.rb
 create mode 100644 packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
 create mode 100644 packages/ruflet_rails/lib/ruflet/rails/html_dsl/view_helpers.rb
 delete mode 100644 packages/ruflet_rails/lib/ruflet/rails/protocol/web_socket_connection.rb
 delete mode 100644 packages/ruflet_rails/lib/ruflet/rails/protocol/wire_codec.rb
 create mode 100644 packages/ruflet_rails/test/controller_helpers_test.rb
 create mode 100644 packages/ruflet_rails/test/html_app_test.rb
 create mode 100644 packages/ruflet_rails/test/html_dsl_helpers_test.rb
 create mode 100644 packages/ruflet_rails/test/html_dsl_test.rb

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..52ae9322 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.native(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..ffa164c8 100644
--- a/packages/ruflet_rails/lib/generators/ruflet/install/install_generator.rb
+++ b/packages/ruflet_rails/lib/generators/ruflet/install/install_generator.rb
@@ -31,7 +31,7 @@ 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
@@ -41,7 +41,8 @@ def mount_web_app
 
         routes = File.join(destination_root, "config", "routes.rb")
         return unless File.file?(routes)
-        return if File.read(routes).include?("Ruflet::Rails.web_app(")
+        contents = File.read(routes)
+        return if contents.include?("Ruflet::Rails.web(")
 
         route Ruflet::Rails::InstallSupport.web_route_snippet(entrypoint: entrypoint_path)
       end
diff --git a/packages/ruflet_rails/lib/ruflet/rails.rb b/packages/ruflet_rails/lib/ruflet/rails.rb
index 74bd4642..96749b8e 100644
--- a/packages/ruflet_rails/lib/ruflet/rails.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails.rb
@@ -28,49 +28,42 @@ 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:
+    # Self-contained web frontend (the Flutter web build plus the Ruflet
+    # WebSocket on one mount), for browser clients. Serves the build with
+    # <base href> rewritten to the mount point; routes stay routing-only:
     #
     #   # 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"
+    #   mount Ruflet::Rails.web(app_file: "app/ruflet/showcase/main.rb"), at: "/showcase"
     #
-    #   # a custom block:
-    #   mount Ruflet::Rails.web_app { |page| MyHome.render(page) }, at: "/app"
+    #   # or a custom block:
+    #   mount Ruflet::Rails.web { |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)
+    def web(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?
+      raise ArgumentError, "web accepts only one of app_file: or a block" if sources.length > 1
+      raise ArgumentError, "web requires one of app_file: or a block" if sources.empty?
 
       Protocol::WebApp.new(
         build_dir: build_dir,
diff --git a/packages/ruflet_rails/lib/ruflet/rails/controller_helpers.rb b/packages/ruflet_rails/lib/ruflet/rails/controller_helpers.rb
new file mode 100644
index 00000000..23769dda
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/controller_helpers.rb
@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Ruflet
+  module Rails
+    # Available in every controller (see Railtie).
+    #
+    # A native screen is fetched by the session's RackFetcher, which tags its
+    # requests. Knowing that lets an action answer the native client in one
+    # cycle instead of the browser's two.
+    #
+    # Post/Redirect/Get exists so a browser's reload button doesn't re-submit.
+    # The native client has no reload button and no address bar: the redirect
+    # buys nothing there and doubles the work, because the fetcher has to
+    # follow the 302 with a second request through routing, the controller and
+    # the view. `render_native` renders the screen straight from the POST.
+    #
+    #   def counter_increment
+    #     session[:count] = session[:count].to_i + 1
+    #     render_native :counter, else: -> { redirect_to counter_path }
+    #   end
+    # A plain module on purpose: ruflet_rails loads without Rails (the gem's
+    # own tests do exactly that), so this must not reach for
+    # ActiveSupport::Concern at load time.
+    module ControllerHelpers
+      def self.included(base)
+        return unless base.respond_to?(:helper_method)
+
+        base.helper_method :ruflet_native_request?
+      rescue StandardError
+        nil
+      end
+
+      # True when this request came from a Ruflet native session rather than a
+      # browser.
+      def ruflet_native_request?
+        request.headers["X-Ruflet-Native"].to_s == "1"
+      end
+
+      # Render `template` for a native client; otherwise run `else` (usually the
+      # redirect a browser still wants).
+      def render_native(template, **options, &fallback)
+        fallback ||= options.delete(:else)
+
+        unless ruflet_native_request?
+          return fallback.call if fallback.respond_to?(:call)
+
+          raise ArgumentError, "render_native needs an `else:` for browser requests"
+        end
+
+        options.delete(:else)
+        render(template, **options)
+      end
+    end
+  end
+end
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..52f2d449
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "html_dsl/parser"
+require_relative "html_dsl/styles"
+require_relative "html_dsl/transformer"
+require_relative "html_dsl/rack_fetcher"
+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: "#{Ruflet::Rails.backend_url}/native") }
+    #
+    # A `fetcher:` can be injected for tests; production uses the in-process
+    # RackFetcher by default.
+    def erb_to_native(page, **opts)
+      HtmlDsl::HtmlApp.new(page, **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..eb92a685
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -0,0 +1,1169 @@
+# frozen_string_literal: true
+
+require "uri"
+require "erb"
+require "json"
+
+module Ruflet
+  module Rails
+    module HtmlDsl
+      # HTML-over-the-wire native UI: Rails renders HTML DSL markup and this
+      # app turns each page into a screen of real Ruflet controls — no
+      # WebView. Links push native screens, `on-click` actions round-trip to
+      # Rails and re-render the current screen in place, forms post their
+      # field values and render the response.
+      class HtmlApp
+        Screen = Struct.new(:url, :view, :route, :root, :fields, :csrf_token, :title,
+                            :appbar_sig, :fab_sig, :nav_sig, :body, 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, from: @screen)
+          def action(method:, url:) = @app.action(method: method, 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 run through Rails routing + controllers, dispatched in-process
+        # against the running app (a function call, not network HTTP), so the
+        # whole session stays on its single WebSocket thread.
+        def default_fetcher
+          RackFetcher.new
+        end
+
+        # --- navigation ---------------------------------------------------------
+
+        def navigate(url, mode, from: nil)
+          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: request the URL, then re-render the source
+        # screen in place with the returned markup (Rails redirects are
+        # followed by the fetcher, so `redirect_to` re-renders the target).
+        def action(method:, url:, from: nil)
+          screen = from || @screens.last
+          return unless screen
+
+          response = request(method, absolute_url(url), screen: screen)
+          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(form[:method], absolute_url(form[:action]), params: params, screen: screen)
+          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
+                  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(data)}" 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("get", url, screen: screen)
+          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
+
+        SERVICE_META_KEYS = %w[
+          service method target args toast timeout result-target capture-target preview-target id disabled
+        ].freeze
+
+        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 "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. This mirrors Studio's flow exactly:
+        # resolve the documents dir → check `has_permission` → record to a .wav in
+        # that dir with the wav encoder. A multi-step async chain, not a single
+        # fire-and-forget invoke (which is why "Start" did nothing before).
+        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|
+            # First call raises the OS microphone prompt and blocks until the
+            # person answers it, so this cannot use the 10s default.
+            recorder.has_permission(timeout: interactive_timeout(spec), on_result: lambda do |*out|
+              allowed, 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 allowed
+                next show_service_result("Microphone permission was not granted.",
+                                         title: "Audio recorder", target: target)
+              end
+
+              show_service_result("Recording → #{file}", title: "Audio recorder", target: target)
+              recorder.start_recording(
+                output_path: file, configuration: configuration, upload: spec["upload"],
+                # Starting capture can itself surface the OS prompt when the
+                # permission was only just granted.
+                timeout: interactive_timeout(spec),
+                on_result: lambda do |*rec|
+                  next unless service_error?(rec[1])
+
+                  show_service_result("Start error: #{rec[1]}", title: "Audio recorder failed", target: target)
+                end
+              )
+            end)
+          end
+
+          return begin_recording.call(explicit) unless explicit.empty?
+
+          show_service_result("Preparing recording…", title: "Audio recorder", target: target)
+          @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
+
+            file = "#{dir.to_s.sub(%r{/+\z}, '')}/#{spec['file-name'] || 'ruflet_recording.wav'}"
+            begin_recording.call(file)
+          end)
+        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 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)
+          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 = error_status?(response.status) ? server_error_markup(response) : 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.csrf_token = result.csrf_token
+          screen.title = result.title
+          if result.controls.empty?
+            message = response.status.to_i >= 400 ? "HTTP #{response.status} — #{screen.url}" : "Empty screen"
+            result.controls = [container(content: text(message), alignment: { x: 0, y: 0 }, expand: true)]
+          end
+          result
+        end
+
+        def transform(screen, body)
+          transformer = Transformer.new(handlers: ScreenHandlers.new(self, screen))
+          transformer.transform(body)
+        rescue StandardError => e
+          transformer.transform(error_markup(screen.url, e))
+        end
+
+        # 422 is the Rails convention for re-rendering a form with validation
+        # errors — that body is a real screen. Other error statuses carry a
+        # Rails error page (dev exception pages are a full web document).
+        def error_status?(status)
+          status = status.to_i
+          status >= 400 && status != 422
+        end
+
+        # Surface the error page's title as a compact native screen instead of
+        # trying to render the page itself.
+        def server_error_markup(response)
+          title = response.body.to_s[%r{<title>(.*?)</title>}m, 1].to_s.strip
+          title = "Server error" if title.empty?
+          <<~HTML
+            <column class="p-6 gap-2">
+              <h3>HTTP #{response.status}</h3>
+              <text class="font-semibold text-red-600">#{ERB::Util.html_escape(title)}</text>
+              <text class="text-slate-500">#{ERB::Util.html_escape(response.url)}</text>
+              <text class="text-sm text-slate-400">Check the Rails server log for the full trace.</text>
+            </column>
+          HTML
+        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(method, url, params: nil, screen: nil)
+          headers = {}
+          token = screen&.csrf_token || @screens.last&.csrf_token
+          headers["X-CSRF-Token"] = token if token && method.to_s.downcase != "get"
+          @fetcher.fetch(method, url, params: params, headers: headers)
+        rescue StandardError => e
+          RackFetcher::Response.new(status: 0, 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
+
+        def absolute_url(url)
+          url = url.to_s
+          return "" if url.empty?
+          return url if URI.parse(url).absolute?
+
+          URI.join(current_url, url).to_s
+        rescue URI::InvalidURIError
+          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/rack_fetcher.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb
new file mode 100644
index 00000000..014ee9a5
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb
@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "uri"
+require "stringio"
+
+module Ruflet
+  module Rails
+    module HtmlDsl
+      # Screen source for erb_to_native: renders Rails views by dispatching
+      # straight into the Rack app (`Rails.application`) — routing, controller,
+      # then view. This is what gives the developer a real controller: params,
+      # `before_action`s, saving a form, loading records, assigning `@ivars`,
+      # then rendering the ERB screen.
+      #
+      # It is NOT network HTTP. There is no socket and no second connection —
+      # it's a function call on the WebSocket session's own thread, so it can't
+      # stall the read loop or drop the connection the way a blocking
+      # `Net::HTTP` self-request would. Screens navigate by URL (`/native`,
+      # `/counter`), and form POSTs round-trip through the controller.
+      class RackFetcher
+        Response = Struct.new(:status, :body, :url, keyword_init: true)
+        MAX_REDIRECTS = 5
+        REDIRECT_STATUSES = [301, 302, 303, 307, 308].freeze
+
+        def initialize(app: nil)
+          @app = app
+          @cookies = {}
+        end
+
+        def fetch(method, url, params: nil, headers: {})
+          method = method.to_s.upcase
+          redirects = 0
+
+          loop do
+            status, response_headers, body = rack_app.call(build_env(method, url, params, headers))
+            store_cookies(response_headers)
+            location = header(response_headers, "location")
+
+            unless REDIRECT_STATUSES.include?(status.to_i) && location
+              return Response.new(status: status.to_i, body: read_body(body), url: url)
+            end
+
+            close_body(body)
+            redirects += 1
+            raise "Too many redirects fetching #{url}" if redirects > MAX_REDIRECTS
+
+            url = URI.join(url, location).to_s
+            # 307/308 preserve the method and body; everything else becomes a GET.
+            unless %w[307 308].include?(status.to_s)
+              method = "GET"
+              params = nil
+            end
+          end
+        end
+
+        private
+
+        def rack_app
+          @app ||= ::Rails.application
+        end
+
+        # A minimal-but-complete Rack env, built by hand so we don't depend on a
+        # particular Rack version's Rack::MockRequest location.
+        def build_env(method, url, params, headers)
+          uri = URI.parse(url)
+          query = uri.query
+          body = ""
+          content_type = nil
+
+          if params && !params.empty?
+            encoded = URI.encode_www_form(params)
+            if method == "GET"
+              query = [query, encoded].reject { |part| part.to_s.empty? }.join("&")
+            else
+              body = encoded
+              content_type = "application/x-www-form-urlencoded"
+            end
+          end
+
+          env = {
+            "REQUEST_METHOD" => method,
+            "SCRIPT_NAME" => "",
+            "PATH_INFO" => uri.path.to_s.empty? ? "/" : uri.path,
+            "QUERY_STRING" => query.to_s,
+            "SERVER_NAME" => uri.host || "localhost",
+            "SERVER_PORT" => (uri.port || (uri.scheme == "https" ? 443 : 80)).to_s,
+            "HTTP_HOST" => [uri.host, uri.port].compact.join(":"),
+            # These renders happen in-process on the server itself — a loopback
+            # request in every sense. Saying so keeps `request.remote_ip` sane and
+            # quiets dev middleware (web-console) on every screen.
+            "REMOTE_ADDR" => "127.0.0.1",
+            "rack.url_scheme" => uri.scheme || "http",
+            "rack.input" => StringIO.new(body),
+            "rack.errors" => $stderr,
+            "rack.multithread" => true,
+            "rack.multiprocess" => false,
+            "rack.run_once" => false,
+            "HTTP_ACCEPT" => "text/html",
+            "HTTP_X_RUFLET_NATIVE" => "1"
+          }
+          env["CONTENT_TYPE"] = content_type if content_type
+          env["CONTENT_LENGTH"] = body.bytesize.to_s unless body.empty?
+          env["HTTP_COOKIE"] = cookie_header unless @cookies.empty?
+          headers.each { |key, value| env["HTTP_#{key.to_s.upcase.tr('-', '_')}"] = value.to_s }
+          env
+        end
+
+        def read_body(body)
+          buffer = +""
+          body.each { |chunk| buffer << chunk.to_s }
+          buffer.force_encoding(Encoding::UTF_8) if buffer.encoding == Encoding::ASCII_8BIT
+          buffer
+        ensure
+          close_body(body)
+        end
+
+        def close_body(body)
+          body.close if body.respond_to?(:close)
+        rescue StandardError
+          nil
+        end
+
+        # Thread the Rails session cookie between sub-requests so CSRF tokens and
+        # flashes survive a form POST -> redirect -> render, like a browser.
+        def store_cookies(response_headers)
+          set_cookie = header(response_headers, "set-cookie")
+          return unless set_cookie
+
+          Array(set_cookie).each do |cookie|
+            cookie.to_s.split("\n").each do |line|
+              pair = line.split(";", 2).first.to_s.strip
+              name, value = pair.split("=", 2)
+              @cookies[name] = value if name && value
+            end
+          end
+        end
+
+        def cookie_header
+          @cookies.map { |name, value| "#{name}=#{value}" }.join("; ")
+        end
+
+        # Rack 3 lower-cases header names; earlier versions title-case them.
+        def header(response_headers, name)
+          return nil unless response_headers
+
+          response_headers[name] || response_headers[name.split("-").map(&:capitalize).join("-")] ||
+            (response_headers.respond_to?(:find) &&
+             response_headers.find { |key, _| key.to_s.downcase == name }&.last)
+        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/transformer.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
new file mode 100644
index 00000000..abb308f8
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
@@ -0,0 +1,1149 @@
+# 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,
+                            :csrf_token, 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
+
+        def initialize(handlers:)
+          @handlers = handlers
+        end
+
+        def transform(html)
+          nodes = Parser.parse(html)
+          @result = Result.new(controls: [], appbar: nil, fab: nil, bottom_nav: nil, services: [],
+                               on_load: [], title: nil, csrf_token: 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|
+            case element.tag
+            when "title"
+              @result.title = element.text if @result.title.nil?
+            when "meta"
+              @result.csrf_token = element["content"] if element["name"] == "csrf-token"
+            end
+          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, form: form)
+        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, styles, 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, form: form)
+          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(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, styles, 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"], default_method: "post")
+            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,
+            method: (element["method"] || "post").downcase,
+            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"], default_method: "post")
+            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, form:)
+          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"], default_method: "post")
+          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] = 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"], default_method: "post")
+            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"], default_method: "post")
+          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"`.
+        def action_handler(spec, default_method:)
+          method, url = parse_action(spec, default_method)
+          handlers = @handlers
+          ->(_event) { handlers.action(method: method, 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 parse_action(spec, default_method)
+          spec = spec.to_s
+          if spec =~ /\A(get|post|put|patch|delete):(.+)\z/i
+            [Regexp.last_match(1).downcase, Regexp.last_match(2)]
+          else
+            [default_method, spec]
+          end
+        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, form: nil)
+          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, default_method: "post"))
+        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/)
+
+            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..e31f1dec 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(
@@ -139,12 +139,12 @@ 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}")
+        %(mount Ruflet::Rails.web(app_file: Rails.root.join("#{entrypoint}")), at: "#{mount_path}")
       end
 
       def install_next_steps(target:, entrypoint:, client:, mount_path: "/ws")
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/protocol/web_app.rb b/packages/ruflet_rails/lib/ruflet/rails/protocol/web_app.rb
index c30009de..33e57f3c 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/protocol/web_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/protocol/web_app.rb
@@ -8,10 +8,10 @@ module Protocol
       # 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"
+      #   mount Ruflet::Rails.web(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|
+      #   mount Ruflet::Rails.web(build_dir: Rails.root.join("frontend")) { |page|
       #     CounterView.render(page)
       #   }, at: "/myfrontend"
       #
@@ -74,7 +74,7 @@ def websocket_endpoint
 
         def entrypoint
           @entrypoint_option || @app_block ||
-            raise(ArgumentError, "web_app requires one of app_file: or a block")
+            raise(ArgumentError, "Ruflet::Rails.web requires one of app_file: or a block")
         end
 
         # The web build must NOT live under public/, or Rails' static
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..5fcc2059 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
@@ -7,6 +7,15 @@ class Railtie < ::Rails::Railtie
       initializer "ruflet_rails.view_helpers" do
         ActiveSupport.on_load(:action_view) do
           include Ruflet::Rails::ViewHelpers
+          include Ruflet::Rails::HtmlDsl::ViewHelpers
+        end
+      end
+
+      # ruflet_native_request? / render_native in every controller, so an
+      # action can answer the native client in one cycle instead of two.
+      initializer "ruflet_rails.controller_helpers" do
+        ActiveSupport.on_load(:action_controller) do
+          include Ruflet::Rails::ControllerHelpers
         end
       end
 
@@ -101,24 +110,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..296889a3 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
@@ -10,7 +10,7 @@ module Rails
     # 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
+    # Ruflet::Rails.native 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 %>
@@ -49,7 +49,7 @@ def ruflet_frame(path, height: 600, width: "100%", title: "Ruflet", style: nil,
       #
       # 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.
 
diff --git a/packages/ruflet_rails/lib/ruflet/rails/web_installer.rb b/packages/ruflet_rails/lib/ruflet/rails/web_installer.rb
index 3eb9215a..de7702f6 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/web_installer.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/web_installer.rb
@@ -14,7 +14,7 @@ module Rails
     #
     #   rake ruflet:web
     #
-    # The extracted build is what Ruflet::Rails.web_app serves (its default
+    # The extracted build is what Ruflet::Rails.native serves (its default
     # build dir is <Rails.root>/frontend).
     module WebInstaller
       module_function
diff --git a/packages/ruflet_rails/lib/ruflet_rails.rb b/packages/ruflet_rails/lib/ruflet_rails.rb
index 9747a027..9e06d62a 100644
--- a/packages/ruflet_rails/lib/ruflet_rails.rb
+++ b/packages/ruflet_rails/lib/ruflet_rails.rb
@@ -11,7 +11,9 @@
 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/controller_helpers"
 require_relative "ruflet/rails/desktop_launcher"
 require_relative "ruflet/rails/protocol"
 require_relative "ruflet/rails/assets"
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/controller_helpers_test.rb b/packages/ruflet_rails/test/controller_helpers_test.rb
new file mode 100644
index 00000000..f970e541
--- /dev/null
+++ b/packages/ruflet_rails/test/controller_helpers_test.rb
@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+# render_native lets one action serve both clients: the native session gets the
+# screen straight from the POST (one Rails cycle), a browser still gets the
+# Post/Redirect/Get its reload button needs.
+class RufletControllerHelpersTest < Minitest::Test
+  class FakeRequest
+    def initialize(headers) = @headers = headers
+    attr_reader :headers
+  end
+
+  class FakeController
+    include Ruflet::Rails::ControllerHelpers
+
+    attr_reader :rendered
+
+    def initialize(native:)
+      @request = FakeRequest.new(native ? { "X-Ruflet-Native" => "1" } : {})
+      @rendered = nil
+    end
+
+    attr_reader :request
+
+    def render(template, **options)
+      @rendered = [template, options]
+    end
+  end
+
+  def test_native_requests_render_in_place
+    controller = FakeController.new(native: true)
+    redirected = false
+
+    controller.render_native(:counter, else: -> { redirected = true })
+
+    assert_equal [:counter, {}], controller.rendered
+    refute redirected, "a native request must not take the redirect"
+  end
+
+  def test_browser_requests_take_the_fallback
+    controller = FakeController.new(native: false)
+    redirected = false
+
+    controller.render_native(:counter, else: -> { redirected = true })
+
+    assert_nil controller.rendered
+    assert redirected, "a browser must still get Post/Redirect/Get"
+  end
+
+  def test_ruflet_native_request_reads_the_fetcher_marker
+    assert FakeController.new(native: true).ruflet_native_request?
+    refute FakeController.new(native: false).ruflet_native_request?
+  end
+
+  def test_browser_request_without_a_fallback_is_a_mistake
+    controller = FakeController.new(native: false)
+
+    assert_raises(ArgumentError) { controller.render_native(:counter) }
+  end
+end
diff --git a/packages/ruflet_rails/test/endpoint_declaration_test.rb b/packages/ruflet_rails/test/endpoint_declaration_test.rb
index 8d748871..58a5ba27 100644
--- a/packages/ruflet_rails/test/endpoint_declaration_test.rb
+++ b/packages/ruflet_rails/test/endpoint_declaration_test.rb
@@ -14,23 +14,23 @@ 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
 
@@ -38,7 +38,7 @@ def test_app_shorthand_delegates_to_endpoint_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
 
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..e5f896cb
--- /dev/null
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -0,0 +1,676 @@
+# 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 method+path and records every request.
+  class StubFetcher
+    Response = Ruflet::Rails::HtmlDsl::RackFetcher::Response
+
+    attr_reader :requests
+
+    def initialize(pages)
+      @pages = pages
+      @requests = []
+    end
+
+    def fetch(method, url, params: nil, headers: {})
+      @requests << { method: method.to_s, url: url, params: params, headers: headers }
+      path = URI.parse(url).path
+      body = @pages.fetch("#{method} #{path}") { @pages.fetch(path, "<text>missing #{path}</text>") }
+      body = body.call(params) if body.respond_to?(:call)
+      Response.new(status: 200, 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>" },
+      "post /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"]
+    assert_equal "post", @fetcher.requests.last["method"] || @fetcher.requests.last[:method]
+  end
+
+  def test_form_submits_tracked_field_values_with_csrf
+    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
+      "post /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 "tok-1", @fetcher.requests.last[:headers]["X-CSRF-Token"]
+    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: 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_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
+
+  # Net::HTTP returns ASCII-8BIT bodies; 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(_m, url, params: nil, headers: {})
+      body = "<text>Ruflet Native — démo</text>".dup.force_encoding(Encoding::ASCII_8BIT)
+      Ruflet::Rails::HtmlDsl::RackFetcher::Response.new(status: 200, 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 test_server_error_pages_render_a_compact_error_screen
+    fetcher = Object.new
+    def fetcher.fetch(_m, url, params: nil, headers: {})
+      Ruflet::Rails::HtmlDsl::RackFetcher::Response.new(
+        status: 500,
+        body: "<html><head><title>ActionController::RoutingError</title></head>" \
+              '<body><header><button onclick="x()">rails page</button></header></body></html>',
+        url: url
+      )
+    end
+    Ruflet::Rails.erb_to_native(@page, start_url: "https://app.test/native", fetcher: fetcher)
+
+    texts = find_all_text_values(@page.views.first)
+    assert_includes texts.join(" "), "HTTP 500"
+    assert_includes texts.join(" "), "ActionController::RoutingError"
+    refute_includes texts.join(" "), "rails page"
+  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,
+      "post /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 },
+      "post /toggle" => lambda { |_params|
+        shape = "<column><text>one</text><text>two</text></column>"
+        shape
+      }
+    )
+
+    app.action(method: "post", 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>',
+      "post /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
+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..c258793e
--- /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(method:, url:) = @actions << [method, 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 [["post", "/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..39f78b1e
--- /dev/null
+++ b/packages/ruflet_rails/test/html_dsl_test.rb
@@ -0,0 +1,824 @@
+# 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(method:, url:) = @actions << [method, 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 "tok123", result.csrf_token
+    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 [["post", "/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 [["delete", "/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 [["post", "/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 [["post", "/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 "post", form[:method]
+    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 [["post", "/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..9d162627 100644
--- a/packages/ruflet_rails/test/install_generator_test.rb
+++ b/packages/ruflet_rails/test/install_generator_test.rb
@@ -70,7 +70,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,7 +85,7 @@ 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
 
@@ -100,7 +100,7 @@ def test_web_install_mounts_only_the_generated_app_at_ruflet
 
       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"'
+                      'mount Ruflet::Rails.web(app_file: Rails.root.join("app/views/ruflet/main.rb")), at: "/ruflet"'
       refute_includes routes, "/products"
     end
   end
diff --git a/packages/ruflet_rails/test/install_support_test.rb b/packages/ruflet_rails/test/install_support_test.rb
index d994e720..a01e89eb 100644
--- a/packages/ruflet_rails/test/install_support_test.rb
+++ b/packages/ruflet_rails/test/install_support_test.rb
@@ -40,7 +40,7 @@ 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
@@ -50,7 +50,7 @@ def test_default_entrypoint_path_uses_ruflet_views_root
   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
+    assert_equal 'mount Ruflet::Rails.web(app_file: Rails.root.join("app/views/ruflet/main.rb")), at: "/ruflet"', route
     refute_includes route, "/products"
   end
 
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/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/web_app_test.rb b/packages/ruflet_rails/test/web_app_test.rb
index 16705be4..bb777ebe 100644
--- a/packages/ruflet_rails/test/web_app_test.rb
+++ b/packages/ruflet_rails/test/web_app_test.rb
@@ -32,7 +32,7 @@ def with_build_dir
   end
 
   def app_for(dir)
-    Ruflet::Rails.web_app(build_dir: dir) { |page| page.title = "Mounted" }
+    Ruflet::Rails.web(build_dir: dir) { |page| page.title = "Mounted" }
   end
 
   def test_index_base_href_follows_the_mount_point
@@ -141,7 +141,7 @@ def test_blocks_path_traversal
   end
 
   def test_missing_build_reports_actionable_error
-    app = Ruflet::Rails.web_app(build_dir: "/nonexistent/build") { |page| page.title = "x" }
+    app = Ruflet::Rails.web(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
@@ -151,7 +151,7 @@ def test_missing_build_reports_actionable_error
   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" }
+      app = Ruflet::Rails.web(build_dir: public_app) { |page| page.title = "x" }
 
       error = assert_raises(ArgumentError) do
         app.call("PATH_INFO" => "/", "SCRIPT_NAME" => "/m", "REQUEST_METHOD" => "GET")
@@ -165,7 +165,7 @@ def test_default_build_dir_is_outside_public
       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" }
+      app = Ruflet::Rails.web { |page| page.title = "Default" }
       status, _headers, body = app.call("PATH_INFO" => "/", "SCRIPT_NAME" => "/x", "REQUEST_METHOD" => "GET")
 
       assert_equal 200, status
@@ -234,7 +234,7 @@ def test_websocket_upgrade_runs_the_ruflet_protocol_under_the_mount
 
   def test_web_app_rejects_multiple_entrypoint_sources
     assert_raises(ArgumentError) do
-      Ruflet::Rails.web_app(app_file: "b.rb") { |page| page }
+      Ruflet::Rails.web(app_file: "b.rb") { |page| page }
     end
   end
 

From 8b5ce8f1bfb431148e3694744ada5b408a5febff Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Wed, 5 Aug 2026 15:48:38 -0400
Subject: [PATCH 02/30] Support iOS device and simulator installs

---
 README.md                                     |  7 ++
 .../ruflet/lib/ruflet/cli/build_command.rb    | 68 +++++++++++++++++++
 packages/ruflet/test/update_command_test.rb   | 21 +++++-
 3 files changed, 94 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 2db81e81..9f8d46d0 100644
--- a/README.md
+++ b/README.md
@@ -396,6 +396,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 +407,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 3488b0bb..12409e03 100644
--- a/packages/ruflet/lib/ruflet/cli/build_command.rb
+++ b/packages/ruflet/lib/ruflet/cli/build_command.rb
@@ -155,6 +155,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
@@ -182,6 +201,19 @@ def command_install(args)
           return 1
         end
 
+        # `flutter install` counts macOS and Chrome alongside mobile devices.
+        # That makes an otherwise unambiguous install fail whenever a simulator
+        # is booted on a development Mac. Keep an explicit --device untouched,
+        # but when it is omitted select the only connected iOS target compatible
+        # with the newest app bundle (iphoneos vs iphonesimulator).
+        device_id ||= compatible_ios_install_device(
+          client_dir,
+          flutter: tools[:flutter],
+          env: command_env,
+          platform: install_platform,
+          verbose: !!verbose
+        )
+
         install_args = ["install"]
         install_args += ["-d", device_id] if device_id
         install_args << "-v" if verbose
@@ -367,6 +399,42 @@ def ios_simulator_device_id?(device_id)
         device_id.match?(/\A[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}\z/i)
       end
 
+      def compatible_ios_install_device(client_dir, flutter:, env:, platform:, verbose: false)
+        return nil unless platform == "ios"
+
+        simulator = File.join(client_dir, "build", "ios", "iphonesimulator", "Runner.app", "Runner")
+        physical = File.join(client_dir, "build", "ios", "iphoneos", "Runner.app", "Runner")
+        artifacts = { simulator: simulator, physical: physical }.select { |_kind, path| File.file?(path) }
+        return nil if artifacts.empty?
+
+        devices = connected_flutter_devices(flutter, env).select do |device|
+          device["targetPlatform"].to_s == "ios" && device.fetch("isSupported", true)
+        end
+        ordered_kinds = artifacts.sort_by { |_kind, path| File.mtime(path) }.reverse.map(&:first)
+        kind, candidates = ordered_kinds.filter_map do |candidate_kind|
+          matching = devices.select { |device| !!device["emulator"] == (candidate_kind == :simulator) }
+          [candidate_kind, matching] if matching.one?
+        end.first
+        return nil unless kind
+
+        selected = candidates.first
+        build_log(verbose, "selected #{kind} device #{selected['id']} (#{selected['name']})")
+        selected["id"].to_s
+      rescue StandardError => e
+        build_log(verbose, "automatic iOS device selection skipped: #{e.class}: #{e.message}")
+        nil
+      end
+
+      def connected_flutter_devices(flutter, env)
+        output, status = Open3.capture2e(env, flutter, "devices", "--machine")
+        return [] unless status.success?
+
+        parsed = JSON.parse(output)
+        parsed.is_a?(Array) ? parsed : []
+      rescue JSON::ParserError
+        []
+      end
+
       def ios_app_signed?(app_path)
         system("/usr/bin/codesign", "-vv", app_path, out: File::NULL, err: File::NULL)
       end
diff --git a/packages/ruflet/test/update_command_test.rb b/packages/ruflet/test/update_command_test.rb
index ba813e5d..f7f9ed20 100644
--- a/packages/ruflet/test/update_command_test.rb
+++ b/packages/ruflet/test/update_command_test.rb
@@ -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", "--dart-define", "RUFLET_EMBEDDED_PROJECT=ruflet"], calls.first[:args]
+      assert_equal ["flutter", "build", "ios", "--codesign", "--target", "lib/main.self.dart", "--dart-define", "RUFLET_EMBEDDED_PROJECT=ruflet"], calls.first[:args]
+      assert_equal ["flutter", "build", "ios", "--simulator", "--target", "lib/main.self.dart", "--dart-define", "RUFLET_EMBEDDED_PROJECT=ruflet"], 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,6 +943,18 @@ 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") }
+      builder.define_singleton_method(:connected_flutter_devices) do |_flutter, _env|
+        [
+          {
+            "name" => "iPhone 16 Pro",
+            "id" => "6C2A608D-7753-49FC-AEDD-A1C1F4D23C1E",
+            "targetPlatform" => "ios",
+            "emulator" => true,
+            "isSupported" => true
+          },
+          { "name" => "macOS", "id" => "macos", "targetPlatform" => "darwin-arm64", "emulator" => false }
+        ]
+      end
 
       calls = []
       builder.define_singleton_method(:system) do |_env, *_args, chdir: nil|
@@ -951,7 +965,7 @@ def test_command_install_syncs_ios_build_outputs_and_runs_flutter_install
       code = builder.command_install([])
 
       assert_equal 0, code
-      assert_equal ["flutter", "install"], calls.first[:args]
+      assert_equal ["flutter", "install", "-d", "6C2A608D-7753-49FC-AEDD-A1C1F4D23C1E"], calls.first[:args]
       assert_equal client_dir, calls.first[:chdir]
       assert File.exist?(File.join(client_dir, "build", "ios", "iphonesimulator", "Runner.app", "Info.plist"))
     ensure
@@ -1005,6 +1019,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 +1043,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
 

From f95a7863b44a06b88026e644032a89550b1a5977 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Wed, 5 Aug 2026 16:09:16 -0400
Subject: [PATCH 03/30] Format extension event payload values

---
 packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb | 4 ++--
 packages/ruflet_rails/test/html_app_test.rb                 | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

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
index eb92a685..18032e9c 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -358,7 +358,7 @@ def run_service(spec)
         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
+                    data["value"] || data[:value] || (data.one? ? data.values.first : data)
                   else
                     data
                   end
@@ -378,7 +378,7 @@ def handle_control_event(spec, event)
           return unless target
 
           message = spec["message"]
-          message = "#{spec['prefix']}#{format_service_value(data)}" if message.to_s.empty?
+          message = "#{spec['prefix']}#{format_service_value(value)}" if message.to_s.empty?
           show_service_result(message, target: target)
         end
 
diff --git a/packages/ruflet_rails/test/html_app_test.rb b/packages/ruflet_rails/test/html_app_test.rb
index e5f896cb..f834cbfd 100644
--- a/packages/ruflet_rails/test/html_app_test.rb
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -332,7 +332,7 @@ def test_studio_style_extension_event_updates_an_erb_status_target
     rive = @page.get_control("demo-rive")
     event = Struct.new(:data).new({ "state" => "playing" })
     assert rive.emit("state_change", event)
-    assert_equal "State: state: playing", @page.get_control("rive-status").props["value"]
+    assert_equal "State: playing", @page.get_control("rive-status").props["value"]
   end
 
   def test_service_result_can_update_inline_like_ruflet_studio

From 69cd91e6f1194f905057fb94c0fc0b6e01d7815e Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Wed, 5 Aug 2026 16:24:38 -0400
Subject: [PATCH 04/30] Let Flutter choose the install device

---
 .../ruflet/lib/ruflet/cli/build_command.rb    | 49 -------------------
 packages/ruflet/test/update_command_test.rb   | 15 +-----
 2 files changed, 1 insertion(+), 63 deletions(-)

diff --git a/packages/ruflet/lib/ruflet/cli/build_command.rb b/packages/ruflet/lib/ruflet/cli/build_command.rb
index 12409e03..75b0dfd7 100644
--- a/packages/ruflet/lib/ruflet/cli/build_command.rb
+++ b/packages/ruflet/lib/ruflet/cli/build_command.rb
@@ -201,19 +201,6 @@ def command_install(args)
           return 1
         end
 
-        # `flutter install` counts macOS and Chrome alongside mobile devices.
-        # That makes an otherwise unambiguous install fail whenever a simulator
-        # is booted on a development Mac. Keep an explicit --device untouched,
-        # but when it is omitted select the only connected iOS target compatible
-        # with the newest app bundle (iphoneos vs iphonesimulator).
-        device_id ||= compatible_ios_install_device(
-          client_dir,
-          flutter: tools[:flutter],
-          env: command_env,
-          platform: install_platform,
-          verbose: !!verbose
-        )
-
         install_args = ["install"]
         install_args += ["-d", device_id] if device_id
         install_args << "-v" if verbose
@@ -399,42 +386,6 @@ def ios_simulator_device_id?(device_id)
         device_id.match?(/\A[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}\z/i)
       end
 
-      def compatible_ios_install_device(client_dir, flutter:, env:, platform:, verbose: false)
-        return nil unless platform == "ios"
-
-        simulator = File.join(client_dir, "build", "ios", "iphonesimulator", "Runner.app", "Runner")
-        physical = File.join(client_dir, "build", "ios", "iphoneos", "Runner.app", "Runner")
-        artifacts = { simulator: simulator, physical: physical }.select { |_kind, path| File.file?(path) }
-        return nil if artifacts.empty?
-
-        devices = connected_flutter_devices(flutter, env).select do |device|
-          device["targetPlatform"].to_s == "ios" && device.fetch("isSupported", true)
-        end
-        ordered_kinds = artifacts.sort_by { |_kind, path| File.mtime(path) }.reverse.map(&:first)
-        kind, candidates = ordered_kinds.filter_map do |candidate_kind|
-          matching = devices.select { |device| !!device["emulator"] == (candidate_kind == :simulator) }
-          [candidate_kind, matching] if matching.one?
-        end.first
-        return nil unless kind
-
-        selected = candidates.first
-        build_log(verbose, "selected #{kind} device #{selected['id']} (#{selected['name']})")
-        selected["id"].to_s
-      rescue StandardError => e
-        build_log(verbose, "automatic iOS device selection skipped: #{e.class}: #{e.message}")
-        nil
-      end
-
-      def connected_flutter_devices(flutter, env)
-        output, status = Open3.capture2e(env, flutter, "devices", "--machine")
-        return [] unless status.success?
-
-        parsed = JSON.parse(output)
-        parsed.is_a?(Array) ? parsed : []
-      rescue JSON::ParserError
-        []
-      end
-
       def ios_app_signed?(app_path)
         system("/usr/bin/codesign", "-vv", app_path, out: File::NULL, err: File::NULL)
       end
diff --git a/packages/ruflet/test/update_command_test.rb b/packages/ruflet/test/update_command_test.rb
index f7f9ed20..114d0b17 100644
--- a/packages/ruflet/test/update_command_test.rb
+++ b/packages/ruflet/test/update_command_test.rb
@@ -943,19 +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") }
-      builder.define_singleton_method(:connected_flutter_devices) do |_flutter, _env|
-        [
-          {
-            "name" => "iPhone 16 Pro",
-            "id" => "6C2A608D-7753-49FC-AEDD-A1C1F4D23C1E",
-            "targetPlatform" => "ios",
-            "emulator" => true,
-            "isSupported" => true
-          },
-          { "name" => "macOS", "id" => "macos", "targetPlatform" => "darwin-arm64", "emulator" => false }
-        ]
-      end
-
       calls = []
       builder.define_singleton_method(:system) do |_env, *_args, chdir: nil|
         calls << { env: _env, args: _args, chdir: chdir }
@@ -965,7 +952,7 @@ def test_command_install_syncs_ios_build_outputs_and_runs_flutter_install
       code = builder.command_install([])
 
       assert_equal 0, code
-      assert_equal ["flutter", "install", "-d", "6C2A608D-7753-49FC-AEDD-A1C1F4D23C1E"], calls.first[:args]
+      assert_equal ["flutter", "install"], calls.first[:args]
       assert_equal client_dir, calls.first[:chdir]
       assert File.exist?(File.join(client_dir, "build", "ios", "iphonesimulator", "Runner.app", "Info.plist"))
     ensure

From 0a897be0dde6c3b49787b3dfb451366234eb6afc Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Wed, 5 Aug 2026 16:25:19 -0400
Subject: [PATCH 05/30] Request microphone before audio recording

---
 .../lib/ruflet/rails/html_dsl/html_app.rb     | 35 +++++++------
 packages/ruflet_rails/test/html_app_test.rb   | 50 +++++++++++++++++++
 2 files changed, 71 insertions(+), 14 deletions(-)

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
index 18032e9c..c1fc3839 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -501,39 +501,42 @@ def run_audio_recorder(action, spec)
         end
 
         # Recording needs a writable file path *on the device*, and the mic
-        # permission has to be granted first. This mirrors Studio's flow exactly:
-        # resolve the documents dir → check `has_permission` → record to a .wav in
-        # that dir with the wav encoder. A multi-step async chain, not a single
-        # fire-and-forget invoke (which is why "Start" did nothing before).
+        # 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|
-            # First call raises the OS microphone prompt and blocks until the
-            # person answers it, so this cannot use the 10s default.
-            recorder.has_permission(timeout: interactive_timeout(spec), on_result: lambda do |*out|
-              allowed, perm_error = out
+            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 allowed
+              unless microphone_permission_granted?(permission_status)
                 next show_service_result("Microphone permission was not granted.",
                                          title: "Audio recorder", target: target)
               end
 
-              show_service_result("Recording → #{file}", title: "Audio recorder", target: target)
               recorder.start_recording(
                 output_path: file, configuration: configuration, upload: spec["upload"],
-                # Starting capture can itself surface the OS prompt when the
-                # permission was only just granted.
                 timeout: interactive_timeout(spec),
                 on_result: lambda do |*rec|
-                  next unless service_error?(rec[1])
+                  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
 
-                  show_service_result("Start error: #{rec[1]}", title: "Audio recorder failed", target: target)
+                  show_service_result("Recording → #{file}", title: "Audio recorder", target: target)
                 end
               )
             end)
@@ -555,6 +558,10 @@ def start_audio_recording(recorder, spec)
           end)
         end
 
+        def microphone_permission_granted?(status)
+          status == true || status.to_s == "granted"
+        end
+
         def toggle_sensor(type, action, spec)
           type = type.tr("-", "_")
           sensor = @page.service(
diff --git a/packages/ruflet_rails/test/html_app_test.rb b/packages/ruflet_rails/test/html_app_test.rb
index f834cbfd..73de7fa5 100644
--- a/packages/ruflet_rails/test/html_app_test.rb
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -371,6 +371,56 @@ def test_generic_service_button_invokes_any_registered_service_method
     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 → /device/Documents/voice.wav",
+                 @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_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|

From 017ffa30d45fe4812db667390532b06b8ac08d44 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Wed, 5 Aug 2026 16:34:45 -0400
Subject: [PATCH 06/30] Animate and replay audio recordings

---
 .../lib/ruflet/rails/html_dsl/html_app.rb     | 61 ++++++++++++++++++-
 packages/ruflet_rails/test/html_app_test.rb   | 55 ++++++++++++++++-
 2 files changed, 114 insertions(+), 2 deletions(-)

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
index c1fc3839..03dc1802 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -489,6 +489,8 @@ def run_audio_recorder(action, spec)
           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
@@ -536,7 +538,8 @@ def start_audio_recording(recorder, spec)
                                              title: "Audio recorder failed", target: target)
                   end
 
-                  show_service_result("Recording → #{file}", title: "Audio recorder", target: target)
+                  set_audio_recording_state(spec, recording: true)
+                  show_service_result("Recording… Speak now.", title: "Audio recorder", target: target)
                 end
               )
             end)
@@ -562,6 +565,62 @@ 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 = @page.service(
+            :audio,
+            id: "ruflet_rails_recording_playback",
+            src: path,
+            autoplay: true,
+            release_mode: "stop",
+            on_state_change: lambda do |event|
+              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|
+              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(
diff --git a/packages/ruflet_rails/test/html_app_test.rb b/packages/ruflet_rails/test/html_app_test.rb
index 73de7fa5..88d2107e 100644
--- a/packages/ruflet_rails/test/html_app_test.rb
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -398,7 +398,7 @@ def test_audio_recorder_requests_microphone_then_records_in_documents
     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 → /device/Documents/voice.wav",
+    assert_equal "Recording… Speak now.",
                  @page.get_control("recorder-status").props["value"]
   end
 
@@ -421,6 +421,59 @@ def test_audio_recorder_does_not_claim_recording_when_native_start_returns_false
                  @page.get_control("recorder-status").props["value"]
   end
 
+  def test_audio_recorder_animates_while_recording_and_autoplays_after_stop
+    @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|
+      result = if control.type == "permissionhandler"
+                 "granted"
+               elsif method == "stop_recording"
+                 "/device/Documents/ruflet_recording.wav"
+               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.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"]
+  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|

From 7ddfb472a8a69fed4980a44805dddc5bdb2ef46f Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Wed, 5 Aug 2026 16:53:01 -0400
Subject: [PATCH 07/30] Prune undeclared client capabilities

---
 README.md                                     |  10 +-
 .../ruflet/lib/ruflet/cli/build_command.rb    |  66 ++++++++-
 .../ruflet/test/build_package_pruning_test.rb | 133 ++++++++++++++++++
 packages/ruflet/test/update_command_test.rb   |   2 +-
 4 files changed, 204 insertions(+), 7 deletions(-)
 create mode 100644 packages/ruflet/test/build_package_pruning_test.rb

diff --git a/README.md b/README.md
index 9f8d46d0..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:
diff --git a/packages/ruflet/lib/ruflet/cli/build_command.rb b/packages/ruflet/lib/ruflet/cli/build_command.rb
index 75b0dfd7..7d713f68 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
@@ -1572,6 +1581,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)
 
@@ -1766,8 +1776,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
@@ -1777,6 +1785,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}"))
 
@@ -1790,6 +1804,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
@@ -1859,8 +1879,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)
@@ -1924,7 +1942,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",
@@ -1949,6 +1966,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)
@@ -2173,6 +2195,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 114d0b17..8d7614d0 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

From 6e673ccd8c1623a32ed3ae7f182df23cbd8d97b0 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Wed, 5 Aug 2026 17:04:04 -0400
Subject: [PATCH 08/30] Keep repeated Rails recordings active

---
 .../lib/ruflet/rails/html_dsl/html_app.rb     | 51 ++++++++++++++-----
 packages/ruflet_rails/test/html_app_test.rb   | 23 ++++++++-
 2 files changed, 60 insertions(+), 14 deletions(-)

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
index 03dc1802..ed48bc52 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -545,19 +545,40 @@ def start_audio_recording(recorder, spec)
             end)
           end
 
-          return begin_recording.call(explicit) unless explicit.empty?
-
-          show_service_result("Preparing recording…", title: "Audio recorder", target: target)
-          @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
+          release_recording_playback do
+            next begin_recording.call(explicit) unless explicit.empty?
+
+            show_service_result("Preparing recording…", title: "Audio recorder", target: target)
+            @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
 
-            file = "#{dir.to_s.sub(%r{/+\z}, '')}/#{spec['file-name'] || 'ruflet_recording.wav'}"
-            begin_recording.call(file)
+              requested_name = spec["file-name"].to_s
+              file_name = requested_name.empty? ? next_recording_file_name : requested_name
+              file = "#{dir.to_s.sub(%r{/+\z}, '')}/#{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
+
+          previous.release(on_result: lambda do |_result, _error|
+            @page.remove_service(previous)
+            after_release.call
           end)
         end
 
@@ -597,6 +618,8 @@ def update_control_property(id, **props)
 
         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",
@@ -604,6 +627,8 @@ def autoplay_recording(path, target:)
             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
@@ -613,6 +638,8 @@ def autoplay_recording(path, target:)
               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)
diff --git a/packages/ruflet_rails/test/html_app_test.rb b/packages/ruflet_rails/test/html_app_test.rb
index 88d2107e..b5d4e431 100644
--- a/packages/ruflet_rails/test/html_app_test.rb
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -422,14 +422,18 @@ def test_audio_recorder_does_not_claim_recording_when_native_start_returns_false
   end
 
   def test_audio_recorder_animates_while_recording_and_autoplays_after_stop
+    recording_paths = []
     @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|
       result = if control.type == "permissionhandler"
                  "granted"
+               elsif method == "start_recording"
+                 recording_paths << args["output_path"]
+                 true
                elsif method == "stop_recording"
-                 "/device/Documents/ruflet_recording.wav"
+                 recording_paths.last
                else
                  true
                end
@@ -464,7 +468,7 @@ def test_audio_recorder_animates_while_recording_and_autoplays_after_stop
     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.wav", player.props["src"]
+    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"]
@@ -472,6 +476,21 @@ def test_audio_recorder_animates_while_recording_and_autoplays_after_stop
     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 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

From 730175830d5080a316b78003adf09181243934c4 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Wed, 5 Aug 2026 17:11:34 -0400
Subject: [PATCH 09/30] Do not block recording on player release

---
 .../ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb   | 9 +++++----
 packages/ruflet_rails/test/html_app_test.rb              | 4 ++++
 2 files changed, 9 insertions(+), 4 deletions(-)

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
index ed48bc52..8009907b 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -576,10 +576,11 @@ def release_recording_playback(&after_release)
           @recording_playback = nil
           return after_release.call unless previous
 
-          previous.release(on_result: lambda do |_result, _error|
-            @page.remove_service(previous)
-            after_release.call
-          end)
+          # 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)
diff --git a/packages/ruflet_rails/test/html_app_test.rb b/packages/ruflet_rails/test/html_app_test.rb
index b5d4e431..cc340253 100644
--- a/packages/ruflet_rails/test/html_app_test.rb
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -427,6 +427,10 @@ def test_audio_recorder_animates_while_recording_and_autoplays_after_stop
       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"
                  "granted"
                elsif method == "start_recording"

From cd98d5007fb5b10329f4c9013cb2ad3701816e64 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Wed, 5 Aug 2026 17:32:09 -0400
Subject: [PATCH 10/30] Reuse recorder preflight results

---
 .../lib/ruflet/rails/html_dsl/html_app.rb     | 43 +++++++++++++------
 packages/ruflet_rails/test/html_app_test.rb   |  6 +++
 2 files changed, 36 insertions(+), 13 deletions(-)

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
index 8009907b..0eef0730 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -513,18 +513,7 @@ def start_audio_recording(recorder, spec)
           explicit = (spec["output-path"] || spec["path"]).to_s
 
           begin_recording = lambda do |file|
-            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
-
+            start_native_recording = lambda do
               recorder.start_recording(
                 output_path: file, configuration: configuration, upload: spec["upload"],
                 timeout: interactive_timeout(spec),
@@ -542,6 +531,27 @@ def start_audio_recording(recorder, spec)
                   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
 
@@ -549,6 +559,12 @@ def start_audio_recording(recorder, spec)
             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(
@@ -557,9 +573,10 @@ def start_audio_recording(recorder, spec)
                 )
               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 = "#{dir.to_s.sub(%r{/+\z}, '')}/#{file_name}"
+              file = "#{@recording_documents_directory}/#{file_name}"
               begin_recording.call(file)
             end)
           end
diff --git a/packages/ruflet_rails/test/html_app_test.rb b/packages/ruflet_rails/test/html_app_test.rb
index cc340253..ac1626a5 100644
--- a/packages/ruflet_rails/test/html_app_test.rb
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -423,7 +423,10 @@ def test_audio_recorder_does_not_claim_recording_when_native_start_returns_false
 
   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|
@@ -432,6 +435,7 @@ def test_audio_recorder_animates_while_recording_and_autoplays_after_stop
       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"]
@@ -486,6 +490,8 @@ def test_audio_recorder_animates_while_recording_and_autoplays_after_stop
       "/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"]

From 78c8410991b0fcdebfc4a61367049b31f86801ad Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Wed, 5 Aug 2026 22:42:37 -0400
Subject: [PATCH 11/30] Align Ruflet Rails endpoint documentation

---
 packages/ruflet_rails/README.md                         | 2 +-
 packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb  | 2 +-
 packages/ruflet_rails/test/endpoint_declaration_test.rb | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/ruflet_rails/README.md b/packages/ruflet_rails/README.md
index 52ae9322..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.native(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.
diff --git a/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb b/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
index 296889a3..ea8bb59f 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
@@ -160,7 +160,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)
diff --git a/packages/ruflet_rails/test/endpoint_declaration_test.rb b/packages/ruflet_rails/test/endpoint_declaration_test.rb
index 58a5ba27..569e6431 100644
--- a/packages/ruflet_rails/test/endpoint_declaration_test.rb
+++ b/packages/ruflet_rails/test/endpoint_declaration_test.rb
@@ -34,7 +34,7 @@ def test_endpoint_rejects_more_than_one_source
     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")

From f9675fdd6b339eee7a02bf1f42b450c893d2478c Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Thu, 6 Aug 2026 22:51:16 -0400
Subject: [PATCH 12/30] Keep declarative service markup out of native invoke
 arguments

Attributes like class/icon/variant/on-load and the on-*-target family are
markup the DSL consumes itself. Passing them through as invoke arguments
produced calls the client could not match to a control's method signature,
which is why the ERB audio buttons did nothing.
---
 .../lib/ruflet/rails/html_dsl/html_app.rb           | 13 +++++++++++++
 1 file changed, 13 insertions(+)

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
index 0eef0730..a7c9f60b 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -438,10 +438,22 @@ def mount_services(result)
                               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 result-target capture-target preview-target id disabled
+          class icon variant on-load file-name output-path path configuration upload encoder
         ].freeze
 
+        # 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,
@@ -849,6 +861,7 @@ 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 DECLARED_EVENT_ATTRIBUTE.match?(key)
             next if value.nil?
 
             args[key.tr("-", "_")] = value

From 7f2649ab41f6ead95f70cf48b5b1922717b5d032 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Fri, 7 Aug 2026 12:35:03 -0400
Subject: [PATCH 13/30] Let native screens be named by path instead of by URL
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

erb_to_native dispatches every screen in-process, so a screen URL never
addresses anything reachable: the client opens one route, the WebSocket,
and the rest is a function call. Requiring an absolute start_url made that
look like a second HTTP endpoint, and pinned it to whatever host was
hardcoded in backend_url — a phone on the LAN then rendered against
127.0.0.1, and a mismatched host answered 403 from host authorization.

A path start_url now takes its host from the connection the client
actually made, so the same route serves localhost and the LAN unchanged.
Absolute URLs keep working and still name the host verbatim.

Also stop putting the default port in Host; a browser omits it, and Rails
echoes the header back through url_for and redirects.
---
 .../ruflet_rails/lib/ruflet/rails/html_dsl.rb |  10 +-
 .../lib/ruflet/rails/html_dsl/html_app.rb     |  16 +-
 .../lib/ruflet/rails/html_dsl/rack_fetcher.rb |  71 +++++++-
 packages/ruflet_rails/test/html_app_test.rb   |  65 +++++++
 .../ruflet_rails/test/rack_fetcher_test.rb    | 162 ++++++++++++++++++
 5 files changed, 319 insertions(+), 5 deletions(-)
 create mode 100644 packages/ruflet_rails/test/rack_fetcher_test.rb

diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
index 52f2d449..bffa208f 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
@@ -27,7 +27,15 @@ module HtmlDsl
     # controller.
     #
     #   # app/views/ruflet/main.rb  (runs in the /ws session)
-    #   Ruflet.run { |page| Ruflet::Rails.erb_to_native(page, start_url: "#{Ruflet::Rails.backend_url}/native") }
+    #   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; production uses the in-process
     # RackFetcher by default.
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
index a7c9f60b..bf909560 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -1265,13 +1265,25 @@ def error_markup(url, error)
           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?
 
-          URI.join(current_url, url).to_s
-        rescue URI::InvalidURIError
+          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
 
diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb
index 014ee9a5..c2e880c4 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb
@@ -22,13 +22,19 @@ class RackFetcher
         MAX_REDIRECTS = 5
         REDIRECT_STATUSES = [301, 302, 303, 307, 308].freeze
 
-        def initialize(app: nil)
+        # The base used for screens declared as plain paths. Only ever a
+        # stand-in for a host we could not learn from the connection.
+        FALLBACK_BASE_URL = "http://localhost"
+
+        def initialize(app: nil, base_url: nil)
           @app = app
+          @base_url = base_url
           @cookies = {}
         end
 
         def fetch(method, url, params: nil, headers: {})
           method = method.to_s.upcase
+          url = absolute(url)
           redirects = 0
 
           loop do
@@ -59,6 +65,57 @@ def rack_app
           @app ||= ::Rails.application
         end
 
+        # Screens are normally declared as paths ("/native"), because none of
+        # this travels over the network and a host would be fiction. Rails still
+        # reads Host off the env though — `ActionDispatch::HostAuthorization`
+        # answers 403 for one it does not recognise — so the host has to be real
+        # even when the request is not. The host the client dialed on this very
+        # WebSocket is accepted by definition, which a hardcoded one is not.
+        def absolute(url)
+          url = url.to_s
+          return url if url.empty?
+          return url if URI.parse(url).absolute?
+
+          URI.join(base_url, url).to_s
+        rescue URI::InvalidURIError, URI::BadURIError
+          url
+        end
+
+        def base_url
+          @base_url ||= websocket_base_url || configured_base_url || FALLBACK_BASE_URL
+        end
+
+        def websocket_base_url
+          env = websocket_env
+          return nil unless env
+
+          host = env["HTTP_X_FORWARDED_HOST"] || env["HTTP_HOST"]
+          return nil if host.to_s.strip.empty?
+
+          scheme = (env["HTTP_X_FORWARDED_PROTO"] || env["rack.url_scheme"] || "http").to_s.split(",").first.to_s.strip
+          scheme = "http" if scheme.empty?
+          "#{scheme}://#{host}"
+        end
+
+        # Loaded before Protocol in ruflet_rails.rb, and usable with no Rails at
+        # all (the gem's own tests do that), so resolve both lazily.
+        def websocket_env
+          return nil unless defined?(::Ruflet::Rails::Protocol::Context)
+
+          ::Ruflet::Rails::Protocol::Context.current_env
+        rescue StandardError
+          nil
+        end
+
+        def configured_base_url
+          return nil unless defined?(::Ruflet::Rails.config)
+
+          configured = ::Ruflet::Rails.config.backend_url.to_s.strip
+          configured.empty? ? nil : configured.sub(%r{/+\z}, "")
+        rescue StandardError
+          nil
+        end
+
         # A minimal-but-complete Rack env, built by hand so we don't depend on a
         # particular Rack version's Rack::MockRequest location.
         def build_env(method, url, params, headers)
@@ -84,7 +141,7 @@ def build_env(method, url, params, headers)
             "QUERY_STRING" => query.to_s,
             "SERVER_NAME" => uri.host || "localhost",
             "SERVER_PORT" => (uri.port || (uri.scheme == "https" ? 443 : 80)).to_s,
-            "HTTP_HOST" => [uri.host, uri.port].compact.join(":"),
+            "HTTP_HOST" => host_header(uri),
             # These renders happen in-process on the server itself — a loopback
             # request in every sense. Saying so keeps `request.remote_ip` sane and
             # quiets dev middleware (web-console) on every screen.
@@ -105,6 +162,16 @@ def build_env(method, url, params, headers)
           env
         end
 
+        # URI always fills in a port, but a browser omits the default one — and
+        # so must we: Rails echoes Host back in `url_for`, redirects and
+        # canonical links, where a stray ":443" would show up.
+        def host_header(uri)
+          return "localhost" if uri.host.to_s.empty?
+          return uri.host if uri.port.nil? || uri.port == uri.default_port
+
+          "#{uri.host}:#{uri.port}"
+        end
+
         def read_body(body)
           buffer = +""
           body.each { |chunk| buffer << chunk.to_s }
diff --git a/packages/ruflet_rails/test/html_app_test.rb b/packages/ruflet_rails/test/html_app_test.rb
index ac1626a5..7c944ad2 100644
--- a/packages/ruflet_rails/test/html_app_test.rb
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -805,4 +805,69 @@ def test_state_written_on_one_screen_is_visible_on_the_next
     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
+
+  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/rack_fetcher_test.rb b/packages/ruflet_rails/test/rack_fetcher_test.rb
new file mode 100644
index 00000000..efe4cd7c
--- /dev/null
+++ b/packages/ruflet_rails/test/rack_fetcher_test.rb
@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+# Screens are dispatched into the Rack app in-process. A screen may therefore be
+# named by path alone — nothing here goes over the network, so there is no host
+# to know. Rails still reads Host off the env, so the fetcher has to supply one
+# the app will accept.
+class RufletRackFetcherTest < Minitest::Test
+  # Records the env it was called with and answers a fixed response.
+  class StubRackApp
+    attr_reader :envs
+
+    def initialize(status: 200, headers: {}, body: "<text>ok</text>")
+      @status = status
+      @headers = headers
+      @body = body
+      @envs = []
+    end
+
+    def call(env)
+      @envs << env
+      [@status, @headers, [@body]]
+    end
+  end
+
+  def teardown
+    Ruflet::Rails.config.backend_url = nil
+  end
+
+  def fetch(app, url, base_url: nil, env: nil, method: "GET", **kwargs)
+    fetcher = Ruflet::Rails::HtmlDsl::RackFetcher.new(app: app, base_url: base_url)
+    if env
+      Ruflet::Rails::Protocol::Context.with_env(env) { fetcher.fetch(method, url, **kwargs) }
+    else
+      fetcher.fetch(method, url, **kwargs)
+    end
+  end
+
+  def ws_env(host, scheme: "http")
+    { "HTTP_HOST" => host, "rack.url_scheme" => scheme }
+  end
+
+  def test_path_url_takes_its_host_from_the_live_websocket_connection
+    app = StubRackApp.new
+    fetch(app, "/native", env: ws_env("192.168.1.50:3000"))
+
+    env = app.envs.first
+    assert_equal "/native", env["PATH_INFO"]
+    assert_equal "192.168.1.50:3000", env["HTTP_HOST"]
+    assert_equal "192.168.1.50", env["SERVER_NAME"]
+    assert_equal "3000", env["SERVER_PORT"]
+    assert_equal "http", env["rack.url_scheme"]
+  end
+
+  def test_path_url_honours_the_forwarded_host_and_scheme
+    app = StubRackApp.new
+    fetch(app, "/native", env: { "HTTP_X_FORWARDED_HOST" => "app.example.com",
+                                 "HTTP_X_FORWARDED_PROTO" => "https,http",
+                                 "HTTP_HOST" => "internal:3000" })
+
+    env = app.envs.first
+    assert_equal "app.example.com", env["HTTP_HOST"]
+    assert_equal "https", env["rack.url_scheme"]
+    assert_equal "443", env["SERVER_PORT"]
+  end
+
+  def test_path_url_falls_back_to_the_configured_backend_url_off_connection
+    Ruflet::Rails.config.backend_url = "https://configured.example.com/"
+    app = StubRackApp.new
+    fetch(app, "/native")
+
+    assert_equal "configured.example.com", app.envs.first["HTTP_HOST"]
+    assert_equal "https", app.envs.first["rack.url_scheme"]
+  end
+
+  def test_the_live_connection_wins_over_a_stale_configured_backend_url
+    Ruflet::Rails.config.backend_url = "http://127.0.0.1:3000"
+    app = StubRackApp.new
+    fetch(app, "/native", env: ws_env("192.168.1.50:3000"))
+
+    assert_equal "192.168.1.50:3000", app.envs.first["HTTP_HOST"]
+  end
+
+  def test_path_url_falls_back_to_localhost_with_no_connection_and_no_config
+    app = StubRackApp.new
+    fetch(app, "/native")
+
+    assert_equal "localhost", app.envs.first["HTTP_HOST"]
+  end
+
+  def test_an_explicit_base_url_overrides_everything
+    Ruflet::Rails.config.backend_url = "http://127.0.0.1:3000"
+    app = StubRackApp.new
+    fetch(app, "/native", base_url: "http://explicit.test", env: ws_env("192.168.1.50:3000"))
+
+    assert_equal "explicit.test", app.envs.first["HTTP_HOST"]
+  end
+
+  def test_an_absolute_url_is_used_verbatim_and_ignores_the_connection
+    app = StubRackApp.new
+    fetch(app, "https://given.example.com/native", env: ws_env("192.168.1.50:3000"))
+
+    env = app.envs.first
+    assert_equal "given.example.com", env["HTTP_HOST"]
+    assert_equal "https", env["rack.url_scheme"]
+    assert_equal "/native", env["PATH_INFO"]
+  end
+
+  def test_the_response_reports_the_resolved_absolute_url
+    response = fetch(StubRackApp.new, "/native", env: ws_env("192.168.1.50:3000"))
+
+    assert_equal "http://192.168.1.50:3000/native", response.url
+  end
+
+  def test_a_path_url_still_follows_redirects
+    app = Object.new
+    app.define_singleton_method(:envs) { @envs ||= [] }
+    app.define_singleton_method(:call) do |env|
+      envs << env
+      if envs.length == 1
+        [302, { "location" => "/native/counter" }, [""]]
+      else
+        [200, {}, ["<text>done</text>"]]
+      end
+    end
+
+    response = fetch(app, "/native", env: ws_env("192.168.1.50:3000"))
+
+    assert_equal 200, response.status
+    assert_equal ["/native", "/native/counter"], app.envs.map { |e| e["PATH_INFO"] }
+    assert_equal ["192.168.1.50:3000", "192.168.1.50:3000"], app.envs.map { |e| e["HTTP_HOST"] }
+  end
+
+  def test_query_strings_and_params_survive_path_resolution
+    app = StubRackApp.new
+    fetch(app, "/search?scope=all", env: ws_env("host.test"), params: { "q" => "ada" })
+
+    env = app.envs.first
+    assert_equal "/search", env["PATH_INFO"]
+    assert_includes env["QUERY_STRING"], "scope=all"
+    assert_includes env["QUERY_STRING"], "q=ada"
+  end
+
+  def test_post_params_become_a_form_encoded_body
+    app = StubRackApp.new
+    fetch(app, "/native/form", method: "POST", env: ws_env("host.test"),
+                               params: { "name" => "Ada Lovelace" })
+
+    env = app.envs.first
+    assert_equal "POST", env["REQUEST_METHOD"]
+    assert_equal "application/x-www-form-urlencoded", env["CONTENT_TYPE"]
+    assert_equal "name=Ada+Lovelace", env["rack.input"].read
+  end
+
+  def test_it_marks_the_request_as_a_native_one
+    app = StubRackApp.new
+    fetch(app, "/native", env: ws_env("host.test"))
+
+    assert_equal "1", app.envs.first["HTTP_X_RUFLET_NATIVE"]
+  end
+end

From 95ce6aeb124bc4e8c2a498efd17e85a0e9b07d94 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Fri, 7 Aug 2026 13:02:40 -0400
Subject: [PATCH 14/30] Resolve media URLs against the client's host, and
 reject host-less ones
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Screens are dispatched in-process, but the client loads media itself over
HTTP, so a src/url naming a Rails-hosted file was the one URL still going
out unresolved: a root-relative "/assets/logo.png" reached the client as
a path it could only look for among its own bundled assets. Resolve those
against the connection host. External URLs, data: URIs, protocol-relative
URLs and bare asset names are left alone.

Also reject a screen URL with a scheme but no host. "localhost:3000"
parses as scheme "localhost" with opaque "3000", which passed through
as absolute and dispatched to "/" — rendering the root route while
appearing to ignore start_url.
---
 .../lib/ruflet/rails/html_dsl/html_app.rb     | 14 +++-
 .../lib/ruflet/rails/html_dsl/rack_fetcher.rb | 15 +++-
 .../lib/ruflet/rails/html_dsl/transformer.rb  | 29 +++++++-
 packages/ruflet_rails/test/html_app_test.rb   | 74 +++++++++++++++++++
 .../ruflet_rails/test/rack_fetcher_test.rb    | 12 +++
 5 files changed, 139 insertions(+), 5 deletions(-)

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
index bf909560..cd88d519 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -1174,12 +1174,24 @@ def render_result(screen, response)
         end
 
         def transform(screen, body)
-          transformer = Transformer.new(handlers: ScreenHandlers.new(self, screen))
+          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
+
         # 422 is the Rails convention for re-rendering a form with validation
         # errors — that body is a real screen. Other error statuses carry a
         # Rails error page (dev exception pages are a full web document).
diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb
index c2e880c4..af385138 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb
@@ -74,13 +74,26 @@ def rack_app
         def absolute(url)
           url = url.to_s
           return url if url.empty?
-          return url if URI.parse(url).absolute?
+
+          uri = URI.parse(url)
+          # A host, not merely a scheme: "localhost:3000" parses as scheme
+          # "localhost" with opaque "3000" and no path, so treating it as
+          # absolute would dispatch it to "/" and quietly render the wrong
+          # screen. Say so instead.
+          return url if uri.host
+          raise ArgumentError, malformed_url_message(url) if uri.scheme && !url.start_with?("/")
 
           URI.join(base_url, url).to_s
         rescue URI::InvalidURIError, URI::BadURIError
           url
         end
 
+        def malformed_url_message(url)
+          "Ruflet screen URL #{url.inspect} has no host. Use a path (\"/native\"), " \
+            "which takes its host from the client's connection, or a full URL " \
+            "including the scheme (\"http://localhost:3000/native\")."
+        end
+
         def base_url
           @base_url ||= websocket_base_url || configured_base_url || FALLBACK_BASE_URL
         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
index abb308f8..b8b931d0 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
@@ -70,8 +70,30 @@ class Transformer
                                top left right bottom blur aspect_ratio clip_behavior gradient
                                visible animate].freeze
 
-        def initialize(handlers:)
+        # 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)
@@ -266,7 +288,7 @@ def build_image(element, styles)
           props[:semantics_label] = element["alt"] if element["alt"]
           props.merge!(styles.slice(:width, :height, :border_radius, :fit, :opacity,
                                     :aspect_ratio, :rotate, :scale))
-          image(element["src"], **props)
+          image(resolve_asset_url(element["src"]), **props)
         end
 
         def build_list(element, styles, form:)
@@ -636,7 +658,7 @@ def build_chip(element, form:)
         def build_avatar(element)
           styles = Styles.parse(element["class"])
           props = element_props(element, except: %w[src alt])
-          props[:foreground_image_src] = element["src"] if element["src"]
+          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")
@@ -1068,6 +1090,7 @@ def element_props(element, except: [])
             # 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
diff --git a/packages/ruflet_rails/test/html_app_test.rb b/packages/ruflet_rails/test/html_app_test.rb
index 7c944ad2..11b4877a 100644
--- a/packages/ruflet_rails/test/html_app_test.rb
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -862,6 +862,80 @@ def test_a_path_start_url_keeps_query_strings_on_relative_links
     assert_equal "/search?q=ada", @fetcher.requests.last[:url]
   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>")
diff --git a/packages/ruflet_rails/test/rack_fetcher_test.rb b/packages/ruflet_rails/test/rack_fetcher_test.rb
index efe4cd7c..47763e9d 100644
--- a/packages/ruflet_rails/test/rack_fetcher_test.rb
+++ b/packages/ruflet_rails/test/rack_fetcher_test.rb
@@ -153,6 +153,18 @@ def test_post_params_become_a_form_encoded_body
     assert_equal "name=Ada+Lovelace", env["rack.input"].read
   end
 
+  # "localhost:3000" parses as scheme "localhost" with opaque "3000" and no
+  # path. Passed through as absolute it would dispatch to "/" and render
+  # whatever the root route is, which looks like the app ignoring start_url.
+  def test_a_host_less_scheme_is_rejected_instead_of_silently_becoming_root
+    error = assert_raises(ArgumentError) do
+      fetch(StubRackApp.new, "localhost:3000", env: ws_env("host.test"))
+    end
+
+    assert_includes error.message, "has no host"
+    assert_includes error.message, "/native"
+  end
+
   def test_it_marks_the_request_as_a_native_one
     app = StubRackApp.new
     fetch(app, "/native", env: ws_env("host.test"))

From 17264cd2fe55ffb5f5161293f190b827fea23808 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Fri, 7 Aug 2026 14:36:45 -0400
Subject: [PATCH 15/30] Resolve native screens by convention instead of by
 declaration

A native app has one public route, the WebSocket; the screens behind it
are reached only from inside a session. Declaring a Rails route per screen
therefore builds a routing table nothing outside the app may use. Resolve
screen paths to controller actions by convention instead, from a catch-all
the Railtie appends and constrains to Ruflet sessions, so an app's
routes.rb carries only its own routes and the WebSocket mount.

Extra path segments are tried as part of the action name before becoming
params, which is what lets one convention cover both an action nested
under another (counter/increment) and a parameterised screen (device/:id).

This keeps the request cycle. It does not yet address handlers running as
Ruby in the session rather than as a controller action per tap.
---
 .../lib/ruflet/rails/native_screens.rb        | 133 ++++++++++++++++++
 .../ruflet_rails/lib/ruflet/rails/railtie.rb  |  15 ++
 packages/ruflet_rails/lib/ruflet_rails.rb     |   1 +
 .../ruflet_rails/test/native_screens_test.rb  | 116 +++++++++++++++
 4 files changed, 265 insertions(+)
 create mode 100644 packages/ruflet_rails/lib/ruflet/rails/native_screens.rb
 create mode 100644 packages/ruflet_rails/test/native_screens_test.rb

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..a90709dc
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/native_screens.rb
@@ -0,0 +1,133 @@
+# 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/camera      -> NativeController#device, params[:id] = "camera"
+    #
+    # 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.
+    #
+    # Dispatch still goes through Rails' middleware and the controller itself,
+    # so `session`, `flash`, CSRF, `before_action` and layouts behave exactly as
+    # they do for a normal request. What is skipped is only the routing table.
+    module NativeScreens
+      # Actions to try for the root of a feature folder, in order.
+      INDEX_ACTIONS = %w[home index show].freeze
+
+      module_function
+
+      # Only a Ruflet session may reach a screen. A browser hitting the same
+      # path gets whatever the app's own routes say — normally a 404 — so
+      # screens are not a second, undeclared public surface.
+      def native_request?(request)
+        request.get_header("HTTP_X_RUFLET_NATIVE").to_s == "1"
+      end
+
+      # "/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
+
+      # Rack app the Railtie installs as a catch-all. Resolving here rather than
+      # in the routing table is the whole point: no screen needs declaring.
+      class Dispatcher
+        def call(env)
+          request = ::ActionDispatch::Request.new(env)
+          screen = NativeScreens.resolve(request.path)
+          return not_found(request.path) unless screen
+
+          assign_params(env, screen[:params])
+          screen[:controller].action(screen[:action]).call(env)
+        end
+
+        private
+
+        # Extra path segments arrive as params, so a screen can be
+        # parameterised without a route declaring the segment's name.
+        def assign_params(env, values)
+          return if values.empty?
+
+          params = env["action_dispatch.request.path_parameters"] || {}
+          params = params.merge(id: values.first, screen_params: values)
+          env["action_dispatch.request.path_parameters"] = params
+        end
+
+        def not_found(path)
+          body = "No Ruflet screen for #{path}"
+          [404, { "content-type" => "text/plain", "content-length" => body.bytesize.to_s }, [body]]
+        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 5fcc2059..a5815e0c 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
@@ -19,6 +19,21 @@ class Railtie < ::Rails::Railtie
         end
       end
 
+      # Screens resolve by convention instead of by declaration, so an app's
+      # routes.rb holds only its own routes plus the one WebSocket mount. The
+      # catch-all is appended (it runs after every declared route, never
+      # shadowing one) and is constrained to Ruflet sessions, so it adds no
+      # public surface: a browser on the same path still falls through to the
+      # app's own routing, normally a 404.
+      initializer "ruflet_rails.native_screens" do |app|
+        app.routes.append do
+          match "/*ruflet_screen",
+                to: Ruflet::Rails::NativeScreens::Dispatcher.new,
+                via: :all,
+                constraints: ->(request) { Ruflet::Rails::NativeScreens.native_request?(request) }
+        end
+      end
+
       initializer "ruflet_rails.desktop_launcher", after: :load_config_initializers do |_app|
         next unless defined?(::Rails.root)
 
diff --git a/packages/ruflet_rails/lib/ruflet_rails.rb b/packages/ruflet_rails/lib/ruflet_rails.rb
index 9e06d62a..d3bd30b3 100644
--- a/packages/ruflet_rails/lib/ruflet_rails.rb
+++ b/packages/ruflet_rails/lib/ruflet_rails.rb
@@ -14,6 +14,7 @@
 require_relative "ruflet/rails/html_dsl"
 require_relative "ruflet/rails/view_helpers"
 require_relative "ruflet/rails/controller_helpers"
+require_relative "ruflet/rails/native_screens"
 require_relative "ruflet/rails/desktop_launcher"
 require_relative "ruflet/rails/protocol"
 require_relative "ruflet/rails/assets"
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..db5303e0
--- /dev/null
+++ b/packages/ruflet_rails/test/native_screens_test.rb
@@ -0,0 +1,116 @@
+# 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.
+  class StubRequest
+    def initialize(headers) = @headers = headers
+    def get_header(name) = @headers[name]
+  end
+
+  def test_only_a_ruflet_session_may_reach_a_screen
+    assert Ruflet::Rails::NativeScreens.native_request?(StubRequest.new("HTTP_X_RUFLET_NATIVE" => "1"))
+    refute Ruflet::Rails::NativeScreens.native_request?(StubRequest.new({}))
+    refute Ruflet::Rails::NativeScreens.native_request?(StubRequest.new("HTTP_X_RUFLET_NATIVE" => "0"))
+  end
+end

From 0dafb367276a5446ff9f774dc17a634c78da9d82 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Fri, 7 Aug 2026 14:51:37 -0400
Subject: [PATCH 16/30] WIP: render ERB screens without a request cycle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

TemplateSource puts the ERB file in the slot a Ruflet Ruby app file
occupies: templates render through ActionView directly, a tap calls a
method on the developer's own controller in the session, and state lives
on that controller instance for the life of the connection. No routing, no
middleware, no Rack env — verified zero process_action.action_controller
notifications across a full navigation.

Opt-in via template_mode: the default still goes through RackFetcher, so
nothing existing changes behaviour.

Incomplete: re-render after an action does not reach the screen body, form
submission does not round-trip, and a controller calling redirect_to
raises because there is no request to redirect.
---
 .../ruflet_rails/lib/ruflet/rails/html_dsl.rb |   6 +-
 .../ruflet/rails/html_dsl/template_source.rb  | 168 ++++++++++++++++++
 2 files changed, 172 insertions(+), 2 deletions(-)
 create mode 100644 packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb

diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
index bffa208f..8f2762f0 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
@@ -4,6 +4,7 @@
 require_relative "html_dsl/styles"
 require_relative "html_dsl/transformer"
 require_relative "html_dsl/rack_fetcher"
+require_relative "html_dsl/template_source"
 require_relative "html_dsl/control_diff"
 require_relative "html_dsl/html_app"
 require_relative "html_dsl/view_helpers"
@@ -39,8 +40,9 @@ module HtmlDsl
     #
     # A `fetcher:` can be injected for tests; production uses the in-process
     # RackFetcher by default.
-    def erb_to_native(page, **opts)
-      HtmlDsl::HtmlApp.new(page, **opts).start
+    def erb_to_native(page, start_url: "/", template_mode: false, layout: nil, **opts)
+      opts[:fetcher] ||= HtmlDsl::TemplateSource.new(layout: layout) if template_mode
+      HtmlDsl::HtmlApp.new(page, start_url: start_url, **opts).start
     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..e768963c
--- /dev/null
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
@@ -0,0 +1,168 @@
+# 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.
+      #
+      # It satisfies the same interface as RackFetcher, so HtmlApp's
+      # navigation, diffing, forms and services all work unchanged.
+      class TemplateSource
+        Response = RackFetcher::Response
+
+        def initialize(view_paths: nil, layout: nil)
+          @view_paths = view_paths
+          @layout = layout
+          @controllers = {}
+        end
+
+        def fetch(method, url, params: nil, headers: {})
+          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])
+
+          Response.new(status: 200, body: render(screen, controller), url: url)
+        rescue StandardError => e
+          Response.new(status: 500, 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)
+          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/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 }
+          values["feature"] = path_params.first if path_params.respond_to?(:first) && path_params.first
+          (form_params || {}).each { |key, value| values[key.to_s] = value }
+          controller.ruflet_screen_params =
+            if defined?(::ActiveSupport::HashWithIndifferentAccess)
+              ::ActiveSupport::HashWithIndifferentAccess.new(values)
+            else
+              values
+            end
+        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.
+        def render(screen, controller)
+          name = template_for(screen)
+          raise "No template for #{screen[:controller]}##{screen[:action]}" unless name
+
+          # Partials in a screen ("render \"nav\"") resolve relative to the
+          # controller's own view folder, the way they do under a controller.
+          lookup_context.prefixes = [controller_path(screen[:controller])]
+          view = ActionView::Base
+                 .with_empty_template_cache
+                 .new(lookup_context, assigns_for(controller), nil)
+          view.render(template: name, layout: @layout)
+        end
+
+        def template_for(screen)
+          prefix = controller_path(screen[:controller])
+          candidates_for(screen[:action]).each do |action|
+            name = "#{prefix}/#{action}"
+            return name if lookup_context.exists?(action, [prefix])
+          end
+          nil
+        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
+
+        def lookup_context
+          @lookup_context ||= ActionView::LookupContext.new(@view_paths || ::ActionController::Base.view_paths)
+        end
+
+        def missing(url, path)
+          Response.new(status: 404, 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
+
+          def params
+            @ruflet_screen_params ||= {}
+          end
+
+          # There is no request, so a native screen is all there is.
+          def ruflet_native_request?
+            true
+          end
+        end
+      end
+    end
+  end
+end

From 2e47f12a8ec3204e883b76ae7c8e6091009d6f28 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Fri, 7 Aug 2026 14:55:07 -0400
Subject: [PATCH 17/30] Render every screen through ActionView, with helpers
 and partials

Screens reach for the app's own helpers as readily as the DSL's tags, and
render partials relative to their controller's view folder, so both have
to work without a controller behind them: mix in the controller's _helpers
module, and give each render a lookup context carrying its own prefix.

The view class is built once per session rather than per render. A
template compiles its partials into the class that rendered it, so a fresh
class each time leaves those methods behind on the previous one, which is
why every screen with a partial failed on its second render.
---
 .../ruflet/rails/html_dsl/template_source.rb  | 29 ++++++++++++++-----
 1 file changed, 22 insertions(+), 7 deletions(-)

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
index e768963c..d3e5c35c 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
@@ -88,12 +88,16 @@ def render(screen, controller)
           name = template_for(screen)
           raise "No template for #{screen[:controller]}##{screen[:action]}" unless name
 
-          # Partials in a screen ("render \"nav\"") resolve relative to the
-          # controller's own view folder, the way they do under a controller.
-          lookup_context.prefixes = [controller_path(screen[:controller])]
-          view = ActionView::Base
-                 .with_empty_template_cache
-                 .new(lookup_context, assigns_for(controller), nil)
+          # A fresh lookup context per render: partials in a screen
+          # ("render \"nav\"") resolve relative to the controller's own view
+          # folder, and a shared, mutated one leaks compiled partial methods
+          # between view instances.
+          lookup = build_lookup_context([controller_path(screen[:controller])])
+          view = view_class.new(lookup, 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
           view.render(template: name, layout: @layout)
         end
 
@@ -125,8 +129,19 @@ def assigns_for(controller)
           end
         end
 
+        # One view class for the session: a template compiles its partials into
+        # the class that rendered it, so a fresh class per render leaves those
+        # methods behind on the previous one.
+        def view_class
+          @view_class ||= ActionView::Base.with_empty_template_cache
+        end
+
+        def build_lookup_context(prefixes = [])
+          ActionView::LookupContext.new(@view_paths || ::ActionController::Base.view_paths, {}, prefixes)
+        end
+
         def lookup_context
-          @lookup_context ||= ActionView::LookupContext.new(@view_paths || ::ActionController::Base.view_paths)
+          @lookup_context ||= build_lookup_context
         end
 
         def missing(url, path)

From dbfbefeda864713ab5ac619e792fa19f242d67fd Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Fri, 7 Aug 2026 15:02:45 -0400
Subject: [PATCH 18/30] Skip the rebuild when an action leaves the screen
 unchanged
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Re-rendering a screen parses its markup and rebuilds the whole control
tree, which measures at roughly 0.41ms against 0.24ms for the ERB render
that produced it — the transform, not the template, is what a tap costs.
When an action returns byte-identical markup none of that work can change
anything, and neither can the diff it feeds, so return early.
---
 .../lib/ruflet/rails/html_dsl/html_app.rb             | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

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
index cd88d519..9bfb2084 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -14,7 +14,7 @@ module HtmlDsl
       # field values and render the response.
       class HtmlApp
         Screen = Struct.new(:url, :view, :route, :root, :fields, :csrf_token, :title,
-                            :appbar_sig, :fab_sig, :nav_sig, :body, keyword_init: true)
+                            :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.
@@ -1102,6 +1102,15 @@ def current_service_request?(token)
         # 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

From dbe39d03dc93ff5561b0d5c85db2a0d1b8fe8c9a Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Fri, 7 Aug 2026 21:34:24 -0400
Subject: [PATCH 19/30] Render the compiled template directly, and reload it
 when it changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

view.render re-resolved the template and fired the render instrumentation
on every tap, and a screen re-renders on every tap: 0.223ms against
0.055ms for calling the compiled template. Full fetch drops from 0.218ms
to 0.067ms.

Holding a compiled template would otherwise defeat template reloading, so
re-resolve when the file's mtime changes. Reloading did not in fact work
here before either — nothing in this path runs inside Rails' reloader, so
an edited screen was never invalidated — which the mtime check now fixes
by clearing the process-wide resolver cache with it.

That clearing must happen only once a file has really changed. Discarding
the view class on a first resolve strands the partials already compiled
into it, which took 28 of the 37 screens down.
---
 .../ruflet/rails/html_dsl/template_source.rb  | 78 +++++++++++++++----
 1 file changed, 62 insertions(+), 16 deletions(-)

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
index d3e5c35c..6a03bba2 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
@@ -30,6 +30,8 @@ def initialize(view_paths: nil, layout: nil)
           @view_paths = view_paths
           @layout = layout
           @controllers = {}
+          @templates = {}
+          @lookups = {}
         end
 
         def fetch(method, url, params: nil, headers: {})
@@ -84,32 +86,76 @@ def assign_params(controller, form_params, path_params)
 
         # 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)
-          name = template_for(screen)
-          raise "No template for #{screen[:controller]}##{screen[:action]}" unless name
-
-          # A fresh lookup context per render: partials in a screen
-          # ("render \"nav\"") resolve relative to the controller's own view
-          # folder, and a shared, mutated one leaks compiled partial methods
-          # between view instances.
-          lookup = build_lookup_context([controller_path(screen[:controller])])
-          view = view_class.new(lookup, assigns_for(controller), nil)
+          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
-          view.render(template: name, layout: @layout)
+
+          return view.render(template: "#{prefix}/#{action}", layout: @layout) if @layout
+
+          template_for_render(prefix, action).render(view, {})
         end
 
-        def template_for(screen)
-          prefix = controller_path(screen[:controller])
-          candidates_for(screen[:action]).each do |action|
-            name = "#{prefix}/#{action}"
-            return name if lookup_context.exists?(action, [prefix])
-          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 = {}
+          @view_class = nil
+        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("_")

From 7c1792c486bb1ba74e453515b5a6b15cfc3e2863 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Fri, 7 Aug 2026 21:42:47 -0400
Subject: [PATCH 20/30] Stop screen renders narrating themselves into the log
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A partial still goes 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 wrote a line per tap for work
that is not a request and has nothing to report.

This is noise removal, not speed: measured against an unsilenced render it
is 0.272ms versus 0.260ms, so the subscriber was costing nothing worth
reclaiming. Silencing is per-thread, so a concurrent web request keeps its
own logging.
---
 .../ruflet/rails/html_dsl/template_source.rb  | 21 +++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

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
index 6a03bba2..cffbc231 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
@@ -101,9 +101,26 @@ def render(screen, controller)
           helpers = screen[:controller].try(:_helpers)
           view.extend(helpers) if helpers
 
-          return view.render(template: "#{prefix}/#{action}", layout: @layout) if @layout
+          # 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 do
+            next view.render(template: "#{prefix}/#{action}", layout: @layout) if @layout
+
+            template_for_render(prefix, action).render(view, {})
+          end
+        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)
 
-          template_for_render(prefix, action).render(view, {})
+          logger.silence(::Logger::ERROR, &block)
+        rescue StandardError
+          yield
         end
 
         # Holding the compiled template would otherwise defeat template

From 45f006bdac34ae4147937f9be507d0bcedd7db65 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Fri, 7 Aug 2026 21:50:17 -0400
Subject: [PATCH 21/30] Keep session working without a request behind it

Dropping the request cycle took Rails' session with it, which pushed every
app onto instance variables and made a working controller something you
had to rewrite to adopt this. Hold a session per connection instead and
expose it as session, so session[:count] keeps its meaning: it outlives
the tap, like a Rails session, but is held by the connection rather than a
cookie.
---
 .../ruflet/rails/html_dsl/template_source.rb  | 26 ++++++++++++++-----
 1 file changed, 19 insertions(+), 7 deletions(-)

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
index cffbc231..c154a703 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
@@ -30,6 +30,7 @@ def initialize(view_paths: nil, layout: nil)
           @view_paths = view_paths
           @layout = layout
           @controllers = {}
+          @session = indifferent({})
           @templates = {}
           @lookups = {}
         end
@@ -60,6 +61,10 @@ def controller_for(klass)
         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
 
@@ -76,12 +81,13 @@ def assign_params(controller, form_params, path_params)
           Array(path_params).each_with_index { |value, index| values[index.zero? ? "id" : "param#{index}"] = value }
           values["feature"] = path_params.first if path_params.respond_to?(:first) && path_params.first
           (form_params || {}).each { |key, value| values[key.to_s] = value }
-          controller.ruflet_screen_params =
-            if defined?(::ActiveSupport::HashWithIndifferentAccess)
-              ::ActiveSupport::HashWithIndifferentAccess.new(values)
-            else
-              values
-            end
+          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
@@ -229,7 +235,13 @@ def failure_markup(path, error)
         # Gives a plain controller instance the few things a screen needs
         # without a request behind it.
         module ScreenContext
-          attr_writer :ruflet_screen_params
+          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 ||= {}

From dbcc7686305db10cc2b16c837f22c048dac898a0 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Fri, 7 Aug 2026 22:31:30 -0400
Subject: [PATCH 22/30] Run a screen's own action before re-rendering it

An action like #counter_increment changes state and then re-renders
counter.html.erb, but the ivars that template reads are assigned by
#counter, which never ran. The screen redrew from whatever the previous
visit left behind, so every tap worked and the number never moved.

Run the screen's own action too when it differs from the one the tap
named, so the template always reads current state.
---
 .../lib/ruflet/rails/html_dsl/template_source.rb           | 7 +++++++
 1 file changed, 7 insertions(+)

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
index c154a703..c0051e22 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
@@ -44,6 +44,13 @@ def fetch(method, url, params: nil, headers: {})
           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(status: 200, body: render(screen, controller), url: url)
         rescue StandardError => e
           Response.new(status: 500, body: failure_markup(path, e), url: url)

From 43455c1fe4a53503cebc5c194838977f8855d0ca Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Fri, 7 Aug 2026 22:47:02 -0400
Subject: [PATCH 23/30] Leave only the three ways to build a Ruflet app on
 Rails
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ruflet::Rails now offers erb_to_native, native_shell and native, and
nothing else. Removed with the Flutter web frontend: Protocol::WebApp and
Ruflet::Rails.web, WebInstaller and the ruflet:web rake task, the
ruflet_frame helper that embedded that mount in an iframe, and the
generator's web client paths.

RackFetcher goes too. It dispatched screens through Rails routing and
middleware, which is the request-per-tap that erb_to_native no longer
does, so it was a second way to mean the same thing that reintroduced
what the design removed. TemplateSource owns Response now, and
NativeScreens keeps only resolve — its Rack dispatcher and the catch-all
route the Railtie appended existed solely for that HTTP path.

The view class is now shared process-wide rather than per session.
ActionView caches compiled templates process-wide and a template compiles
into the class that first rendered it, so a class per session handed the
second connection a template that believed it was already compiled: every
shared screen raised NoMethodError. Two clients at once was enough.
---
 .../ruflet/install/install_generator.rb       |  29 +-
 packages/ruflet_rails/lib/ruflet/rails.rb     |  34 ---
 .../ruflet_rails/lib/ruflet/rails/html_dsl.rb |   8 +-
 .../lib/ruflet/rails/html_dsl/html_app.rb     |   9 +-
 .../lib/ruflet/rails/html_dsl/rack_fetcher.rb | 233 ---------------
 .../ruflet/rails/html_dsl/template_source.rb  |  26 +-
 .../lib/ruflet/rails/install_support.rb       |  16 --
 .../lib/ruflet/rails/native_screens.rb        |  36 ---
 .../ruflet_rails/lib/ruflet/rails/protocol.rb |   1 -
 .../lib/ruflet/rails/protocol/web_app.rb      | 243 ----------------
 .../ruflet_rails/lib/ruflet/rails/railtie.rb  |  28 +-
 .../lib/ruflet/rails/view_helpers.rb          |  30 --
 .../lib/ruflet/rails/web_installer.rb         | 137 ---------
 packages/ruflet_rails/lib/ruflet_rails.rb     |   1 -
 .../test/endpoint_declaration_test.rb         |  12 -
 packages/ruflet_rails/test/html_app_test.rb   |   6 +-
 .../test/install_generator_test.rb            |  37 ---
 .../ruflet_rails/test/install_support_test.rb |   9 -
 .../ruflet_rails/test/native_screens_test.rb  |   9 -
 .../ruflet_rails/test/rack_fetcher_test.rb    | 174 -----------
 .../ruflet_rails/test/view_helpers_test.rb    |  41 +--
 packages/ruflet_rails/test/web_app_test.rb    | 272 ------------------
 .../ruflet_rails/test/web_installer_test.rb   |  94 ------
 23 files changed, 31 insertions(+), 1454 deletions(-)
 delete mode 100644 packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb
 delete mode 100644 packages/ruflet_rails/lib/ruflet/rails/protocol/web_app.rb
 delete mode 100644 packages/ruflet_rails/lib/ruflet/rails/web_installer.rb
 delete mode 100644 packages/ruflet_rails/test/rack_fetcher_test.rb
 delete mode 100644 packages/ruflet_rails/test/web_app_test.rb
 delete mode 100644 packages/ruflet_rails/test/web_installer_test.rb

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 ffa164c8..1fc682f8 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."
 
@@ -36,17 +35,6 @@ def mount_websocket
         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)
-        contents = File.read(routes)
-        return if contents.include?("Ruflet::Rails.web(")
-
-        route Ruflet::Rails::InstallSupport.web_route_snippet(entrypoint: entrypoint_path)
-      end
-
       def add_desktop_flag_to_binstubs
         return unless desktop_requested?
 
@@ -58,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
@@ -86,13 +73,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"
@@ -102,20 +87,10 @@ 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"
         exit_code = Dir.chdir(destination_root) { Ruflet::CLI.command_update(["desktop"]) }
diff --git a/packages/ruflet_rails/lib/ruflet/rails.rb b/packages/ruflet_rails/lib/ruflet/rails.rb
index 96749b8e..0acc78b9 100644
--- a/packages/ruflet_rails/lib/ruflet/rails.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails.rb
@@ -49,39 +49,5 @@ def native(app_file = nil, &block)
       Protocol::Runner.new(&block).build_endpoint
     end
 
-    # Self-contained web frontend (the Flutter web build plus the Ruflet
-    # WebSocket on one mount), for browser clients. Serves the build with
-    # <base href> rewritten to the mount point; routes stay routing-only:
-    #
-    #   # a standalone Ruflet app file (MyApp.new.run), loaded per session:
-    #   mount Ruflet::Rails.web(app_file: "app/ruflet/showcase/main.rb"), at: "/showcase"
-    #
-    #   # or a custom block:
-    #   mount Ruflet::Rails.web { |page| MyHome.render(page) }, at: "/app"
-    #
-    # One of app_file: or a block is required.
-    def web(app_file: nil, build_dir: nil, &app_block)
-      sources = [app_file, app_block].compact
-      raise ArgumentError, "web accepts only one of app_file: or a block" if sources.length > 1
-      raise ArgumentError, "web 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/html_dsl.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
index 8f2762f0..679099a3 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
@@ -3,7 +3,6 @@
 require_relative "html_dsl/parser"
 require_relative "html_dsl/styles"
 require_relative "html_dsl/transformer"
-require_relative "html_dsl/rack_fetcher"
 require_relative "html_dsl/template_source"
 require_relative "html_dsl/control_diff"
 require_relative "html_dsl/html_app"
@@ -38,10 +37,9 @@ module HtmlDsl
     # configuring anything. A full URL is still accepted, and then names the
     # host verbatim.
     #
-    # A `fetcher:` can be injected for tests; production uses the in-process
-    # RackFetcher by default.
-    def erb_to_native(page, start_url: "/", template_mode: false, layout: nil, **opts)
-      opts[:fetcher] ||= HtmlDsl::TemplateSource.new(layout: layout) if template_mode
+    # A `fetcher:` can be injected for tests.
+    def erb_to_native(page, start_url: "/", layout: nil, **opts)
+      opts[:fetcher] ||= HtmlDsl::TemplateSource.new(layout: layout)
       HtmlDsl::HtmlApp.new(page, start_url: start_url, **opts).start
     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
index 9bfb2084..20545e29 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -48,11 +48,10 @@ def start
           self
         end
 
-        # Screens run through Rails routing + controllers, dispatched in-process
-        # against the running app (a function call, not network HTTP), so the
-        # whole session stays on its single WebSocket thread.
+        # 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
-          RackFetcher.new
+          TemplateSource.new
         end
 
         # --- navigation ---------------------------------------------------------
@@ -1273,7 +1272,7 @@ def request(method, url, params: nil, screen: nil)
           headers["X-CSRF-Token"] = token if token && method.to_s.downcase != "get"
           @fetcher.fetch(method, url, params: params, headers: headers)
         rescue StandardError => e
-          RackFetcher::Response.new(status: 0, body: error_markup(url, e), url: url)
+          TemplateSource::Response.new(status: 0, body: error_markup(url, e), url: url)
         end
 
         def error_markup(url, error)
diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb
deleted file mode 100644
index af385138..00000000
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/rack_fetcher.rb
+++ /dev/null
@@ -1,233 +0,0 @@
-# frozen_string_literal: true
-
-require "uri"
-require "stringio"
-
-module Ruflet
-  module Rails
-    module HtmlDsl
-      # Screen source for erb_to_native: renders Rails views by dispatching
-      # straight into the Rack app (`Rails.application`) — routing, controller,
-      # then view. This is what gives the developer a real controller: params,
-      # `before_action`s, saving a form, loading records, assigning `@ivars`,
-      # then rendering the ERB screen.
-      #
-      # It is NOT network HTTP. There is no socket and no second connection —
-      # it's a function call on the WebSocket session's own thread, so it can't
-      # stall the read loop or drop the connection the way a blocking
-      # `Net::HTTP` self-request would. Screens navigate by URL (`/native`,
-      # `/counter`), and form POSTs round-trip through the controller.
-      class RackFetcher
-        Response = Struct.new(:status, :body, :url, keyword_init: true)
-        MAX_REDIRECTS = 5
-        REDIRECT_STATUSES = [301, 302, 303, 307, 308].freeze
-
-        # The base used for screens declared as plain paths. Only ever a
-        # stand-in for a host we could not learn from the connection.
-        FALLBACK_BASE_URL = "http://localhost"
-
-        def initialize(app: nil, base_url: nil)
-          @app = app
-          @base_url = base_url
-          @cookies = {}
-        end
-
-        def fetch(method, url, params: nil, headers: {})
-          method = method.to_s.upcase
-          url = absolute(url)
-          redirects = 0
-
-          loop do
-            status, response_headers, body = rack_app.call(build_env(method, url, params, headers))
-            store_cookies(response_headers)
-            location = header(response_headers, "location")
-
-            unless REDIRECT_STATUSES.include?(status.to_i) && location
-              return Response.new(status: status.to_i, body: read_body(body), url: url)
-            end
-
-            close_body(body)
-            redirects += 1
-            raise "Too many redirects fetching #{url}" if redirects > MAX_REDIRECTS
-
-            url = URI.join(url, location).to_s
-            # 307/308 preserve the method and body; everything else becomes a GET.
-            unless %w[307 308].include?(status.to_s)
-              method = "GET"
-              params = nil
-            end
-          end
-        end
-
-        private
-
-        def rack_app
-          @app ||= ::Rails.application
-        end
-
-        # Screens are normally declared as paths ("/native"), because none of
-        # this travels over the network and a host would be fiction. Rails still
-        # reads Host off the env though — `ActionDispatch::HostAuthorization`
-        # answers 403 for one it does not recognise — so the host has to be real
-        # even when the request is not. The host the client dialed on this very
-        # WebSocket is accepted by definition, which a hardcoded one is not.
-        def absolute(url)
-          url = url.to_s
-          return url if url.empty?
-
-          uri = URI.parse(url)
-          # A host, not merely a scheme: "localhost:3000" parses as scheme
-          # "localhost" with opaque "3000" and no path, so treating it as
-          # absolute would dispatch it to "/" and quietly render the wrong
-          # screen. Say so instead.
-          return url if uri.host
-          raise ArgumentError, malformed_url_message(url) if uri.scheme && !url.start_with?("/")
-
-          URI.join(base_url, url).to_s
-        rescue URI::InvalidURIError, URI::BadURIError
-          url
-        end
-
-        def malformed_url_message(url)
-          "Ruflet screen URL #{url.inspect} has no host. Use a path (\"/native\"), " \
-            "which takes its host from the client's connection, or a full URL " \
-            "including the scheme (\"http://localhost:3000/native\")."
-        end
-
-        def base_url
-          @base_url ||= websocket_base_url || configured_base_url || FALLBACK_BASE_URL
-        end
-
-        def websocket_base_url
-          env = websocket_env
-          return nil unless env
-
-          host = env["HTTP_X_FORWARDED_HOST"] || env["HTTP_HOST"]
-          return nil if host.to_s.strip.empty?
-
-          scheme = (env["HTTP_X_FORWARDED_PROTO"] || env["rack.url_scheme"] || "http").to_s.split(",").first.to_s.strip
-          scheme = "http" if scheme.empty?
-          "#{scheme}://#{host}"
-        end
-
-        # Loaded before Protocol in ruflet_rails.rb, and usable with no Rails at
-        # all (the gem's own tests do that), so resolve both lazily.
-        def websocket_env
-          return nil unless defined?(::Ruflet::Rails::Protocol::Context)
-
-          ::Ruflet::Rails::Protocol::Context.current_env
-        rescue StandardError
-          nil
-        end
-
-        def configured_base_url
-          return nil unless defined?(::Ruflet::Rails.config)
-
-          configured = ::Ruflet::Rails.config.backend_url.to_s.strip
-          configured.empty? ? nil : configured.sub(%r{/+\z}, "")
-        rescue StandardError
-          nil
-        end
-
-        # A minimal-but-complete Rack env, built by hand so we don't depend on a
-        # particular Rack version's Rack::MockRequest location.
-        def build_env(method, url, params, headers)
-          uri = URI.parse(url)
-          query = uri.query
-          body = ""
-          content_type = nil
-
-          if params && !params.empty?
-            encoded = URI.encode_www_form(params)
-            if method == "GET"
-              query = [query, encoded].reject { |part| part.to_s.empty? }.join("&")
-            else
-              body = encoded
-              content_type = "application/x-www-form-urlencoded"
-            end
-          end
-
-          env = {
-            "REQUEST_METHOD" => method,
-            "SCRIPT_NAME" => "",
-            "PATH_INFO" => uri.path.to_s.empty? ? "/" : uri.path,
-            "QUERY_STRING" => query.to_s,
-            "SERVER_NAME" => uri.host || "localhost",
-            "SERVER_PORT" => (uri.port || (uri.scheme == "https" ? 443 : 80)).to_s,
-            "HTTP_HOST" => host_header(uri),
-            # These renders happen in-process on the server itself — a loopback
-            # request in every sense. Saying so keeps `request.remote_ip` sane and
-            # quiets dev middleware (web-console) on every screen.
-            "REMOTE_ADDR" => "127.0.0.1",
-            "rack.url_scheme" => uri.scheme || "http",
-            "rack.input" => StringIO.new(body),
-            "rack.errors" => $stderr,
-            "rack.multithread" => true,
-            "rack.multiprocess" => false,
-            "rack.run_once" => false,
-            "HTTP_ACCEPT" => "text/html",
-            "HTTP_X_RUFLET_NATIVE" => "1"
-          }
-          env["CONTENT_TYPE"] = content_type if content_type
-          env["CONTENT_LENGTH"] = body.bytesize.to_s unless body.empty?
-          env["HTTP_COOKIE"] = cookie_header unless @cookies.empty?
-          headers.each { |key, value| env["HTTP_#{key.to_s.upcase.tr('-', '_')}"] = value.to_s }
-          env
-        end
-
-        # URI always fills in a port, but a browser omits the default one — and
-        # so must we: Rails echoes Host back in `url_for`, redirects and
-        # canonical links, where a stray ":443" would show up.
-        def host_header(uri)
-          return "localhost" if uri.host.to_s.empty?
-          return uri.host if uri.port.nil? || uri.port == uri.default_port
-
-          "#{uri.host}:#{uri.port}"
-        end
-
-        def read_body(body)
-          buffer = +""
-          body.each { |chunk| buffer << chunk.to_s }
-          buffer.force_encoding(Encoding::UTF_8) if buffer.encoding == Encoding::ASCII_8BIT
-          buffer
-        ensure
-          close_body(body)
-        end
-
-        def close_body(body)
-          body.close if body.respond_to?(:close)
-        rescue StandardError
-          nil
-        end
-
-        # Thread the Rails session cookie between sub-requests so CSRF tokens and
-        # flashes survive a form POST -> redirect -> render, like a browser.
-        def store_cookies(response_headers)
-          set_cookie = header(response_headers, "set-cookie")
-          return unless set_cookie
-
-          Array(set_cookie).each do |cookie|
-            cookie.to_s.split("\n").each do |line|
-              pair = line.split(";", 2).first.to_s.strip
-              name, value = pair.split("=", 2)
-              @cookies[name] = value if name && value
-            end
-          end
-        end
-
-        def cookie_header
-          @cookies.map { |name, value| "#{name}=#{value}" }.join("; ")
-        end
-
-        # Rack 3 lower-cases header names; earlier versions title-case them.
-        def header(response_headers, name)
-          return nil unless response_headers
-
-          response_headers[name] || response_headers[name.split("-").map(&:capitalize).join("-")] ||
-            (response_headers.respond_to?(:find) &&
-             response_headers.find { |key, _| key.to_s.downcase == name }&.last)
-        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
index c0051e22..b39f323b 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
@@ -21,10 +21,8 @@ module HtmlDsl
       # the controller instance, which is held for the life of the session, so
       # an ordinary `@count` survives from one tap to the next.
       #
-      # It satisfies the same interface as RackFetcher, so HtmlApp's
-      # navigation, diffing, forms and services all work unchanged.
       class TemplateSource
-        Response = RackFetcher::Response
+        Response = Struct.new(:status, :body, :url, keyword_init: true)
 
         def initialize(view_paths: nil, layout: nil)
           @view_paths = view_paths
@@ -161,7 +159,7 @@ def invalidate_templates!
           @templates = {}
           @lookups = {}
           @template_actions = {}
-          @view_class = nil
+          self.class.reset_view_class!
         end
 
         def template_mtime(template)
@@ -205,13 +203,23 @@ def assigns_for(controller)
           end
         end
 
-        # One view class for the session: a template compiles its partials into
-        # the class that rendered it, so a fresh class per render leaves those
-        # methods behind on the previous one.
-        def view_class
-          @view_class ||= ActionView::Base.with_empty_template_cache
+        # 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(@view_paths || ::ActionController::Base.view_paths, {}, prefixes)
         end
diff --git a/packages/ruflet_rails/lib/ruflet/rails/install_support.rb b/packages/ruflet_rails/lib/ruflet/rails/install_support.rb
index e31f1dec..1777500e 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/install_support.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/install_support.rb
@@ -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)
         normalized = normalize_build_platform(platform)
         return [] if normalized.to_s.empty?
-        return [] if normalized == "web"
-
         [normalized]
       end
 
@@ -143,10 +138,6 @@ def route_snippet(entrypoint: default_entrypoint_path, mount_path: "/ws", helper
         %(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_file: Rails.root.join("#{entrypoint}")), at: "#{mount_path}")
-      end
-
       def install_next_steps(target:, entrypoint:, client:, mount_path: "/ws")
         lines = [
           "Ruflet Rails installed.",
@@ -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_screens.rb b/packages/ruflet_rails/lib/ruflet/rails/native_screens.rb
index a90709dc..f22f628e 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/native_screens.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/native_screens.rb
@@ -30,13 +30,6 @@ module NativeScreens
 
       module_function
 
-      # Only a Ruflet session may reach a screen. A browser hitting the same
-      # path gets whatever the app's own routes say — normally a 404 — so
-      # screens are not a second, undeclared public surface.
-      def native_request?(request)
-        request.get_header("HTTP_X_RUFLET_NATIVE").to_s == "1"
-      end
-
       # "/native/counter/increment" -> ["native", ["counter", "increment"]]
       def split_path(path)
         segments = path.to_s.split("/").reject(&:empty?)
@@ -99,35 +92,6 @@ def constantize(name)
         nil
       end
 
-      # Rack app the Railtie installs as a catch-all. Resolving here rather than
-      # in the routing table is the whole point: no screen needs declaring.
-      class Dispatcher
-        def call(env)
-          request = ::ActionDispatch::Request.new(env)
-          screen = NativeScreens.resolve(request.path)
-          return not_found(request.path) unless screen
-
-          assign_params(env, screen[:params])
-          screen[:controller].action(screen[:action]).call(env)
-        end
-
-        private
-
-        # Extra path segments arrive as params, so a screen can be
-        # parameterised without a route declaring the segment's name.
-        def assign_params(env, values)
-          return if values.empty?
-
-          params = env["action_dispatch.request.path_parameters"] || {}
-          params = params.merge(id: values.first, screen_params: values)
-          env["action_dispatch.request.path_parameters"] = params
-        end
-
-        def not_found(path)
-          body = "No Ruflet screen for #{path}"
-          [404, { "content-type" => "text/plain", "content-length" => body.bytesize.to_s }, [body]]
-        end
-      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 33e57f3c..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_file: Rails.root.join("app/views/ruflet/main.rb")), at: "/myfrontend"
-      #
-      #   # or with an explicit entrypoint and build directory:
-      #   mount Ruflet::Rails.web(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, "Ruflet::Rails.web 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/railtie.rb b/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
index a5815e0c..4550ac5f 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
@@ -3,7 +3,7 @@
 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
@@ -19,21 +19,6 @@ class Railtie < ::Rails::Railtie
         end
       end
 
-      # Screens resolve by convention instead of by declaration, so an app's
-      # routes.rb holds only its own routes plus the one WebSocket mount. The
-      # catch-all is appended (it runs after every declared route, never
-      # shadowing one) and is constrained to Ruflet sessions, so it adds no
-      # public surface: a browser on the same path still falls through to the
-      # app's own routing, normally a 404.
-      initializer "ruflet_rails.native_screens" do |app|
-        app.routes.append do
-          match "/*ruflet_screen",
-                to: Ruflet::Rails::NativeScreens::Dispatcher.new,
-                via: :all,
-                constraints: ->(request) { Ruflet::Rails::NativeScreens.native_request?(request) }
-        end
-      end
-
       initializer "ruflet_rails.desktop_launcher", after: :load_config_initializers do |_app|
         next unless defined?(::Rails.root)
 
@@ -49,11 +34,6 @@ 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)
@@ -89,12 +69,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
diff --git a/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb b/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
index ea8bb59f..9cc251c4 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
@@ -9,10 +9,6 @@ module Rails
     # 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.native 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%" %>
     #
@@ -20,31 +16,6 @@ module Rails
     # WebSocket and assets resolve against this host with no extra config. Pass a
     # full URL to embed a Ruflet app on another host.
     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
@@ -213,7 +184,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)
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 de7702f6..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.native 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 d3bd30b3..41b4b8f0 100644
--- a/packages/ruflet_rails/lib/ruflet_rails.rb
+++ b/packages/ruflet_rails/lib/ruflet_rails.rb
@@ -18,7 +18,6 @@
 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/test/endpoint_declaration_test.rb b/packages/ruflet_rails/test/endpoint_declaration_test.rb
index 569e6431..cd0700bd 100644
--- a/packages/ruflet_rails/test/endpoint_declaration_test.rb
+++ b/packages/ruflet_rails/test/endpoint_declaration_test.rb
@@ -42,16 +42,4 @@ def test_native_accepts_an_app_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
index 11b4877a..1cee1534 100644
--- a/packages/ruflet_rails/test/html_app_test.rb
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -7,7 +7,7 @@
 class RufletHtmlAppTest < Minitest::Test
   # Serves canned HTML per method+path and records every request.
   class StubFetcher
-    Response = Ruflet::Rails::HtmlDsl::RackFetcher::Response
+    Response = Ruflet::Rails::HtmlDsl::TemplateSource::Response
 
     attr_reader :requests
 
@@ -618,7 +618,7 @@ def test_binary_response_bodies_become_utf8_text
     fetcher = Object.new
     def fetcher.fetch(_m, url, params: nil, headers: {})
       body = "<text>Ruflet Native — démo</text>".dup.force_encoding(Encoding::ASCII_8BIT)
-      Ruflet::Rails::HtmlDsl::RackFetcher::Response.new(status: 200, body: body, url: url)
+      Ruflet::Rails::HtmlDsl::TemplateSource::Response.new(status: 200, body: body, url: url)
     end
     Ruflet::Rails.erb_to_native(@page, start_url: "https://app.test/", fetcher: fetcher)
 
@@ -630,7 +630,7 @@ def fetcher.fetch(_m, url, params: nil, headers: {})
   def test_server_error_pages_render_a_compact_error_screen
     fetcher = Object.new
     def fetcher.fetch(_m, url, params: nil, headers: {})
-      Ruflet::Rails::HtmlDsl::RackFetcher::Response.new(
+      Ruflet::Rails::HtmlDsl::TemplateSource::Response.new(
         status: 500,
         body: "<html><head><title>ActionController::RoutingError</title></head>" \
               '<body><header><button onclick="x()">rails page</button></header></body></html>',
diff --git a/packages/ruflet_rails/test/install_generator_test.rb b/packages/ruflet_rails/test/install_generator_test.rb
index 9d162627..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({})
@@ -89,21 +67,6 @@ def test_install_does_not_duplicate_the_websocket_route
     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_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 a01e89eb..5960c84e 100644
--- a/packages/ruflet_rails/test/install_support_test.rb
+++ b/packages/ruflet_rails/test/install_support_test.rb
@@ -47,12 +47,6 @@ 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_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,9 +78,6 @@ 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(
diff --git a/packages/ruflet_rails/test/native_screens_test.rb b/packages/ruflet_rails/test/native_screens_test.rb
index db5303e0..70d3d514 100644
--- a/packages/ruflet_rails/test/native_screens_test.rb
+++ b/packages/ruflet_rails/test/native_screens_test.rb
@@ -103,14 +103,5 @@ def test_a_folder_with_no_index_action_does_not_resolve
 
   # Rails' own Request is not loaded here (the gem's tests run without Rails),
   # and native_request? only ever asks for the header.
-  class StubRequest
-    def initialize(headers) = @headers = headers
-    def get_header(name) = @headers[name]
-  end
 
-  def test_only_a_ruflet_session_may_reach_a_screen
-    assert Ruflet::Rails::NativeScreens.native_request?(StubRequest.new("HTTP_X_RUFLET_NATIVE" => "1"))
-    refute Ruflet::Rails::NativeScreens.native_request?(StubRequest.new({}))
-    refute Ruflet::Rails::NativeScreens.native_request?(StubRequest.new("HTTP_X_RUFLET_NATIVE" => "0"))
-  end
 end
diff --git a/packages/ruflet_rails/test/rack_fetcher_test.rb b/packages/ruflet_rails/test/rack_fetcher_test.rb
deleted file mode 100644
index 47763e9d..00000000
--- a/packages/ruflet_rails/test/rack_fetcher_test.rb
+++ /dev/null
@@ -1,174 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "test_helper"
-
-# Screens are dispatched into the Rack app in-process. A screen may therefore be
-# named by path alone — nothing here goes over the network, so there is no host
-# to know. Rails still reads Host off the env, so the fetcher has to supply one
-# the app will accept.
-class RufletRackFetcherTest < Minitest::Test
-  # Records the env it was called with and answers a fixed response.
-  class StubRackApp
-    attr_reader :envs
-
-    def initialize(status: 200, headers: {}, body: "<text>ok</text>")
-      @status = status
-      @headers = headers
-      @body = body
-      @envs = []
-    end
-
-    def call(env)
-      @envs << env
-      [@status, @headers, [@body]]
-    end
-  end
-
-  def teardown
-    Ruflet::Rails.config.backend_url = nil
-  end
-
-  def fetch(app, url, base_url: nil, env: nil, method: "GET", **kwargs)
-    fetcher = Ruflet::Rails::HtmlDsl::RackFetcher.new(app: app, base_url: base_url)
-    if env
-      Ruflet::Rails::Protocol::Context.with_env(env) { fetcher.fetch(method, url, **kwargs) }
-    else
-      fetcher.fetch(method, url, **kwargs)
-    end
-  end
-
-  def ws_env(host, scheme: "http")
-    { "HTTP_HOST" => host, "rack.url_scheme" => scheme }
-  end
-
-  def test_path_url_takes_its_host_from_the_live_websocket_connection
-    app = StubRackApp.new
-    fetch(app, "/native", env: ws_env("192.168.1.50:3000"))
-
-    env = app.envs.first
-    assert_equal "/native", env["PATH_INFO"]
-    assert_equal "192.168.1.50:3000", env["HTTP_HOST"]
-    assert_equal "192.168.1.50", env["SERVER_NAME"]
-    assert_equal "3000", env["SERVER_PORT"]
-    assert_equal "http", env["rack.url_scheme"]
-  end
-
-  def test_path_url_honours_the_forwarded_host_and_scheme
-    app = StubRackApp.new
-    fetch(app, "/native", env: { "HTTP_X_FORWARDED_HOST" => "app.example.com",
-                                 "HTTP_X_FORWARDED_PROTO" => "https,http",
-                                 "HTTP_HOST" => "internal:3000" })
-
-    env = app.envs.first
-    assert_equal "app.example.com", env["HTTP_HOST"]
-    assert_equal "https", env["rack.url_scheme"]
-    assert_equal "443", env["SERVER_PORT"]
-  end
-
-  def test_path_url_falls_back_to_the_configured_backend_url_off_connection
-    Ruflet::Rails.config.backend_url = "https://configured.example.com/"
-    app = StubRackApp.new
-    fetch(app, "/native")
-
-    assert_equal "configured.example.com", app.envs.first["HTTP_HOST"]
-    assert_equal "https", app.envs.first["rack.url_scheme"]
-  end
-
-  def test_the_live_connection_wins_over_a_stale_configured_backend_url
-    Ruflet::Rails.config.backend_url = "http://127.0.0.1:3000"
-    app = StubRackApp.new
-    fetch(app, "/native", env: ws_env("192.168.1.50:3000"))
-
-    assert_equal "192.168.1.50:3000", app.envs.first["HTTP_HOST"]
-  end
-
-  def test_path_url_falls_back_to_localhost_with_no_connection_and_no_config
-    app = StubRackApp.new
-    fetch(app, "/native")
-
-    assert_equal "localhost", app.envs.first["HTTP_HOST"]
-  end
-
-  def test_an_explicit_base_url_overrides_everything
-    Ruflet::Rails.config.backend_url = "http://127.0.0.1:3000"
-    app = StubRackApp.new
-    fetch(app, "/native", base_url: "http://explicit.test", env: ws_env("192.168.1.50:3000"))
-
-    assert_equal "explicit.test", app.envs.first["HTTP_HOST"]
-  end
-
-  def test_an_absolute_url_is_used_verbatim_and_ignores_the_connection
-    app = StubRackApp.new
-    fetch(app, "https://given.example.com/native", env: ws_env("192.168.1.50:3000"))
-
-    env = app.envs.first
-    assert_equal "given.example.com", env["HTTP_HOST"]
-    assert_equal "https", env["rack.url_scheme"]
-    assert_equal "/native", env["PATH_INFO"]
-  end
-
-  def test_the_response_reports_the_resolved_absolute_url
-    response = fetch(StubRackApp.new, "/native", env: ws_env("192.168.1.50:3000"))
-
-    assert_equal "http://192.168.1.50:3000/native", response.url
-  end
-
-  def test_a_path_url_still_follows_redirects
-    app = Object.new
-    app.define_singleton_method(:envs) { @envs ||= [] }
-    app.define_singleton_method(:call) do |env|
-      envs << env
-      if envs.length == 1
-        [302, { "location" => "/native/counter" }, [""]]
-      else
-        [200, {}, ["<text>done</text>"]]
-      end
-    end
-
-    response = fetch(app, "/native", env: ws_env("192.168.1.50:3000"))
-
-    assert_equal 200, response.status
-    assert_equal ["/native", "/native/counter"], app.envs.map { |e| e["PATH_INFO"] }
-    assert_equal ["192.168.1.50:3000", "192.168.1.50:3000"], app.envs.map { |e| e["HTTP_HOST"] }
-  end
-
-  def test_query_strings_and_params_survive_path_resolution
-    app = StubRackApp.new
-    fetch(app, "/search?scope=all", env: ws_env("host.test"), params: { "q" => "ada" })
-
-    env = app.envs.first
-    assert_equal "/search", env["PATH_INFO"]
-    assert_includes env["QUERY_STRING"], "scope=all"
-    assert_includes env["QUERY_STRING"], "q=ada"
-  end
-
-  def test_post_params_become_a_form_encoded_body
-    app = StubRackApp.new
-    fetch(app, "/native/form", method: "POST", env: ws_env("host.test"),
-                               params: { "name" => "Ada Lovelace" })
-
-    env = app.envs.first
-    assert_equal "POST", env["REQUEST_METHOD"]
-    assert_equal "application/x-www-form-urlencoded", env["CONTENT_TYPE"]
-    assert_equal "name=Ada+Lovelace", env["rack.input"].read
-  end
-
-  # "localhost:3000" parses as scheme "localhost" with opaque "3000" and no
-  # path. Passed through as absolute it would dispatch to "/" and render
-  # whatever the root route is, which looks like the app ignoring start_url.
-  def test_a_host_less_scheme_is_rejected_instead_of_silently_becoming_root
-    error = assert_raises(ArgumentError) do
-      fetch(StubRackApp.new, "localhost:3000", env: ws_env("host.test"))
-    end
-
-    assert_includes error.message, "has no host"
-    assert_includes error.message, "/native"
-  end
-
-  def test_it_marks_the_request_as_a_native_one
-    app = StubRackApp.new
-    fetch(app, "/native", env: ws_env("host.test"))
-
-    assert_equal "1", app.envs.first["HTTP_X_RUFLET_NATIVE"]
-  end
-end
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 bb777ebe..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(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(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(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 { |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_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

From 945288f2e9c607400f21b391c767f95e9c499f09 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Fri, 7 Aug 2026 23:04:15 -0400
Subject: [PATCH 24/30] Remove what the request cycle left behind
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ControllerHelpers answered a question nothing asks any more:
ruflet_native_request? read the X-Ruflet-Native header, and RackFetcher
was the only thing that ever set it, while render_native existed to
collapse the Post/Redirect/Get double-fetch that only a request has.

The HTML DSL's CSRF plumbing goes with it — the csrf-token meta scan, the
token carried on each Screen, and the X-CSRF-Token header. There is no
request to forge and nothing reads a header. The CSRF JS in native_shell
stays: a WebView really does post a form.

Also ruflet_css_dimension, which only ever sized the iframe that
ruflet_frame rendered.
---
 .../lib/ruflet/rails/controller_helpers.rb    | 55 -----------------
 .../lib/ruflet/rails/html_dsl/html_app.rb     |  8 +--
 .../lib/ruflet/rails/html_dsl/transformer.rb  | 12 +---
 .../ruflet_rails/lib/ruflet/rails/railtie.rb  |  8 ---
 .../lib/ruflet/rails/view_helpers.rb          |  3 -
 packages/ruflet_rails/lib/ruflet_rails.rb     |  1 -
 .../test/controller_helpers_test.rb           | 61 -------------------
 packages/ruflet_rails/test/html_app_test.rb   |  3 +-
 packages/ruflet_rails/test/html_dsl_test.rb   |  1 -
 9 files changed, 6 insertions(+), 146 deletions(-)
 delete mode 100644 packages/ruflet_rails/lib/ruflet/rails/controller_helpers.rb
 delete mode 100644 packages/ruflet_rails/test/controller_helpers_test.rb

diff --git a/packages/ruflet_rails/lib/ruflet/rails/controller_helpers.rb b/packages/ruflet_rails/lib/ruflet/rails/controller_helpers.rb
deleted file mode 100644
index 23769dda..00000000
--- a/packages/ruflet_rails/lib/ruflet/rails/controller_helpers.rb
+++ /dev/null
@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Ruflet
-  module Rails
-    # Available in every controller (see Railtie).
-    #
-    # A native screen is fetched by the session's RackFetcher, which tags its
-    # requests. Knowing that lets an action answer the native client in one
-    # cycle instead of the browser's two.
-    #
-    # Post/Redirect/Get exists so a browser's reload button doesn't re-submit.
-    # The native client has no reload button and no address bar: the redirect
-    # buys nothing there and doubles the work, because the fetcher has to
-    # follow the 302 with a second request through routing, the controller and
-    # the view. `render_native` renders the screen straight from the POST.
-    #
-    #   def counter_increment
-    #     session[:count] = session[:count].to_i + 1
-    #     render_native :counter, else: -> { redirect_to counter_path }
-    #   end
-    # A plain module on purpose: ruflet_rails loads without Rails (the gem's
-    # own tests do exactly that), so this must not reach for
-    # ActiveSupport::Concern at load time.
-    module ControllerHelpers
-      def self.included(base)
-        return unless base.respond_to?(:helper_method)
-
-        base.helper_method :ruflet_native_request?
-      rescue StandardError
-        nil
-      end
-
-      # True when this request came from a Ruflet native session rather than a
-      # browser.
-      def ruflet_native_request?
-        request.headers["X-Ruflet-Native"].to_s == "1"
-      end
-
-      # Render `template` for a native client; otherwise run `else` (usually the
-      # redirect a browser still wants).
-      def render_native(template, **options, &fallback)
-        fallback ||= options.delete(:else)
-
-        unless ruflet_native_request?
-          return fallback.call if fallback.respond_to?(:call)
-
-          raise ArgumentError, "render_native needs an `else:` for browser requests"
-        end
-
-        options.delete(:else)
-        render(template, **options)
-      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
index 20545e29..fd729427 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -13,7 +13,7 @@ module HtmlDsl
       # Rails and re-render the current screen in place, forms post their
       # field values and render the response.
       class HtmlApp
-        Screen = Struct.new(:url, :view, :route, :root, :fields, :csrf_token, :title,
+        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,
@@ -1172,7 +1172,6 @@ def render_result(screen, response)
           # 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.csrf_token = result.csrf_token
           screen.title = result.title
           if result.controls.empty?
             message = response.status.to_i >= 400 ? "HTTP #{response.status} — #{screen.url}" : "Empty screen"
@@ -1267,10 +1266,7 @@ def flush
         # --- HTTP -----------------------------------------------------------------
 
         def request(method, url, params: nil, screen: nil)
-          headers = {}
-          token = screen&.csrf_token || @screens.last&.csrf_token
-          headers["X-CSRF-Token"] = token if token && method.to_s.downcase != "get"
-          @fetcher.fetch(method, url, params: params, headers: headers)
+          @fetcher.fetch(method, url, params: params)
         rescue StandardError => e
           TemplateSource::Response.new(status: 0, body: error_markup(url, e), url: url)
         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
index b8b931d0..0fe9ab74 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
@@ -16,8 +16,7 @@ module HtmlDsl
       # `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,
-                            :csrf_token, keyword_init: true)
+        Result = Struct.new(:controls, :appbar, :fab, :bottom_nav, :services, :on_load, :title, keyword_init: true)
 
         HEADING_STYLES = {
           "h1" => { size: 32, weight: "bold" },
@@ -99,7 +98,7 @@ def resolve_asset_url(value)
         def transform(html)
           nodes = Parser.parse(html)
           @result = Result.new(controls: [], appbar: nil, fab: nil, bottom_nav: nil, services: [],
-                               on_load: [], title: nil, csrf_token: nil)
+                               on_load: [], title: nil)
           scan_document_metadata(nodes)
 
           @result.controls = build_children(content_nodes(nodes), form: nil)
@@ -112,12 +111,7 @@ def transform(html)
 
         def scan_document_metadata(nodes)
           each_element(nodes) do |element|
-            case element.tag
-            when "title"
-              @result.title = element.text if @result.title.nil?
-            when "meta"
-              @result.csrf_token = element["content"] if element["name"] == "csrf-token"
-            end
+            @result.title = element.text if element.tag == "title" && @result.title.nil?
           end
         end
 
diff --git a/packages/ruflet_rails/lib/ruflet/rails/railtie.rb b/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
index 4550ac5f..56fee890 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
@@ -11,14 +11,6 @@ class Railtie < ::Rails::Railtie
         end
       end
 
-      # ruflet_native_request? / render_native in every controller, so an
-      # action can answer the native client in one cycle instead of two.
-      initializer "ruflet_rails.controller_helpers" do
-        ActiveSupport.on_load(:action_controller) do
-          include Ruflet::Rails::ControllerHelpers
-        end
-      end
-
       initializer "ruflet_rails.desktop_launcher", after: :load_config_initializers do |_app|
         next unless defined?(::Rails.root)
 
diff --git a/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb b/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
index 9cc251c4..11256104 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
@@ -221,9 +221,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.rb b/packages/ruflet_rails/lib/ruflet_rails.rb
index 41b4b8f0..bb416ebd 100644
--- a/packages/ruflet_rails/lib/ruflet_rails.rb
+++ b/packages/ruflet_rails/lib/ruflet_rails.rb
@@ -13,7 +13,6 @@
 require_relative "ruflet/rails/native_app"
 require_relative "ruflet/rails/html_dsl"
 require_relative "ruflet/rails/view_helpers"
-require_relative "ruflet/rails/controller_helpers"
 require_relative "ruflet/rails/native_screens"
 require_relative "ruflet/rails/desktop_launcher"
 require_relative "ruflet/rails/protocol"
diff --git a/packages/ruflet_rails/test/controller_helpers_test.rb b/packages/ruflet_rails/test/controller_helpers_test.rb
deleted file mode 100644
index f970e541..00000000
--- a/packages/ruflet_rails/test/controller_helpers_test.rb
+++ /dev/null
@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "test_helper"
-
-# render_native lets one action serve both clients: the native session gets the
-# screen straight from the POST (one Rails cycle), a browser still gets the
-# Post/Redirect/Get its reload button needs.
-class RufletControllerHelpersTest < Minitest::Test
-  class FakeRequest
-    def initialize(headers) = @headers = headers
-    attr_reader :headers
-  end
-
-  class FakeController
-    include Ruflet::Rails::ControllerHelpers
-
-    attr_reader :rendered
-
-    def initialize(native:)
-      @request = FakeRequest.new(native ? { "X-Ruflet-Native" => "1" } : {})
-      @rendered = nil
-    end
-
-    attr_reader :request
-
-    def render(template, **options)
-      @rendered = [template, options]
-    end
-  end
-
-  def test_native_requests_render_in_place
-    controller = FakeController.new(native: true)
-    redirected = false
-
-    controller.render_native(:counter, else: -> { redirected = true })
-
-    assert_equal [:counter, {}], controller.rendered
-    refute redirected, "a native request must not take the redirect"
-  end
-
-  def test_browser_requests_take_the_fallback
-    controller = FakeController.new(native: false)
-    redirected = false
-
-    controller.render_native(:counter, else: -> { redirected = true })
-
-    assert_nil controller.rendered
-    assert redirected, "a browser must still get Post/Redirect/Get"
-  end
-
-  def test_ruflet_native_request_reads_the_fetcher_marker
-    assert FakeController.new(native: true).ruflet_native_request?
-    refute FakeController.new(native: false).ruflet_native_request?
-  end
-
-  def test_browser_request_without_a_fallback_is_a_mistake
-    controller = FakeController.new(native: false)
-
-    assert_raises(ArgumentError) { controller.render_native(:counter) }
-  end
-end
diff --git a/packages/ruflet_rails/test/html_app_test.rb b/packages/ruflet_rails/test/html_app_test.rb
index 1cee1534..9c9b46cd 100644
--- a/packages/ruflet_rails/test/html_app_test.rb
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -99,7 +99,7 @@ def test_action_rerenders_the_screen_in_place
     assert_equal "post", @fetcher.requests.last["method"] || @fetcher.requests.last[:method]
   end
 
-  def test_form_submits_tracked_field_values_with_csrf
+  def test_form_submits_tracked_field_values
     submitted = nil
     pages = {
       "/" => <<~HTML,
@@ -120,7 +120,6 @@ def test_form_submits_tracked_field_values_with_csrf
     find(view, "filledbutton").emit("click", nil)
 
     assert_equal({ "email" => "new@x.y", "token" => "h1" }, submitted)
-    assert_equal "tok-1", @fetcher.requests.last[:headers]["X-CSRF-Token"]
     assert_equal "done", find(@page.views.first, "text").props["value"]
   end
 
diff --git a/packages/ruflet_rails/test/html_dsl_test.rb b/packages/ruflet_rails/test/html_dsl_test.rb
index 39f78b1e..5afd4bf4 100644
--- a/packages/ruflet_rails/test/html_dsl_test.rb
+++ b/packages/ruflet_rails/test/html_dsl_test.rb
@@ -272,7 +272,6 @@ def test_full_rails_layout_unwraps_to_body_and_reads_metadata
     HTML
 
     assert_equal "Inbox", result.title
-    assert_equal "tok123", result.csrf_token
     assert_equal 1, result.controls.length
     assert_equal "hello", result.controls.first.props["value"]
   end

From 3c00ff31cd6ac2c7d746adc5cd7be2714678b52c Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Sat, 8 Aug 2026 00:00:53 -0400
Subject: [PATCH 25/30] Drop arguments and prose the rewrite left behind

Parameters nothing reads: the screen threaded through HtmlApp#request and
the headers passed to a fetcher, both left over from CSRF; the source
screen given to #navigate, which never consulted it; styles on
build_button, form on build_chip and finalize; root on desktop_enabled?;
ruflet_url on build_args_for_platform and target on install_next_steps,
with the generator's install_target that existed only to supply it.

The comments were worse than unused, because they were wrong: NativeScreens
still promised dispatch through Rails' middleware with session, flash and
CSRF intact, HtmlApp described actions round-tripping to Rails and
redirects being followed, and ViewHelpers opened by documenting the
ruflet_frame that no longer exists.
---
 .../ruflet/install/install_generator.rb       |  4 ---
 .../lib/ruflet/rails/desktop_launcher.rb      |  4 +--
 .../lib/ruflet/rails/html_dsl/html_app.rb     | 26 +++++++++----------
 .../ruflet/rails/html_dsl/template_source.rb  |  2 +-
 .../lib/ruflet/rails/html_dsl/transformer.rb  | 12 ++++-----
 .../lib/ruflet/rails/install_support.rb       |  4 +--
 .../lib/ruflet/rails/native_screens.rb        |  7 +----
 .../ruflet_rails/lib/ruflet/rails/railtie.rb  |  5 ++--
 .../lib/ruflet/rails/view_helpers.rb          | 14 +++-------
 .../test/desktop_launcher_test.rb             |  8 +++---
 .../ruflet_rails/test/install_support_test.rb |  2 --
 11 files changed, 34 insertions(+), 54 deletions(-)

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 1fc682f8..aaa8b81b 100644
--- a/packages/ruflet_rails/lib/generators/ruflet/install/install_generator.rb
+++ b/packages/ruflet_rails/lib/generators/ruflet/install/install_generator.rb
@@ -54,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 }
@@ -87,9 +86,6 @@ def desktop_requested?
         %w[desktop all].include?(requested_client)
       end
 
-      def install_target
-        "ruflet"
-      end
 
       def install_desktop_client
         require "ruflet/cli"
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/html_app.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
index fd729427..5699f0f8 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -7,11 +7,10 @@
 module Ruflet
   module Rails
     module HtmlDsl
-      # HTML-over-the-wire native UI: Rails renders HTML DSL markup and this
-      # app turns each page into a screen of real Ruflet controls — no
-      # WebView. Links push native screens, `on-click` actions round-trip to
-      # Rails and re-render the current screen in place, forms post their
-      # field values and render the response.
+      # 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)
@@ -24,7 +23,7 @@ def initialize(app, screen)
             @screen = screen
           end
 
-          def navigate(url, mode) = @app.navigate(url, mode, from: @screen)
+          def navigate(url, mode) = @app.navigate(url, mode)
           def action(method:, url:) = @app.action(method: method, url: url, from: @screen)
           def submit_form(form) = @app.submit_form(form, from: @screen)
           def field_changed(name, value) = @screen.fields[name] = value
@@ -56,7 +55,7 @@ def default_fetcher
 
         # --- navigation ---------------------------------------------------------
 
-        def navigate(url, mode, from: nil)
+        def navigate(url, mode)
           url = absolute_url(url)
           case mode.to_s
           when "back"
@@ -72,14 +71,13 @@ def navigate(url, mode, from: nil)
           end
         end
 
-        # An `on-click` action: request the URL, then re-render the source
-        # screen in place with the returned markup (Rails redirects are
-        # followed by the fetcher, so `redirect_to` re-renders the target).
+        # 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(method:, url:, from: nil)
           screen = from || @screens.last
           return unless screen
 
-          response = request(method, absolute_url(url), screen: screen)
+          response = request(method, absolute_url(url))
           rerender(screen, response)
         end
 
@@ -91,7 +89,7 @@ def submit_form(form, from: nil)
             value = screen.fields.key?(name) ? screen.fields[name] : form[:fields][name]
             collected[name] = value.nil? ? "" : value
           end
-          response = request(form[:method], absolute_url(form[:action]), params: params, screen: screen)
+          response = request(form[:method], absolute_url(form[:action]), params: params)
           rerender(screen, response)
         end
 
@@ -396,7 +394,7 @@ def push_screen(url, root: false)
           invalidate_pending_services
           screen = Screen.new(url: url, root: root, fields: {})
           screen.route = root ? "/" : "/screen/#{@route_seq += 1}"
-          response = request("get", url, screen: screen)
+          response = request("get", url)
           result = render_result(screen, response)
           screen.view = build_view(screen, result)
           remember_chrome(screen, result)
@@ -1265,7 +1263,7 @@ def flush
 
         # --- HTTP -----------------------------------------------------------------
 
-        def request(method, url, params: nil, screen: nil)
+        def request(method, url, params: nil)
           @fetcher.fetch(method, url, params: params)
         rescue StandardError => e
           TemplateSource::Response.new(status: 0, body: error_markup(url, e), url: url)
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
index b39f323b..4b13597e 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
@@ -33,7 +33,7 @@ def initialize(view_paths: nil, layout: nil)
           @lookups = {}
         end
 
-        def fetch(method, url, params: nil, headers: {})
+        def fetch(_method, url, params: nil)
           path = URI.parse(url.to_s).path.to_s
           screen = NativeScreens.resolve(path)
           return missing(url, path) unless screen
diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
index 0fe9ab74..f64eb123 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
@@ -152,7 +152,7 @@ def build_node(node, form:)
           control = build_element(element, form: form)
           return nil unless control
 
-          finalize(control, element, form: form)
+          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
@@ -189,7 +189,7 @@ def build_element(element, form:)
           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, 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)
@@ -210,7 +210,7 @@ def build_element(element, 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, form: form)
+          when "chip" then build_chip(element)
           when "progress" then progress_bar(**element_props(element))
           else
             build_generic(element, form: form)
@@ -317,7 +317,7 @@ def build_link(element, styles, form:)
           "outlined" => :outlined_button, "text" => :text_button, "elevated" => :button
         }.freeze
 
-        def build_button(element, styles, form:)
+        def build_button(element, form:)
           label = collapse_whitespace(element.text)
           icon = element["icon"]
           on_click =
@@ -636,7 +636,7 @@ def table_cell_content(cell, form:)
 
         # <chip label="Ruby"> or <chip>Ruby</chip> — Chip needs `label`, and
         # a bare `on-click` becomes its native click action.
-        def build_chip(element, form:)
+        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"]
@@ -1063,7 +1063,7 @@ def event_value(event)
         end
 
         # Generic `on-click` on non-interactive elements gets a tap wrapper.
-        def finalize(control, element, form: nil)
+        def finalize(control, element)
           spec = element["on-click"] || element["on-tap"]
           return control unless spec
           return control if SELF_CLICKING_TAGS.include?(element.tag)
diff --git a/packages/ruflet_rails/lib/ruflet/rails/install_support.rb b/packages/ruflet_rails/lib/ruflet/rails/install_support.rb
index 1777500e..2e0681a3 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/install_support.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/install_support.rb
@@ -124,7 +124,7 @@ def normalize_build_platform(platform)
         value
       end
 
-      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?
         [normalized]
@@ -138,7 +138,7 @@ def route_snippet(entrypoint: default_entrypoint_path, mount_path: "/ws", helper
         %(match "#{mount_path}", to: Ruflet::Rails.#{helper}(Rails.root.join("#{entrypoint}")), via: :all)
       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}",
diff --git a/packages/ruflet_rails/lib/ruflet/rails/native_screens.rb b/packages/ruflet_rails/lib/ruflet/rails/native_screens.rb
index f22f628e..7b39472b 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/native_screens.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/native_screens.rb
@@ -13,17 +13,13 @@ module Rails
     #   /native                    -> NativeController#home   (or #index)
     #   /native/counter            -> NativeController#counter
     #   /native/counter/increment  -> NativeController#counter_increment
-    #   /native/device/camera      -> NativeController#device, params[:id] = "camera"
+    #   /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.
-    #
-    # Dispatch still goes through Rails' middleware and the controller itself,
-    # so `session`, `flash`, CSRF, `before_action` and layouts behave exactly as
-    # they do for a normal request. What is skipped is only the routing table.
     module NativeScreens
       # Actions to try for the root of a feature folder, in order.
       INDEX_ACTIONS = %w[home index show].freeze
@@ -91,7 +87,6 @@ def constantize(name)
       rescue NameError
         nil
       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 56fee890..ebafbf8d 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/railtie.rb
@@ -26,9 +26,8 @@ class Railtie < ::Rails::Railtie
           task :build, [:platform] do |_task, args|
             platform = args[:platform].to_s.strip.downcase
 
-            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]"
diff --git a/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb b/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
index 11256104..6fcb44a3 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/view_helpers.rb
@@ -5,16 +5,10 @@
 
 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.
-    #
-    #   <%= 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
       # --- Native annotations ------------------------------------------------
       #
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/install_support_test.rb b/packages/ruflet_rails/test/install_support_test.rb
index 5960c84e..90efa5f0 100644
--- a/packages/ruflet_rails/test/install_support_test.rb
+++ b/packages/ruflet_rails/test/install_support_test.rb
@@ -81,7 +81,6 @@ def test_build_args_for_rails_desktop_are_server_driven
 
   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")
@@ -94,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")

From 816643465c57219e071b76f366bcce2e71bee011 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Sat, 8 Aug 2026 00:14:47 -0400
Subject: [PATCH 26/30] Drop the last two orphans

lookup_context was left memoising a context nothing asks for once render
started building one per prefix, and ScreenContext#ruflet_native_request?
answered a question no caller has: with no request behind a screen it can
only ever say true.
---
 .../lib/ruflet/rails/html_dsl/template_source.rb           | 7 -------
 1 file changed, 7 deletions(-)

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
index 4b13597e..e425b100 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
@@ -224,9 +224,6 @@ def build_lookup_context(prefixes = [])
           ActionView::LookupContext.new(@view_paths || ::ActionController::Base.view_paths, {}, prefixes)
         end
 
-        def lookup_context
-          @lookup_context ||= build_lookup_context
-        end
 
         def missing(url, path)
           Response.new(status: 404, body: <<~HTML, url: url)
@@ -262,10 +259,6 @@ def params
             @ruflet_screen_params ||= {}
           end
 
-          # There is no request, so a native screen is all there is.
-          def ruflet_native_request?
-            true
-          end
         end
       end
     end

From efcdfdc3028e5ee19af16e8f4cc028f1c2f91f80 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Sat, 8 Aug 2026 01:15:06 -0400
Subject: [PATCH 27/30] Stop offering settings nobody sets

layout: and view_paths: were options with no caller: the layout path also
kept a second, slower render alive purely to honour it, and view_paths
existed only as a seam a test never used.

assign_params knew a screen's segment was called "feature", which is a
name from the demo's device_feature screen, not something a gem can know.
Trailing segments are just id and param1..n now.
---
 .../ruflet_rails/lib/ruflet/rails/html_dsl.rb     |  4 ++--
 .../lib/ruflet/rails/html_dsl/template_source.rb  | 15 ++++-----------
 2 files changed, 6 insertions(+), 13 deletions(-)

diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
index 679099a3..c31ab1ad 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl.rb
@@ -38,8 +38,8 @@ module HtmlDsl
     # host verbatim.
     #
     # A `fetcher:` can be injected for tests.
-    def erb_to_native(page, start_url: "/", layout: nil, **opts)
-      opts[:fetcher] ||= HtmlDsl::TemplateSource.new(layout: layout)
+    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
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
index e425b100..ec564471 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
@@ -24,9 +24,7 @@ module HtmlDsl
       class TemplateSource
         Response = Struct.new(:status, :body, :url, keyword_init: true)
 
-        def initialize(view_paths: nil, layout: nil)
-          @view_paths = view_paths
-          @layout = layout
+        def initialize
           @controllers = {}
           @session = indifferent({})
           @templates = {}
@@ -80,11 +78,10 @@ def invoke(controller, action)
         end
 
         # Params arrive from a form's fields and from trailing path segments
-        # (/native/device/camera), not from a Rack env.
+        # (/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 }
-          values["feature"] = path_params.first if path_params.respond_to?(:first) && path_params.first
           (form_params || {}).each { |key, value| values[key.to_s] = value }
           controller.ruflet_screen_params = indifferent(values)
         end
@@ -117,11 +114,7 @@ def render(screen, controller)
           # 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 do
-            next view.render(template: "#{prefix}/#{action}", layout: @layout) if @layout
-
-            template_for_render(prefix, action).render(view, {})
-          end
+          silence_view_logging { template_for_render(prefix, action).render(view, {}) }
         end
 
         # Per-thread, so a concurrent web request keeps its own logging.
@@ -221,7 +214,7 @@ def reset_view_class!
         def view_class = self.class.view_class
 
         def build_lookup_context(prefixes = [])
-          ActionView::LookupContext.new(@view_paths || ::ActionController::Base.view_paths, {}, prefixes)
+          ActionView::LookupContext.new(::ActionController::Base.view_paths, {}, prefixes)
         end
 
 

From da8a7120c6d49bf6e16941a1805e6fb30c2cd6a4 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Sat, 8 Aug 2026 01:20:11 -0400
Subject: [PATCH 28/30] Stop describing screens as HTTP

Nothing has made a request since TemplateSource replaced RackFetcher, but
the shape survived it: an on-click carried a verb, a form carried a
method, and a screen came back wrapped in a status code.

The status was not merely decorative. render_result treated anything >=400
as a Rails error page, so it threw away the markup TemplateSource writes
for a missing or failed screen and substituted "HTTP 404 / Server error".
A screen that says which path had no action now survives to the client.

A leading verb on an on-click is stripped rather than obeyed, so existing
"post:/path" markup keeps working.
---
 .../lib/ruflet/rails/html_dsl/html_app.rb     | 42 ++++------------
 .../ruflet/rails/html_dsl/template_source.rb  | 10 ++--
 .../lib/ruflet/rails/html_dsl/transformer.rb  | 32 +++++--------
 packages/ruflet_rails/test/html_app_test.rb   | 48 ++++++-------------
 .../test/html_dsl_helpers_test.rb             |  4 +-
 packages/ruflet_rails/test/html_dsl_test.rb   | 13 +++--
 6 files changed, 51 insertions(+), 98 deletions(-)

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
index 5699f0f8..93238bf3 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -24,7 +24,7 @@ def initialize(app, screen)
           end
 
           def navigate(url, mode) = @app.navigate(url, mode)
-          def action(method:, url:) = @app.action(method: method, url: url, from: @screen)
+          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)
@@ -73,11 +73,11 @@ def navigate(url, mode)
 
         # 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(method:, url:, from: nil)
+        def action(url:, from: nil)
           screen = from || @screens.last
           return unless screen
 
-          response = request(method, absolute_url(url))
+          response = request(absolute_url(url))
           rerender(screen, response)
         end
 
@@ -89,7 +89,7 @@ def submit_form(form, from: nil)
             value = screen.fields.key?(name) ? screen.fields[name] : form[:fields][name]
             collected[name] = value.nil? ? "" : value
           end
-          response = request(form[:method], absolute_url(form[:action]), params: params)
+          response = request(absolute_url(form[:action]), params: params)
           rerender(screen, response)
         end
 
@@ -394,7 +394,7 @@ def push_screen(url, root: false)
           invalidate_pending_services
           screen = Screen.new(url: url, root: root, fields: {})
           screen.route = root ? "/" : "/screen/#{@route_seq += 1}"
-          response = request("get", url)
+          response = request(url)
           result = render_result(screen, response)
           screen.view = build_view(screen, result)
           remember_chrome(screen, result)
@@ -1165,15 +1165,14 @@ def chrome_sig(control)
         def render_result(screen, response)
           screen.url = response.url.to_s unless response.url.to_s.empty?
           screen.fields = {}
-          body = error_status?(response.status) ? server_error_markup(response) : response.body.to_s
+          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?
-            message = response.status.to_i >= 400 ? "HTTP #{response.status} — #{screen.url}" : "Empty screen"
-            result.controls = [container(content: text(message), alignment: { x: 0, y: 0 }, expand: true)]
+            result.controls = [container(content: text("Empty screen"), alignment: { x: 0, y: 0 }, expand: true)]
           end
           result
         end
@@ -1197,28 +1196,7 @@ def asset_base_url
           nil
         end
 
-        # 422 is the Rails convention for re-rendering a form with validation
-        # errors — that body is a real screen. Other error statuses carry a
-        # Rails error page (dev exception pages are a full web document).
-        def error_status?(status)
-          status = status.to_i
-          status >= 400 && status != 422
-        end
 
-        # Surface the error page's title as a compact native screen instead of
-        # trying to render the page itself.
-        def server_error_markup(response)
-          title = response.body.to_s[%r{<title>(.*?)</title>}m, 1].to_s.strip
-          title = "Server error" if title.empty?
-          <<~HTML
-            <column class="p-6 gap-2">
-              <h3>HTTP #{response.status}</h3>
-              <text class="font-semibold text-red-600">#{ERB::Util.html_escape(title)}</text>
-              <text class="text-slate-500">#{ERB::Util.html_escape(response.url)}</text>
-              <text class="text-sm text-slate-400">Check the Rails server log for the full trace.</text>
-            </column>
-          HTML
-        end
 
         def build_view(screen, result)
           args = { route: screen.route }
@@ -1263,10 +1241,10 @@ def flush
 
         # --- HTTP -----------------------------------------------------------------
 
-        def request(method, url, params: nil)
-          @fetcher.fetch(method, url, params: params)
+        def request(url, params: nil)
+          @fetcher.fetch(url, params: params)
         rescue StandardError => e
-          TemplateSource::Response.new(status: 0, body: error_markup(url, e), url: url)
+          TemplateSource::Response.new(body: error_markup(url, e), url: url)
         end
 
         def error_markup(url, error)
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
index ec564471..87af6152 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/template_source.rb
@@ -22,7 +22,7 @@ module HtmlDsl
       # an ordinary `@count` survives from one tap to the next.
       #
       class TemplateSource
-        Response = Struct.new(:status, :body, :url, keyword_init: true)
+        Response = Struct.new(:body, :url, keyword_init: true)
 
         def initialize
           @controllers = {}
@@ -31,7 +31,7 @@ def initialize
           @lookups = {}
         end
 
-        def fetch(_method, url, params: nil)
+        def fetch(url, params: nil)
           path = URI.parse(url.to_s).path.to_s
           screen = NativeScreens.resolve(path)
           return missing(url, path) unless screen
@@ -47,9 +47,9 @@ def fetch(_method, url, params: nil)
           own = template_action(screen)
           invoke(controller, own) if own && own != screen[:action].to_s
 
-          Response.new(status: 200, body: render(screen, controller), url: url)
+          Response.new(body: render(screen, controller), url: url)
         rescue StandardError => e
-          Response.new(status: 500, body: failure_markup(path, e), url: url)
+          Response.new(body: failure_markup(path, e), url: url)
         end
 
         private
@@ -219,7 +219,7 @@ def build_lookup_context(prefixes = [])
 
 
         def missing(url, path)
-          Response.new(status: 404, body: <<~HTML, url: url)
+          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>
diff --git a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
index f64eb123..18a9d097 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/transformer.rb
@@ -325,7 +325,7 @@ def build_button(element, form:)
               register_on_load(element)
               service_handler(element)
             elsif element["on-click"]
-              action_handler(element["on-click"], default_method: "post")
+              action_handler(element["on-click"])
             elsif element["href"]
               navigation_handler(element["href"], element["nav"] || "push")
             elsif form
@@ -439,8 +439,7 @@ def build_select(element, form:)
         def build_form(element, styles)
           form = {
             action: element["action"].to_s,
-            method: (element["method"] || "post").downcase,
-            fields: {}
+                        fields: {}
           }
           children = build_children(element.children, form: form)
           wrap_in_box(column(children, **flex_props(styles, axis: "column")), styles)
@@ -546,7 +545,7 @@ def build_list_tile(element)
           props[:trailing] = element["trailing"] if element["trailing"]
           handler =
             if element["on-click"]
-              action_handler(element["on-click"], default_method: "post")
+              action_handler(element["on-click"])
             elsif element["href"]
               navigation_handler(element["href"], element["nav"] || "push")
             end
@@ -641,7 +640,7 @@ def build_chip(element)
           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"], default_method: "post")
+            props[:on_click] = action_handler(element["on-click"])
           elsif element["href"]
             props[:on_click] = navigation_handler(element["href"], element["nav"] || "push")
           end
@@ -668,7 +667,7 @@ def extract_fab(element)
           props[:content] = text(label) unless label.to_s.empty?
           handler =
             if element["on-click"]
-              action_handler(element["on-click"], default_method: "post")
+              action_handler(element["on-click"])
             elsif element["href"]
               navigation_handler(element["href"], element["nav"] || "push")
             end
@@ -1003,7 +1002,7 @@ def extract_appbar(element)
 
         def appbar_action_handler(action)
           if action["on-click"]
-            action_handler(action["on-click"], default_method: "post")
+            action_handler(action["on-click"])
           else
             navigation_handler(action["href"].to_s, action["nav"] || "push")
           end
@@ -1018,10 +1017,13 @@ def navigation_handler(url, mode)
 
         # `on-click="post:/counter/increment"`, `on-click="/refresh"` (POST by
         # default), `on-click="get:/search"`.
-        def action_handler(spec, default_method:)
-          method, url = parse_action(spec, default_method)
+        # 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(method: method, url: url) }
+          ->(_event) { handlers.action(url: url) }
         end
 
         def submit_handler(form)
@@ -1043,14 +1045,6 @@ def register_field(form, name, initial)
           @handlers.field_changed(name, initial) if @handlers.respond_to?(:field_changed)
         end
 
-        def parse_action(spec, default_method)
-          spec = spec.to_s
-          if spec =~ /\A(get|post|put|patch|delete):(.+)\z/i
-            [Regexp.last_match(1).downcase, Regexp.last_match(2)]
-          else
-            [default_method, spec]
-          end
-        end
 
         def event_value(event)
           data = event.respond_to?(:data) ? event.data : event
@@ -1068,7 +1062,7 @@ def finalize(control, element)
           return control unless spec
           return control if SELF_CLICKING_TAGS.include?(element.tag)
 
-          gesture_detector(content: control, on_tap: action_handler(spec, default_method: "post"))
+          gesture_detector(content: control, on_tap: action_handler(spec))
         end
 
         # --- props & styling -------------------------------------------------------
diff --git a/packages/ruflet_rails/test/html_app_test.rb b/packages/ruflet_rails/test/html_app_test.rb
index 9c9b46cd..89a91aa1 100644
--- a/packages/ruflet_rails/test/html_app_test.rb
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -5,7 +5,7 @@
 # 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 method+path and records every request.
+  # Serves canned HTML per path and records every screen asked for.
   class StubFetcher
     Response = Ruflet::Rails::HtmlDsl::TemplateSource::Response
 
@@ -16,12 +16,12 @@ def initialize(pages)
       @requests = []
     end
 
-    def fetch(method, url, params: nil, headers: {})
-      @requests << { method: method.to_s, url: url, params: params, headers: headers }
+    def fetch(url, params: nil)
+      @requests << { url: url, params: params }
       path = URI.parse(url).path
-      body = @pages.fetch("#{method} #{path}") { @pages.fetch(path, "<text>missing #{path}</text>") }
+      body = @pages.fetch(path, "<text>missing #{path}</text>")
       body = body.call(params) if body.respond_to?(:call)
-      Response.new(status: 200, body: body, url: url)
+      Response.new(body: body, url: url)
     end
   end
 
@@ -87,7 +87,7 @@ def test_action_rerenders_the_screen_in_place
     count = 0
     pages = {
       "/" => -> (_params) { "<text>count #{count}</text><button on-click=\"/inc\">+</button>" },
-      "post /inc" => -> (_params) { count += 1; "<text>count #{count}</text><button on-click=\"/inc\">+</button>" }
+      "/inc" => -> (_params) { count += 1; "<text>count #{count}</text><button on-click=\"/inc\">+</button>" }
     }
     start(pages)
 
@@ -96,7 +96,6 @@ def test_action_rerenders_the_screen_in_place
 
     assert_equal 1, @page.views.length
     assert_equal "count 1", find(@page.views.first, "text").props["value"]
-    assert_equal "post", @fetcher.requests.last["method"] || @fetcher.requests.last[:method]
   end
 
   def test_form_submits_tracked_field_values
@@ -111,7 +110,7 @@ def test_form_submits_tracked_field_values
           </form>
         </body></html>
       HTML
-      "post /session" => ->(params) { submitted = params; "<text>done</text>" }
+      "/session" => ->(params) { submitted = params; "<text>done</text>" }
     }
     start(pages)
 
@@ -611,13 +610,13 @@ def test_expanding_screens_do_not_scroll_but_normal_screens_do
     assert_equal "auto", body.props["scroll"]
   end
 
-  # Net::HTTP returns ASCII-8BIT bodies; binary text values would be packed
-  # as msgpack bin and render as byte arrays on the client.
+  # 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(_m, url, params: nil, headers: {})
+    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(status: 200, body: body, url: url)
+      Ruflet::Rails::HtmlDsl::TemplateSource::Response.new(body: body, url: url)
     end
     Ruflet::Rails.erb_to_native(@page, start_url: "https://app.test/", fetcher: fetcher)
 
@@ -626,23 +625,6 @@ def fetcher.fetch(_m, url, params: nil, headers: {})
     assert_equal "Ruflet Native — démo", value
   end
 
-  def test_server_error_pages_render_a_compact_error_screen
-    fetcher = Object.new
-    def fetcher.fetch(_m, url, params: nil, headers: {})
-      Ruflet::Rails::HtmlDsl::TemplateSource::Response.new(
-        status: 500,
-        body: "<html><head><title>ActionController::RoutingError</title></head>" \
-              '<body><header><button onclick="x()">rails page</button></header></body></html>',
-        url: url
-      )
-    end
-    Ruflet::Rails.erb_to_native(@page, start_url: "https://app.test/native", fetcher: fetcher)
-
-    texts = find_all_text_values(@page.views.first)
-    assert_includes texts.join(" "), "HTTP 500"
-    assert_includes texts.join(" "), "ActionController::RoutingError"
-    refute_includes texts.join(" "), "rails page"
-  end
 
   def find_all_text_values(node, values = [])
     case node
@@ -729,7 +711,7 @@ def test_rerender_patches_only_the_controls_whose_props_changed
     }
     start(
       "/" => markup,
-      "post /up" => lambda { |params|
+      "/up" => lambda { |params|
         count += 1
         markup.call(params)
       }
@@ -752,13 +734,13 @@ def test_rerender_replaces_the_body_when_the_shape_changes
     shape = "<column><text>one</text></column>"
     app = start(
       "/" => ->(_params) { shape },
-      "post /toggle" => lambda { |_params|
+      "/toggle" => lambda { |_params|
         shape = "<column><text>one</text><text>two</text></column>"
         shape
       }
     )
 
-    app.action(method: "post", url: "/toggle")
+    app.action(url: "/toggle")
 
     texts = []
     collect = lambda do |node|
@@ -779,7 +761,7 @@ def test_state_written_on_one_screen_is_visible_on_the_next
     store = []
     app = start(
       "/" => '<button on-click="post:/items">Add</button>',
-      "post /items" => lambda { |_params|
+      "/items" => lambda { |_params|
         store << "item"
         "<text>added</text>"
       },
diff --git a/packages/ruflet_rails/test/html_dsl_helpers_test.rb b/packages/ruflet_rails/test/html_dsl_helpers_test.rb
index c258793e..819d9db7 100644
--- a/packages/ruflet_rails/test/html_dsl_helpers_test.rb
+++ b/packages/ruflet_rails/test/html_dsl_helpers_test.rb
@@ -20,7 +20,7 @@ def initialize
     end
 
     def navigate(url, mode) = @navigations << [url, mode]
-    def action(method:, url:) = @actions << [method, url]
+    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]
@@ -155,7 +155,7 @@ def test_helper_markup_round_trips_through_the_transformer
     assert_equal 32, heading.props["size"]
 
     find(column, "filledbutton").emit("click", nil)
-    assert_equal [["post", "/inc"]], handlers.actions
+    assert_equal ["/inc"], handlers.actions
 
     find(column, "textbutton").emit("click", nil)
     assert_equal [["/settings", "push"]], handlers.navigations
diff --git a/packages/ruflet_rails/test/html_dsl_test.rb b/packages/ruflet_rails/test/html_dsl_test.rb
index 5afd4bf4..666a87b2 100644
--- a/packages/ruflet_rails/test/html_dsl_test.rb
+++ b/packages/ruflet_rails/test/html_dsl_test.rb
@@ -19,7 +19,7 @@ def initialize
     end
 
     def navigate(url, mode) = @navigations << [url, mode]
-    def action(method:, url:) = @actions << [method, url]
+    def action(url:) = @actions << url
     def submit_form(form) = @submissions << form
     def field_changed(name, value) = @fields[name] = value
     def service(spec) = @services << spec
@@ -471,7 +471,7 @@ def test_buttons_post_actions
 
     button = result.controls.first
     button.emit("click", nil)
-    assert_equal [["post", "/counter/increment"]], handlers.actions
+    assert_equal ["/counter/increment"], handlers.actions
   end
 
   def test_service_button_runs_a_native_service_on_tap
@@ -493,7 +493,7 @@ def test_button_variants_and_explicit_methods
     button = result.controls.first
     assert_equal "outlinedbutton", button.type
     button.emit("click", nil)
-    assert_equal [["delete", "/items/3"]], handlers.actions
+    assert_equal ["/items/3"], handlers.actions
   end
 
   def test_on_click_on_plain_elements_wraps_in_gesture_detector
@@ -502,7 +502,7 @@ def test_on_click_on_plain_elements_wraps_in_gesture_detector
     detector = result.controls.first
     assert_equal "gesturedetector", detector.type
     detector.emit("tap", nil)
-    assert_equal [["post", "/open"]], handlers.actions
+    assert_equal ["/open"], handlers.actions
   end
 
   def test_class_styles_apply_to_non_container_controls
@@ -529,7 +529,7 @@ def test_icon_only_button_becomes_an_icon_button
     button = result.controls.first
     assert_equal "iconbutton", button.type
     button.emit("click", nil)
-    assert_equal [["post", "/send"]], handlers.actions
+    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>')
@@ -556,7 +556,6 @@ def test_forms_track_fields_and_submit
     submit.emit("click", nil)
     form = handlers.submissions.first
     assert_equal "/session", form[:action]
-    assert_equal "post", form[:method]
     assert_equal %w[email token], form[:fields].keys.sort
     assert_equal "t1", form[:fields]["token"]
   end
@@ -630,7 +629,7 @@ def test_list_tile_maps_leading_title_subtitle
     # `leading` is an icon slot — the name is normalized to its codepoint.
     refute_nil tile.props["leading"]
     tile.emit("click", nil)
-    assert_equal [["post", "/inbox"]], handlers.actions
+    assert_equal ["/inbox"], handlers.actions
   end
 
   def test_switch_slider_checkbox_as_standalone_tags

From e5007531577086bafd742996c1dbe403e297fed1 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Sat, 8 Aug 2026 23:06:30 -0400
Subject: [PATCH 29/30] Never send a control name as a service argument
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The audio recorder's Record and Stop buttons carry indicator-target,
record-target and stop-target: names of controls to update when recording
starts and stops. They were not in the meta-key list, so they went to the
device as arguments to audio_recorder_start, which has no such parameters
— the client could not match the call and the tap did nothing.

Listing three more names would have left the next invented one broken, so
match the shape: an attribute ending in -target names a control, never an
argument.
---
 .../ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

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
index 93238bf3..c926d3f9 100644
--- a/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
+++ b/packages/ruflet_rails/lib/ruflet/rails/html_dsl/html_app.rb
@@ -443,10 +443,17 @@ def mount_services(result)
         # 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 result-target capture-target preview-target id disabled
+          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/
@@ -858,6 +865,7 @@ 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?
 

From 4cc920658da49a1216942dfafa8f1c9584579636 Mon Sep 17 00:00:00 2001
From: AdamMusa <adammusa2222@gmail.com>
Date: Sat, 8 Aug 2026 23:12:49 -0400
Subject: [PATCH 30/30] Cover the service argument rule with a test

The recorder's whole cycle depends on it: start, stop, autoplay, start
again all work once no control name reaches the device as an argument.
---
 packages/ruflet_rails/test/html_app_test.rb | 24 +++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/packages/ruflet_rails/test/html_app_test.rb b/packages/ruflet_rails/test/html_app_test.rb
index 89a91aa1..39e0e689 100644
--- a/packages/ruflet_rails/test/html_app_test.rb
+++ b/packages/ruflet_rails/test/html_app_test.rb
@@ -843,6 +843,30 @@ def test_a_path_start_url_keeps_query_strings_on_relative_links
     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