ruflet_rails 0.0.11 → 0.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebf6ba0607ab65bf23420e9d03d39283aac94ad1ffd92bcd6e96c21fa7d79c9a
-  data.tar.gz: 74bba5b6bbf7976457a49556f5ee3c81c42f7afe30ede8979e5cf6f3f4e77354
+  metadata.gz: dc30304299f6e6c539c8fcc838c7f843b54b2d106e6219c657ac8c856c69f9cf
+  data.tar.gz: 52ec66b70428d3d1d4ff2d3d7ac4cf6bae34b497addd74e6ba39f8f9c3cc5d3f
 SHA512:
-  metadata.gz: d1027674f71e87d89e24e2ca90bb9906fe60a67b7f23d93b30e90e053e7a710439fe8d22774976f9c83cdbf83ca82b28aa6610eeec6178d413430fa105ced16c
-  data.tar.gz: e55b5f9c8a3549fb37833f5cc88d9950cf35428a2bd688884205b6c83a1ff7d68c627a25469a5893d0b81dd445d5c697fe66b80dcac91c57ae129748da9f1e6b
+  metadata.gz: 976c713a63c7a6f3663fbd2541474008e010947a81c6d205cb43f318d6e6fbdaae59c71564f145f34311570518c1910ead0f0278173e270f9ce6bbda3bd4d659
+  data.tar.gz: 88d2668bd895b3e817bae881f65ab8fa395ec54377b850a9f7aef163bcf1caa96982656103fdeb8b6034a40271ae1c4dfe80ae43a7f987fd0cf816e56f28cb2d

data/README.md

@@ -2,17 +2,18 @@
 
 `ruflet_rails` is the Rails-first integration package for Ruflet.
 
-Internal Rails transport/protocol code is bundled inside this gem as `Ruflet::Rails::Protocol`.
-No separate protocol gem is required.
+It mounts Ruby-driven Ruflet interfaces in a Rails application, makes Rails
+models available to Ruflet components, and connects web, mobile, and desktop
+clients to the same application entrypoint.
 
-## Usage
+## Add The Gem
 
 ```ruby
 # Gemfile
-gem "ruflet_rails", ">= 0.0.5"
+gem "ruflet_rails"
 ```
 
-## Install into Rails
+## Install Into Rails
 
 ```bash
 bin/rails generate ruflet:install
@@ -24,7 +25,8 @@ bin/rails generate ruflet:install --web --desktop
 This generator will:
 - create `app/views/ruflet/main.rb`
 - create `ruflet.yaml`
-- add the Ruflet mount route to `config/routes.rb`
+- add the Ruflet WebSocket route to `config/routes.rb`
+- add a `/ruflet` web mount when `--web` is used
 - download prebuilt clients from GitHub releases when `--web`, `--desktop`, or
   `--client=web|desktop|all` is used
 
@@ -44,12 +46,30 @@ assets:
 
 For Rails apps, those asset paths are resolved from `app/assets/` during build.
 
-## Build client from Rails
+## Web client
 
-Uses the same build pipeline as `ruflet build`:
+Rails installs the prebuilt web client into `frontend/`; it does not need
+Flutter source or a Flutter web build:
+
+```bash
+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"
+```
+
+The install generator adds the same mount at `/ruflet` when `--web` is used.
+The mount serves the static client and its WebSocket endpoint together. The
+same `main.rb` also drives native clients through the generated `/ws` route.
+
+## Build native clients from Rails
+
+Uses the same native build pipeline as `ruflet build`:
 
 ```bash
-bundle exec rake ruflet:build[web]
 bundle exec rake ruflet:build[macos]
 bundle exec rake ruflet:build[windows]
 bundle exec rake ruflet:build[linux]
@@ -59,8 +79,6 @@ bundle exec rake ruflet:build[ios]
 bundle exec rake ruflet:build[aab]
 ```
 
-Rails web builds are published to `public/ruflet` and served by Rails at `/ruflet/`.
-
 `desktop` is also accepted as a host-platform alias:
 
 ```bash
@@ -82,16 +100,14 @@ bin/rails s --desktop
 
 ## Update prebuilt clients
 
