ruflet_rails 0.0.11 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebf6ba0607ab65bf23420e9d03d39283aac94ad1ffd92bcd6e96c21fa7d79c9a
-  data.tar.gz: 74bba5b6bbf7976457a49556f5ee3c81c42f7afe30ede8979e5cf6f3f4e77354
+  metadata.gz: d142d63121dae012354a763ef756504d64534adbc4b2c11eaf0dc51b514c6b32
+  data.tar.gz: d3d1e6cbf9af94c81d5514b71325484e547b40ba34afe3d8601a111f08e4af6a
 SHA512:
-  metadata.gz: d1027674f71e87d89e24e2ca90bb9906fe60a67b7f23d93b30e90e053e7a710439fe8d22774976f9c83cdbf83ca82b28aa6610eeec6178d413430fa105ced16c
-  data.tar.gz: e55b5f9c8a3549fb37833f5cc88d9950cf35428a2bd688884205b6c83a1ff7d68c627a25469a5893d0b81dd445d5c697fe66b80dcac91c57ae129748da9f1e6b
+  metadata.gz: daf5bf66b258ece12da18cbb4c455d2f9f5dd141faa3638c2ef0ec9a64d85be9b25d94add15ae0374a96c6694f6e393ee015290df62368bd1d9cd6920a3185f3
+  data.tar.gz: 075def7cfb22688619559ba1ca55ede0d4c152c403c95a2273c1fa322a2862b20aafe7bda0507bf73bb4a8e8f40e03eb6c87b9505900fb31aa3ac08098dbf88b

data/README.md

@@ -24,7 +24,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 +45,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 +78,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 +99,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,7 +119,7 @@ bundle exec rake ruflet:install[DEVICE_ID]
 
 ## Ruflet resource scaffolds
 
-Generate a Ruflet CRUD view for an existing Rails model:
+Generate a mountable Ruflet CRUD component for an existing Rails model:
 
 ```bash
 bin/rails generate ruflet:scaffold Post
@@ -113,30 +128,6 @@ bin/rails generate ruflet:scaffold Post
 The scaffold creates generated app 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 +136,16 @@ 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.
 
 ## Ruflet model forms
 
@@ -175,8 +171,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 +184,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/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/protocol/runner.rb

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