-Uses the same GitHub release assets as `ruflet update`:
+Reinstall web or update native desktop clients:
 
 ```bash
-bundle exec rake ruflet:update[web]
+bundle exec rake ruflet:web
 bundle exec rake ruflet:update[desktop]
-bundle exec rake ruflet:update[all]
 ```
 
-For web, the downloaded static client is published to `public/ruflet` and served
-by Rails at `/ruflet/`. The Rails app does not vendor Flutter source code.
+The Rails app does not vendor Flutter source code.
 
 ## Install mobile build
 
@@ -104,39 +120,18 @@ bundle exec rake ruflet:install[DEVICE_ID]
 
 ## Ruflet resource scaffolds
 
-Generate a Ruflet CRUD view for an existing Rails model:
+The standard Rails scaffold command also generates a mountable Ruflet CRUD
+component:
 
 ```bash
-bin/rails generate ruflet:scaffold Post
+bin/rails generate scaffold Post title:string body:text published:boolean
 ```
 
-The scaffold creates generated app code the Rails developer can own and edit:
+The Rails model attributes are passed to the Ruflet component generator. The
+scaffold creates generated application code the Rails developer can own and
+edit:
 
 ```ruby
-# app/views/ruflet/posts_view.rb
-require_relative "components/posts/post_component"
-
-class PostView < RufletView
-  include Ruflet::Rails::FormHelpers
-
-  route "/posts"
-
-  def render
-    page.title = resource_title
-    render_index
-  end
-
-  private
-
-  def records
-    # edit resource query logic here
-  end
-
-  def component
-    @component ||= PostComponent.new(page, controller: self)
-  end
-end
-
 # app/views/ruflet/components/posts/post_component.rb
 class PostComponent < Ruflet::Rails::ResourceComponent
   def render
@@ -145,11 +140,19 @@ class PostComponent < Ruflet::Rails::ResourceComponent
 end
 ```
 
-The generated view contains the resource logic: query, model helpers, field
-introspection, save/delete, dialog close, and display formatting. The generated
-component contains the UI: tables, lists, and dialogs. `ruflet_rails` only
-provides the base classes and generic helpers. The generator does not dump field
-declarations like `title:string` or literal metadata tables into the app.
+Mount it explicitly in `config/routes.rb`:
+
+```ruby
+mount Ruflet::Rails.web_app(view: "PostComponent"), at: "/posts"
+```
+
+The generated component contains the developer-owned UI and persistence calls.
+`ruflet_rails` provides the reusable model, navigation, dialog, and formatting
+helpers. Component files under `app/views/ruflet/components` are loaded by the
+Railtie so both web mounts and `main.rb` can reference them.
+
+Use `--skip-ruflet` when a Rails scaffold should not generate a Ruflet
+component.
 
 ## Ruflet model forms
 
@@ -175,8 +178,8 @@ when that base component does not already exist.
 
 ## Shared Ruflet components
 
-Put shared Ruflet UI components under `app/views/ruflet/components`. Component
-files are loaded before `*_view.rb` files, so views can call them directly:
+Put shared Ruflet UI components under `app/views/ruflet/components`. Those files
+are reloaded with Rails application code:
 
 ```ruby
 # app/views/ruflet/components/page_title_component.rb
@@ -188,11 +191,9 @@ end
 ```
 
 ```ruby
-# app/views/ruflet/posts/posts_view.rb
-class PostsView < RufletView
-  def render
-    page.add(PageTitleComponent.render(page, "Posts"))
-  end
+# app/views/ruflet/main.rb
+Ruflet.run do |page|
+  page.add(PageTitleComponent.render(page, "Posts"))
 end
 ```
 

data/lib/generators/ruflet/install/install_generator.rb

@@ -6,8 +6,9 @@ require "ruflet/rails/install_support"
 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: "Download prebuilt client from GitHub releases: desktop or none"
+      class_option :client, type: :string, default: nil, desc: "Install prebuilt clients: web, desktop, all, or none"
 
       desc "Install Ruflet into a Rails app."
 
@@ -25,11 +26,24 @@ module Ruflet
         create_file target, Ruflet::Rails::InstallSupport.default_ruflet_yaml(app_name: app_name)
       end
 
-      def create_ruflet_initializer
-        target = File.join(destination_root, Ruflet::Rails::InstallSupport.initializer_path)
-        return if File.exist?(target)
+      # Mount the native WebSocket endpoint explicitly in config/routes.rb.
+      # Nothing is auto-mounted — the dev owns the route, like any other.
+      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(")
+
+        route Ruflet::Rails::InstallSupport.route_snippet(entrypoint: entrypoint_path)
+      end
+
+      def mount_web_app
+        return unless web_requested?
+
+        routes = File.join(destination_root, "config", "routes.rb")
+        return unless File.file?(routes)
+        return if File.read(routes).include?("Ruflet::Rails.web_app(")
 
-        create_file target, Ruflet::Rails::InstallSupport.initializer_template(entrypoint: entrypoint_path)
+        route Ruflet::Rails::InstallSupport.web_route_snippet(entrypoint: entrypoint_path)
       end
 
       def add_desktop_flag_to_binstubs
@@ -43,14 +57,8 @@ module Ruflet
         client = requested_client
         return if client == "none"
 
-        require "ruflet/cli"
-        exit_code = Dir.chdir(destination_root) do
-          Ruflet::CLI.command_update([client])
-        end
-        unless exit_code.to_i.zero?
-          @client_download_failed = true
-          say_status(:warn, "Ruflet client download failed; install files were generated and build/update steps are printed below", :yellow)
-        end
+        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
         say_status(:warn, "Ruflet client download failed: #{e.class}: #{e.message}", :yellow)
@@ -77,24 +85,47 @@ module Ruflet
       def requested_client
         explicit = options[:client].to_s.strip.downcase
         unless explicit.empty?
-          raise Thor::Error, "--client must be desktop or none" unless %w[desktop none].include?(explicit)
+          raise Thor::Error, "--client must be web, desktop, all, or none" unless %w[web desktop all none].include?(explicit)
 
           return explicit
         end
 
+        return "all" if options[:web] && options[:desktop]
+        return "web" if options[:web]
         return "desktop" if options[:desktop]
 
         "none"
       end
 
       def desktop_requested?
-        requested_client == "desktop"
+        %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"]) }
+        client_download_failed("desktop") unless exit_code.to_i.zero?
+      end
+
+      def client_download_failed(client)
+        @client_download_failed = true
+        say_status(:warn, "Ruflet #{client} client download failed; install files were still generated", :yellow)
+      end
+
       def install_desktop_flag_bootstrap(relative_path)
         target = File.join(destination_root, relative_path)
         return unless File.file?(target)

data/lib/ruflet/rails/configuration.rb

@@ -4,20 +4,14 @@ module Ruflet
   module Rails
     # Central configuration for ruflet_rails.
     #
-    # Mirrors the full ruflet.yaml schema so a Rails app needs only
-    # config/initializers/ruflet.rb — no ruflet.yaml on disk.
-    #
-    # Set in config/initializers/ruflet.rb:
+    # An install needs no config/initializers/ruflet.rb: routes mount
+    # app/views/ruflet/main.rb explicitly and build metadata is read from
+    # ruflet.yaml. Add an initializer only to override these settings:
     #
     #   Ruflet::Rails.configure do |config|
     #     # Runtime / server
-    #     config.app_file    = Rails.root.join("app/views/ruflet/main.rb")
-    #     config.ws_path     = "/ws"
     #     config.backend_url = Rails.env.production? ? "https://example.com" : "http://localhost:3000"
     #
-    #     # Flutter web build output directory
-    #     config.web_build_dir = Rails.root.join("public/app")
-    #
     #     # App metadata (ruflet.yaml → app:)
     #     config.app_name = "My App"
     #
@@ -43,19 +37,10 @@ module Ruflet
     class Configuration
       # --- Runtime / server ---
 
-      # Absolute path to the Ruflet app entry-point.
-      attr_accessor :app_file
-
-      # URL path the WebSocket endpoint listens on. Defaults to "/ws".
-      attr_accessor :ws_path
-
       # Backend base URL. Used as --dart-define=RUFLET_URL at build time
       # and by the desktop launcher. Replaces ruflet.yaml → app.backend_url.
       attr_accessor :backend_url
 
-      # Absolute directory containing the Flutter web build (index.html + assets).
-      attr_accessor :web_build_dir
-
       # --- App metadata (ruflet.yaml → app:) ---
 
       attr_accessor :app_name
@@ -83,12 +68,9 @@ module Ruflet
       attr_accessor :theme_color
 
       def initialize
-        @ws_path      = "/ws"
-        @app_file     = nil
-        @backend_url  = nil
-        @web_build_dir = nil
-        @app_name     = nil
-        @services     = []
+        @backend_url = nil
+        @app_name = nil
+        @services = []
       end
 
       # Serialises config to the ruflet.yaml hash structure so the CLI can

data/lib/ruflet/rails/generator_hooks.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ruflet
+  module Rails
+    module GeneratorHooks
+      module_function
+
+      def install!
+        require "active_support/core_ext/string/filters"
+        require "rails/generators/rails/scaffold/scaffold_generator"
+        require "generators/ruflet/scaffold/scaffold_generator"
+
+        generator = ::Rails::Generators::ScaffoldGenerator
+        return if generator.class_options.key?(:ruflet)
+
+        generator.hook_for(
+          :ruflet,
+          type: :boolean,
+          default: true,
+          desc: "Generate a Ruflet resource component"
+        )
+      end
+    end
+  end
+end

data/lib/ruflet/rails/install_support.rb

@@ -10,18 +10,33 @@ module Ruflet
       module_function
 
       def default_app_template(app_title:)
-        template = <<~RUBY
-          require "ruflet"
-          require "ruflet_rails"
-
-          Ruflet::Rails.load_views(__dir__)
+        <<~RUBY
+          # frozen_string_literal: true
 
+          # The home screen for this Ruflet app. You own this file — declare your
+          # screens here; nothing is auto-discovered. It is mounted explicitly in
+          # config/routes.rb (the install generator adds this line):
+          #   match "/ws", to: Ruflet::Rails.app(Rails.root.join("app/views/ruflet/main.rb")), via: :all
           Ruflet.run do |page|
             page.title = #{app_title.inspect}
-            Ruflet::Rails.render(page)
+            page.add(
+              safe_area(
+                container(
+                  expand: true,
+                  padding: 24,
+                  content: column(
+                    spacing: 12,
+                    controls: [
+                      text(#{app_title.inspect}, size: 24, weight: "bold"),
+                      text("Edit app/views/ruflet/main.rb to build your app.")
+                    ]
+                  )
+                ),
+                expand: true
+              )
+            )
           end
         RUBY
-        template.gsub(/^    /, "  ")
       end
 
       def application_component_template
@@ -90,10 +105,6 @@ module Ruflet
         File.join("app", "views", "ruflet", "components", "application_component.rb")
       end
 
-      def default_mobile_app_template(app_title:)
-        default_app_template(app_title: app_title)
-      end
-
       def model_names(model_name)
         raw = model_name.to_s.strip
         class_name = raw.camelize
@@ -673,22 +684,6 @@ module Ruflet
         YAML
       end
 
-      def desktop_initializer_path
-        File.join("config", "initializers", "ruflet_desktop.rb")
-      end
-
-      def desktop_initializer_template
-        <<~RUBY
-          # frozen_string_literal: true
-
-          # Set this to true when you intentionally want the Rails server process to
-          # launch the server-driven Ruflet desktop client.
-          Rails.application.configure do
-            config.x.ruflet_rails.desktop = false
-          end
-        RUBY
-      end
-
       def ruby_desktop_flag_bootstrap
         <<~RUBY
           # ruflet_rails desktop flag
@@ -746,70 +741,41 @@ module Ruflet
         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"
 
-        args = [normalized]
-        args += ["--dart-define", "RUFLET_URL=#{ruflet_url}"] if normalized == "web" && ruflet_url.to_s.strip != ""
-        args
+        [normalized]
       end
 
       def default_entrypoint_path
         File.join("app", "views", "ruflet", "main.rb")
       end
 
-      def initializer_template(entrypoint: default_entrypoint_path, ws_path: "/ws")
-        <<~RUBY
-          # frozen_string_literal: true
-
-          Ruflet::Rails.configure do |config|
-            # Ruflet app entry-point. Auto-mounts a WebSocket endpoint at ws_path —
-            # no explicit route needed in config/routes.rb.
-            config.app_file = Rails.root.join(#{entrypoint.inspect})
-
-            # URL path the WebSocket endpoint listens on (default: "/ws").
-            config.ws_path = #{ws_path.inspect}
-
-            # Base URL the Flutter client uses to reach this Rails app. Always
-            # required: it backs asset URLs (Ruflet::Rails.asset_url), the
-            # build-time RUFLET_URL define, and the desktop launcher. At runtime
-            # it can fall back to the connecting host, but a build has no request,
-            # so set it here. Point it at a LAN IP (not localhost) to test on a
-            # real device.
-            config.backend_url = ENV.fetch("RUFLET_BACKEND_URL") do
-              Rails.env.production? ? "https://example.com" : "http://localhost:3000"
-            end
-
-            # Directory the Flutter web build is served from. Defaults to
-            # Rails.root/build/web (where `rake ruflet:build[web]` outputs).
-            # Must stay OUTSIDE public/, or Rails would serve it statically and
-            # expose the app at a path no route declares.
-            # config.web_build_dir = Rails.root.join("build", "web")
-          end
-        RUBY
-      end
-
-      def initializer_path
-        File.join("config", "initializers", "ruflet.rb")
-      end
-
       # Kept for backward compatibility with apps that use manual mount.
       def route_snippet(entrypoint: default_entrypoint_path, mount_path: "/ws", helper: "app")
         %(match "#{mount_path}", to: Ruflet::Rails.#{helper}(Rails.root.join("#{entrypoint}")), via: :all)
       end
 
+      def web_route_snippet(entrypoint: default_entrypoint_path, mount_path: "/ruflet")
+        %(mount Ruflet::Rails.web_app(app_file: Rails.root.join("#{entrypoint}")), at: "#{mount_path}")
+      end
+
       def install_next_steps(target:, entrypoint:, client:, mount_path: "/ws")
         lines = [
           "Ruflet Rails installed.",
           "Generated entrypoint: #{entrypoint}",
-          "Mounted websocket: #{mount_path}",
+          "Added WebSocket route #{mount_path} to config/routes.rb",
           "Next steps:",
           "  1. Start Rails: bin/rails server",
           "  2. Connect your Ruflet app to ws://localhost:3000#{mount_path}"
         ]
 
-        if client.to_s == "desktop"
+        if %w[desktop all].include?(client.to_s)
           lines += [
             "Desktop clients are server-driven and connect to this Rails app.",
             "Plain bin/dev, bin/rails server, and bin/rails s do not launch desktop.",
@@ -819,6 +785,13 @@ module Ruflet
           ]
         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

data/lib/ruflet/rails/native_app.rb

@@ -4,7 +4,7 @@ require "uri"
 
 module Ruflet
   module Rails
-    # Hotwire Native-style driver for ruflet_rails.
+    # Managed webview navigation driver for ruflet_rails.
     #
     # Your existing web app is the body, rendered in a WebView. Navigation works
     # out of the box: a tiny JS bridge injected into each page intercepts link
@@ -122,6 +122,7 @@ module Ruflet
         Ruflet::UI::ControlFactory.build(
           :webview,
           url: screen.url,
+          method: "get",
           expand: true,
           on_page_ended: ->(_event) { inject_bridge(screen) },
           on_console_message: ->(event) { handle_message(screen, message_of(event)) }
@@ -190,7 +191,7 @@ module Ruflet
       # --- Modal (bottom sheet of web content) -------------------------------
 
       def present_modal(url)
-        sheet_webview = Ruflet::UI::ControlFactory.build(:webview, url: url.to_s, expand: true)
+        sheet_webview = Ruflet::UI::ControlFactory.build(:webview, url: url.to_s, method: "get", expand: true)
         @modal_sheet = Ruflet::UI::ControlFactory.build(
           :bottomsheet,
           open: true,
@@ -245,7 +246,7 @@ module Ruflet
 
     module_function
 
-    # Start a Hotwire Native-style app. See NativeApp.
+    # Start a managed webview app. See NativeApp.
     def native_app(page, **opts)
       NativeApp.new(page, **opts).start
     end

data/lib/ruflet/rails/protocol/runner.rb

@@ -26,8 +26,6 @@ module Ruflet
             path: path
           )
         end
-        alias build_mobile_endpoint build_app_endpoint
-
         private
 
         def build_server(entrypoint)