ruflet_core 0.0.18 → 0.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c28a07c8c32f3e0eca58c3d1400f06453275690b4e9f75d3a868a4507e78c74a
-  data.tar.gz: 71f044a3c2f0464571e4d16f779e1f751c42f4e16ea3aeeecb3036b596269022
+  metadata.gz: 7b5d3e1bde28f482994a21faa5d1412808941a9a5f6384df22ec4307d7ce4f35
+  data.tar.gz: d5d90041346619db3781eb5f67747ccf91d9657f4b62ba1edafd806f959bd5a0
 SHA512:
-  metadata.gz: 38de8d3745bbdf5b217e91de9a6dab2a194757964fa39f7a78bb89c83586fb4f0acee955ae7457221b12a15c4ab7fd18465e2a74af58627c8da25d6c75b62463
-  data.tar.gz: 476528dec0a5b55ca3e2a3622d4cf2691162434794a498d544a9da165efb249bca5e612f6ba8f49da52387223441ec34ebe64769f162a78916db0f27bee3dce9
+  metadata.gz: 3b7aa35ac477467d595e0d4e2ce7e246cd5ed309d20bca5a1ef658e4f67735fbc829042750722cf0a513cd300d8621c69977697712e580c5b90d3a482be8377b
+  data.tar.gz: 462a296c2022360be5ce1df9ddb97400fb6c6ec87b7a443681f7104f78c4060cb1350c889b41f3b9ad090ba2be27da6e140cfa7c40a5d4093382faf842303109

data/README.md

@@ -1,3 +1,34 @@
-# ruflet
+# ruflet_core
 
-Part of Ruflet monorepo.
+`ruflet_core` provides Ruflet's Ruby UI API: controls, control builders, page
+operations, events, services, and application lifecycle behavior.
+
+Applications normally receive this package through a generated Ruflet project
+or through `ruflet_rails`; it is not a standalone application server.
+
+```ruby
+require "ruflet"
+
+Ruflet.run do |page|
+  page.title = "Hello"
+  page.add(
+    container(
+      bgcolor: :surface_container_high,
+      padding: 24,
+      content: text(
+        value: "Hello Ruflet",
+        style: { color: "DeepOrange500", size: 20, weight: "w600" }
+      )
+    )
+  )
+end
+```
+
+Color properties accept named colors and hex values. Use Ruby-style symbols
+like `:deep_orange_500`, compact strings like `"DeepOrange500"`, spaced names
+like `"Deep Orange 500"`, semantic theme names like `:primary_container`, or
+hex strings like `"#ff6d00"`. Ruflet normalizes named colors before sending
+them to the client.
+
+Use `ruflet_server` to run a standalone server-driven application. Use
+`ruflet_rails` when the UI is hosted by Rails.

data/lib/ruflet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ruflet
-  VERSION = "0.0.18" unless const_defined?(:VERSION)
+  VERSION = "0.0.20" unless const_defined?(:VERSION)
 end

data/lib/ruflet_protocol/ruflet/protocol.rb

@@ -78,10 +78,28 @@ module Ruflet
       }
     end
 
-    def register_response(session_id:)
+    # The client's reply to `invoke_control_method`: the pending call id plus its
+    # result/error. Ruflet::ConnectionProtocol (ruflet_rails' Rack-hijack adapter
+    # and any other host adapter) normalizes this before handing it to
+    # Page#handle_invoke_method_result, which matches `call_id` back to the
+    # waiting callback. Without this method that path fell through to the DSL's
+    # method_missing and every invoke result was silently discarded.
+    def normalize_invoke_method_result_payload(payload)
+      payload = {} unless payload.is_a?(Hash)
+      {
+        "call_id" => payload["call_id"] || payload["callId"],
+        "result" => payload.key?("result") ? payload["result"] : payload["value"],
+        "error" => payload["error"]
+      }
+    end
+
+    # page_patch defaults to nil rather than {} because mruby cannot parse a
+    # hash literal as a keyword argument default, and this file is compiled
+    # into the embedded VM.
+    def register_response(session_id:, page_patch: nil)
       {
         "session_id" => session_id,
-        "page_patch" => {},
+        "page_patch" => page_patch || {},
         "error" => ""
       }
     end

data/lib/ruflet_ui/ruflet/dsl.rb

@@ -321,6 +321,7 @@ module Ruflet
     def video(**props) = _pending_app.video(**props)
     def code_editor(value = nil, **props) = _pending_app.code_editor(value, **props)
     def codeeditor(value = nil, **props) = _pending_app.codeeditor(value, **props)
+    def lottie(src = nil, **props) = _pending_app.lottie(src, **props)
     def rive(src = nil, **props) = _pending_app.rive(src, **props)
     def fab(content = nil, **props) = _pending_app.fab(content, **props)
     def cupertino_button(content = nil, **props) = _pending_app.cupertino_button(content, **props)

data/lib/ruflet_ui/ruflet/event.rb

@@ -17,6 +17,15 @@ module Ruflet
       @control = control
     end
 
+    # A stable convenience accessor shared by built-in and extension events.
+    # Extension event names are intentionally not part of the core typed-event
+    # registry, so fall back to the same value extraction used by GenericEvent.
+    def value
+      return typed_data.value if typed_data&.respond_to?(:value)
+
+      Events::GenericEvent.from_data(data).value
+    end
+
     private
 
     def parse_data(raw)

data/lib/ruflet_ui/ruflet/extensions/qrcode_scanner.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Ruflet
+  module Extensions
+    class QrCodeScannerControl < Ruflet::Control
+      TYPE = "qrcode_scanner".freeze
+      WIRE = "qrcode_scanner".freeze
+      KEYWORDS = %i[
+        align animate_align animate_margin animate_offset animate_opacity
+        animate_position animate_rotation animate_scale animate_size aspect_ratio
+        auto_start auto_zoom badge bottom camera_facing col data detection_speed
+        detection_timeout disabled expand expand_loose fit formats height
+        invert_image key left margin offset opacity return_image right rotate rtl
+        scale scan_window size_change_interval tap_to_focus tooltip top
+        torch_enabled visible width zoom_scale on_animation_end on_detect on_error
+        on_size_change
+      ].freeze
+
+      def initialize(id: nil, **props)
+        super(type: TYPE, id: id, **props)
+      end
+
+      def start(timeout: 10, on_result: nil)
+        invoke_scanner("start", timeout: timeout, on_result: on_result)
+      end
+
+      def stop(timeout: 10, on_result: nil)
+        invoke_scanner("stop", timeout: timeout, on_result: on_result)
+      end
+
+      def switch_camera(timeout: 10, on_result: nil)
+        invoke_scanner("switch_camera", timeout: timeout, on_result: on_result)
+      end
+
+      def toggle_torch(timeout: 10, on_result: nil)
+        invoke_scanner("toggle_torch", timeout: timeout, on_result: on_result)
+      end
+
+      def set_zoom_scale(value, timeout: 10, on_result: nil)
+        invoke_scanner("set_zoom_scale", args: { "value" => value }, timeout: timeout, on_result: on_result)
+      end
+
+      def reset_zoom_scale(timeout: 10, on_result: nil)
+        invoke_scanner("reset_zoom_scale", timeout: timeout, on_result: on_result)
+      end
+
+      private
+
+      def preprocess_props(props)
+        mapped = props.dup
+        mapped[:formats] = Array(mapped[:formats]).map(&:to_s) if mapped.key?(:formats)
+        mapped["formats"] = Array(mapped["formats"]).map(&:to_s) if mapped.key?("formats")
+        mapped
+      end
+
+      def invoke_scanner(name, args: nil, timeout: 10, on_result: nil)
+        runtime_page&.invoke(self, name, args: args, timeout: timeout, on_result: on_result)
+      end
+    end
+
+    register_control(
+      :qrcode_scanner,
+      control_class: QrCodeScannerControl,
+      flutter: {
+        package: "ruflet_qrcode_scanner",
+        import: "package:ruflet_qrcode_scanner/ruflet_qrcode_scanner.dart",
+        alias: "ruflet_qrcode_scanner",
+        constructor: "Extension"
+      }
+    )
+  end
+end

data/lib/ruflet_ui/ruflet/extensions.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Ruflet
+  # Registry used by Ruflet extension gems to add typed Ruby controls and
+  # describe the matching Flet Flutter package. Registering a control makes its
+  # helpers available in the bare DSL, Ruflet::DSL, Ruflet, Ruflet::UI, and
+  # WidgetBuilder without editing Ruflet's generated control method tables.
+  module Extensions
+    Registration = Struct.new(
+      :name,
+      :control_class,
+      :helpers,
+      :flutter,
+      keyword_init: true
+    )
+
+    @registrations = {}
+
+    class << self
+      def register_control(name, control_class:, helpers: nil, flutter: nil)
+        key = normalize_name(name)
+        helper_names = Array(helpers || key).map { |helper| normalize_name(helper) }.uniq.freeze
+        registration = Registration.new(
+          name: key,
+          control_class: control_class,
+          helpers: helper_names,
+          flutter: normalize_flutter_metadata(flutter)
+        ).freeze
+
+        existing = @registrations[key]
+        if existing && existing != registration
+          raise ArgumentError, "Ruflet extension `#{key}` is already registered"
+        end
+
+        helper_names.each do |helper|
+          UI::ControlFactory.register_extension(helper, control_class)
+          define_control_helper(helper)
+        end
+        @registrations[key] = registration
+      end
+
+      def [](name)
+        @registrations[normalize_name(name)]
+      end
+
+      def each(&block)
+        return enum_for(:each) unless block
+
+        @registrations.values.each(&block)
+      end
+
+      def registered?(name)
+        @registrations.key?(normalize_name(name))
+      end
+
+      private
+
+      def normalize_name(value)
+        name = value.to_s.strip.downcase.tr("-", "_")
+        raise ArgumentError, "Extension name cannot be empty" if name.empty?
+        raise ArgumentError, "Invalid extension name `#{value}`" unless name.match?(/\A[a-z][a-z0-9_]*\z/)
+
+        name
+      end
+
+      def normalize_flutter_metadata(metadata)
+        return nil if metadata.nil?
+
+        values = metadata.transform_keys(&:to_sym)
+        package = values.fetch(:package).to_s
+        import = values.fetch(:import, "package:#{package}/#{package}.dart").to_s
+        alias_name = values.fetch(:alias, package).to_s
+        constructor = values.fetch(:constructor, "Extension").to_s
+        {
+          package: package,
+          import: import,
+          alias: alias_name,
+          constructor: constructor
+        }.freeze
+      end
+
+      def define_control_helper(helper)
+        type = helper
+
+        UI::ControlMethods.send(:define_method, helper) do |**props, &block|
+          control(type, **props, &block)
+        end
+
+        UI::SharedControlForwarders.send(:define_method, helper) do |**props, &block|
+          control_delegate.public_send(type, **props, &block)
+        end
+
+        DSL.define_singleton_method(helper) do |**props, &block|
+          _pending_app.public_send(type, **props, &block)
+        end
+
+        Kernel.send(:private, helper) if Kernel.method_defined?(helper)
+      end
+    end
+  end
+end

data/lib/ruflet_ui/ruflet/page.rb

@@ -300,6 +300,90 @@ module Ruflet
       self
     end
 
+    # Complete page state as a property map for the register_client response
+    # (Flet's page_patch). The client applies this through Control.update,
+    # which merges by control id and keeps existing instances alive — the only
+    # patch path that survives a re-register on a client with prior state
+    # (reconnect after a backend restart). The op-based view patch replaces
+    # control instances and detaches containers on such clients.
+    def register_page_patch
+      refresh_control_indexes!
+      patch = { "views" => build_view_patches }
+      @page_props.each { |key, value| patch[key] = serialize_patch_value(value) }
+      @overlay_container_mounted = true if @overlay_container.wire_id
+      @dialogs_container_mounted = true if @dialogs_container.wire_id
+      @services_container_mounted = true if @services_container.wire_id
+      patch
+    end
+
+    # Page props that must survive a hot reload: the route (kept on purpose),
+    # the client-reported window, and the internal overlay/services/dialogs
+    # containers (kept mounted so the client keeps their bindings).
+    RELOAD_PRESERVED_PAGE_PROPS = %w[route window _overlay _dialogs _services].freeze
+
+    # Quietly clears session content and page chrome so a reloaded app block
+    # can re-render on this same Page without recreating it. The page object
+    # must survive a hot reload: a new Page re-sends the internal
+    # overlay/service/dialogs containers, which replaces their client-side
+    # instances and detaches them (see build_page_patch_ops) — after that,
+    # dialog and service patches are silently ignored by the client.
+    #
+    # Chrome (appbar, drawer, FAB, bgcolor, title, ...) lives in @view_props
+    # and @page_props. If the reloaded block no longer sets a piece of chrome,
+    # the previous run's value would linger, so both are cleared here. The
+    # view is fully rebuilt on the next patch, which drops any @view_props not
+    # re-set; page-level props merge on the client, so finalize_reload! sends
+    # explicit nils for the ones that disappeared. Sends nothing itself.
+    def reset_for_reload!
+      @root_controls = []
+      @views = []
+      @dialogs = []
+      @dialog = nil
+      @snack_bar = nil
+      @bottom_sheet = nil
+      @route_change_seen_since_reset = false
+
+      @reload_prior_page_prop_keys = @page_props.keys - RELOAD_PRESERVED_PAGE_PROPS
+      @view_props = {}
+      @page_props = @page_props.select { |key, _| RELOAD_PRESERVED_PAGE_PROPS.include?(key) }
+      @page_props["route"] ||= (@client_details["route"] || "/")
+      @page_props["window"] ||= @window
+      @overlay_container.children.clear
+      refresh_overlay_container!
+      refresh_services_container!
+      refresh_dialogs_container!
+      self
+    end
+
+    # Called after the reloaded app block ran, before the reload view patch.
+    # Page-level props merge on the client (the Page control is not recreated),
+    # so chrome the reloaded block dropped must be sent as an explicit nil or
+    # it lingers. View props need no such treatment: the View is rebuilt
+    # wholesale from @view_props. Also flushes the overlay container, which
+    # stays mounted and is skipped by a plain view patch.
+    def finalize_reload!
+      keys = @reload_prior_page_prop_keys
+      if keys
+        (keys - @page_props.keys).each { |key| @page_props[key] = nil }
+        @reload_prior_page_prop_keys = nil
+      end
+      push_overlay_update!
+      self
+    end
+
+    # Called after the reloaded app block ran. The route survives a reload
+    # (page props are kept), but the client only sends its route_change event
+    # at connect time — apps that render routes exclusively inside
+    # on_route_change would be stuck on stale content after a reload. Replay
+    # the event for them, unless the block already routed itself (page.go).
+    def replay_route_after_reload!
+      return self if @route_change_seen_since_reset
+      return self unless @page_event_handlers["route_change"].respond_to?(:call)
+
+      dispatch_page_event(name: "route_change", data: @page_props["route"])
+      self
+    end
+
     def overlay
       @overlay_container.children
     end
@@ -590,11 +674,13 @@ module Ruflet
     def dialog=(value)
       @dialog = value
       refresh_dialogs_container!
+      push_dialogs_update! if @dialogs_container_mounted
     end
 
     def snack_bar=(value)
       @snack_bar = value
       refresh_dialogs_container!
+      push_dialogs_update! if @dialogs_container_mounted
     end
 
     def snack_bar
@@ -608,6 +694,7 @@ module Ruflet
     def bottom_sheet=(value)
       @bottom_sheet = value
       refresh_dialogs_container!
+      push_dialogs_update! if @dialogs_container_mounted
     end
 
     def bottom_sheet
@@ -640,9 +727,22 @@ module Ruflet
     end
 
     def show_bottom_sheet(bottom_sheet_control)
+      @bottom_sheet = bottom_sheet_control
       show_dialog(bottom_sheet_control)
     end
 
+    def show_bottomsheet(bottom_sheet_control)
+      show_bottom_sheet(bottom_sheet_control)
+    end
+
+    def close_bottom_sheet(bottom_sheet_control = nil)
+      close_dialog(bottom_sheet_control || @bottom_sheet)
+    end
+
+    def close_bottomsheet(bottom_sheet_control = nil)
+      close_bottom_sheet(bottom_sheet_control)
+    end
+
     def show_banner(banner_control)
       show_dialog(banner_control)
     end
@@ -651,13 +751,27 @@ module Ruflet
       close_dialog(banner_control)
     end
 
+    # Flet-compatible generic overlay API. Prefer close_bottom_sheet for sheets
+    # so the page's current bottom-sheet slot is handled explicitly.
+    def open(dialog_control)
+      show_dialog(dialog_control)
+    end
+
+    def close(dialog_control = nil)
+      close_dialog(dialog_control)
+    end
+
     def close_dialog(dialog_control = nil)
       target = dialog_control || latest_open_dialog
       return nil unless target
 
+      clear_dialog_slots(target)
+      # The client pops a dialog's route only when the mounted control sees
+      # its `open` prop flip to false (alert_dialog.dart tracks open/_open).
+      # Replacing the dialogs container recreates the control client-side and
+      # the transition is lost, so patch the open prop on the control itself.
       target.props["open"] = false
-      refresh_dialogs_container!
-      push_dialogs_update!
+      update(target, open: false)
       target
     end
 
@@ -1192,6 +1306,8 @@ module Ruflet
         patch["content"] = patch.delete("text")
       end
 
+      patch.each { |key, value| control.props[key] = value }
+
       # Keep runtime control tree aligned with incremental patches.
       if patch.key?("controls")
         control.children.clear
@@ -1577,6 +1693,7 @@ module Ruflet
     def dispatch_page_event(name:, data:)
       event_name = name.to_s
       event_name = event_name[3..-1] if event_name.start_with?("on_")
+      @route_change_seen_since_reset = true if event_name == "route_change"
       handler = @page_event_handlers[event_name]
       return unless handler.respond_to?(:call)
 
@@ -1712,10 +1829,17 @@ module Ruflet
       return false unless @dialogs.include?(control)
 
       @dialogs.delete(control)
+      clear_dialog_slots(control)
       refresh_dialogs_container!
       true
     end
 
+    def clear_dialog_slots(control)
+      @dialog = nil if @dialog.equal?(control)
+      @snack_bar = nil if @snack_bar.equal?(control)
+      @bottom_sheet = nil if @bottom_sheet.equal?(control)
+    end
+
     def assign_split_prop(key, value)
       if key == "vertical_alignment" || key == "horizontal_alignment"
         @page_props[key] = value

data/lib/ruflet_ui/ruflet/ui/control_factory.rb

@@ -13,12 +13,14 @@ module Ruflet
         Services::RufletServices::CLASS_MAP
           .merge(Controls::RufletControls::CLASS_MAP)
           .freeze
+      EXTENSION_CLASS_MAP = {}
       CONSTRUCTOR_KEYWORDS_CACHE = {}
 
-      PYTHON_COMMON_ATTRIBUTES = %i[flip ref transform].freeze
-      PYTHON_ATTRIBUTE_OVERRIDES = {
+      COMMON_ATTRIBUTES = %i[flip ref transform].freeze
+      ATTRIBUTE_OVERRIDES = {
         "expansionpanellist" => %i[auto_scroll on_scroll scroll scroll_interval],
-        "fletapp" => %i[assets_dir on_python_output],
+        "ruflet_app" => %i[assets_dir on_python_output],
+        "rufletapp" => %i[assets_dir on_python_output],
         "image" => %i[
           align animate_align animate_margin animate_offset animate_opacity animate_position
           animate_rotation animate_scale animate_size aspect_ratio badge bottom col disabled
@@ -40,7 +42,7 @@ module Ruflet
         if ENV["RUFLET_DEBUG"] == "1" && normalized_type == "floatingactionbutton"
           Kernel.warn("[factory] type=#{normalized_type} id=#{id.inspect} props=#{props.inspect}")
         end
-        klass = CLASS_MAP[normalized_type]
+        klass = EXTENSION_CLASS_MAP[normalized_type] || CLASS_MAP[normalized_type]
         if klass
           normalized_props, supplemental_props = normalize_constructor_props(klass, normalized_type, props)
           if ENV["RUFLET_DEBUG"] == "1" && normalized_type == "floatingactionbutton"
@@ -64,7 +66,7 @@ module Ruflet
 
       def normalize_constructor_props(klass, type, props)
         keywords = constructor_keywords(klass)
-        return [props, {}] if keywords.empty? && PYTHON_ATTRIBUTE_OVERRIDES[type].nil?
+        return [props, {}] if keywords.empty? && ATTRIBUTE_OVERRIDES[type].nil?
 
         allowed = keywords.map(&:to_s)
         mapped = props.each_with_object({}) { |(k, v), out| out[k.to_sym] = v }
@@ -74,7 +76,7 @@ module Ruflet
         if mapped.key?(:value) && !allowed.include?("value") && allowed.include?("text") && !mapped.key?(:text)
           mapped[:text] = mapped.delete(:value)
         end
-        supplemental_names = PYTHON_COMMON_ATTRIBUTES + PYTHON_ATTRIBUTE_OVERRIDES.fetch(type, [])
+        supplemental_names = COMMON_ATTRIBUTES + ATTRIBUTE_OVERRIDES.fetch(type, [])
         supplemental = mapped.slice(*supplemental_names)
         [mapped.reject { |key, _| supplemental_names.include?(key) }, supplemental]
       end
@@ -96,6 +98,21 @@ module Ruflet
         []
       end
 
+      def register_extension(type, klass)
+        key = type.to_s.downcase
+        raise ArgumentError, "Extension control type cannot be empty" if key.empty?
+        raise ArgumentError, "Extension control must inherit Ruflet::Control" unless klass <= Ruflet::Control
+
+        existing = EXTENSION_CLASS_MAP[key]
+        if existing && existing != klass
+          raise ArgumentError, "Extension control `#{key}` is already registered by #{existing}"
+        end
+
+        EXTENSION_CLASS_MAP[key] = klass
+        CONSTRUCTOR_KEYWORDS_CACHE.delete(klass)
+        klass
+      end
+
       def normalize_common_value(value)
         case value
         when Hash

data/lib/ruflet_ui/ruflet/ui/controls/materials/webview_control.rb

@@ -4,11 +4,32 @@ module Ruflet
   module UI
     module Controls
       module RufletComponents
+        # WebView control — parity with Flet's WebView
+        # (https://flet.dev/docs/controls/webview/).
+        #
+        # Properties: url, bgcolor, prevent_links, plus the usual layout props.
+        # Events: on_page_started, on_page_ended, on_web_resource_error,
+        #   on_progress, on_url_change, on_scroll, on_console_message,
+        #   on_javascript_alert_dialog.
+        # Methods (invoked over the wire on a mounted control): reload, go_back,
+        #   go_forward, can_go_back, can_go_forward, run_javascript, load_html,
+        #   load_request, load_file, scroll_to, scroll_by, clear_cache,
+        #   clear_local_storage, enable_zoom, disable_zoom, set_javascript_mode,
+        #   get_current_url, get_title, get_user_agent.
+        #
+        # Platform note: the native webview runs on iOS, Android, macOS, Windows,
+        # and Linux. Linux distributions must provide WebKitGTK 4.1. On web it
+        # uses an iframe, so browser cross-origin restrictions still apply.
         class WebViewControl < Ruflet::Control
           TYPE = "WebView".freeze
           WIRE = "WebView".freeze
 
-          def initialize(id: nil, bgcolor: nil, data: nil, enable_javascript: nil, expand: nil, height: nil, key: nil, method: nil, opacity: nil, rtl: nil, tooltip: nil, url: nil, visible: nil, width: nil, on_page_ended: nil, on_page_started: nil, on_web_resource_error: nil)
+          def initialize(id: nil, bgcolor: nil, data: nil, enable_javascript: nil, expand: nil,
+                         height: nil, key: nil, method: nil, opacity: nil, prevent_links: nil,
+                         rtl: nil, tooltip: nil, url: nil, visible: nil, width: nil,
+                         on_page_ended: nil, on_page_started: nil, on_web_resource_error: nil,
+                         on_progress: nil, on_url_change: nil, on_scroll: nil,
+                         on_console_message: nil, on_javascript_alert_dialog: nil)
             props = {}
             props[:bgcolor] = bgcolor unless bgcolor.nil?
             props[:data] = data unless data.nil?
@@ -18,6 +39,7 @@ module Ruflet
             props[:key] = key unless key.nil?
             props[:method] = method unless method.nil?
             props[:opacity] = opacity unless opacity.nil?
+            props[:prevent_links] = prevent_links unless prevent_links.nil?
             props[:rtl] = rtl unless rtl.nil?
             props[:tooltip] = tooltip unless tooltip.nil?
             props[:url] = url unless url.nil?
@@ -26,8 +48,98 @@ module Ruflet
             props[:on_page_ended] = on_page_ended unless on_page_ended.nil?
             props[:on_page_started] = on_page_started unless on_page_started.nil?
             props[:on_web_resource_error] = on_web_resource_error unless on_web_resource_error.nil?
+            props[:on_progress] = on_progress unless on_progress.nil?
+            props[:on_url_change] = on_url_change unless on_url_change.nil?
+            props[:on_scroll] = on_scroll unless on_scroll.nil?
+            props[:on_console_message] = on_console_message unless on_console_message.nil?
+            props[:on_javascript_alert_dialog] = on_javascript_alert_dialog unless on_javascript_alert_dialog.nil?
             super(type: TYPE, id: id, **props)
           end
+
+          # --- Navigation --------------------------------------------------
+
+          def reload = invoke_webview_method("reload")
+          def go_back = invoke_webview_method("go_back")
+          def go_forward = invoke_webview_method("go_forward")
+
+          def can_go_back(timeout: 10, &on_result)
+            invoke_webview_method("can_go_back", timeout: timeout, on_result: on_result)
+          end
+
+          def can_go_forward(timeout: 10, &on_result)
+            invoke_webview_method("can_go_forward", timeout: timeout, on_result: on_result)
+          end
+
+          # --- Loading content ---------------------------------------------
+
+          def load_request(url, method: "get")
+            invoke_webview_method("load_request", { "url" => url.to_s, "method" => method.to_s })
+          end
+
+          def load_html(value, base_url: nil)
+            args = { "value" => value.to_s }
+            args["base_url"] = base_url.to_s unless base_url.nil?
+            invoke_webview_method("load_html", args)
+          end
+
+          def load_file(path)
+            invoke_webview_method("load_file", { "path" => path.to_s })
+          end
+
+          # --- JavaScript injection ---------------------------------------
+
+          # Run arbitrary JS inside the page — e.g. hide a node so a native
+          # control can take its place:
+          #   webview.run_javascript("document.getElementById('banner').remove()")
+          def run_javascript(value)
+            invoke_webview_method("run_javascript", { "value" => value.to_s })
+          end
+
+          def set_javascript_mode(mode)
+            invoke_webview_method("set_javascript_mode", { "mode" => mode.to_s })
+          end
+
+          # --- Scrolling ---------------------------------------------------
+
+          def scroll_to(x, y)
+            invoke_webview_method("scroll_to", { "x" => x.to_i, "y" => y.to_i })
+          end
+
+          def scroll_by(x, y)
+            invoke_webview_method("scroll_by", { "x" => x.to_i, "y" => y.to_i })
+          end
+
+          # --- Storage / zoom ----------------------------------------------
+
+          def clear_cache = invoke_webview_method("clear_cache")
+          def clear_local_storage = invoke_webview_method("clear_local_storage")
+          def enable_zoom = invoke_webview_method("enable_zoom")
+          def disable_zoom = invoke_webview_method("disable_zoom")
+
+          # --- Introspection (result delivered to the block) ---------------
+
+          def get_current_url(timeout: 10, &on_result)
+            invoke_webview_method("get_current_url", timeout: timeout, on_result: on_result)
+          end
+
+          def get_title(timeout: 10, &on_result)
+            invoke_webview_method("get_title", timeout: timeout, on_result: on_result)
+          end
+
+          def get_user_agent(timeout: 10, &on_result)
+            invoke_webview_method("get_user_agent", timeout: timeout, on_result: on_result)
+          end
+
+          private
+
+          def invoke_webview_method(name, args = nil, timeout: 10, on_result: nil)
+            page = runtime_page
+            unless page && wire_id
+              raise "WebView ##{id} is not mounted yet — add it to the page before calling #{name}."
+            end
+
+            page.invoke(self, name, args: args, timeout: timeout, on_result: on_result)
+          end
         end
       end
     end

data/lib/ruflet_ui/ruflet/ui/controls/ruflet_controls.rb

@@ -115,7 +115,6 @@ require_relative "shared/dismissible_control"
 require_relative "shared/draggable_control"
 require_relative "shared/dragtarget_control"
 require_relative "shared/fill_control"
-require_relative "shared/fletapp_control"
 require_relative "shared/gesturedetector_control"
 require_relative "shared/gridview_control"
 require_relative "shared/hero_control"
@@ -140,6 +139,7 @@ require_relative "shared/reorderabledraghandle_control"
 require_relative "shared/responsiverow_control"
 require_relative "shared/row_control"
 require_relative "shared/rotatedbox_control"
+require_relative "shared/ruflet_app_control"
 require_relative "shared/safearea_control"
 require_relative "shared/screenshot_control"
 require_relative "shared/semantics_control"
@@ -301,8 +301,6 @@ module Ruflet
           "fillediconbutton" => RufletComponents::FilledIconButtonControl,
           "filledtonalbutton" => RufletComponents::FilledTonalButtonControl,
           "filledtonaliconbutton" => RufletComponents::FilledTonalIconButtonControl,
-          "flet_app" => RufletComponents::FletAppControl,
-          "fletapp" => RufletComponents::FletAppControl,
           "floating_action_button" => RufletComponents::FloatingActionButtonControl,
           "floatingactionbutton" => RufletComponents::FloatingActionButtonControl,
           "gesture_detector" => RufletComponents::GestureDetectorControl,
@@ -399,6 +397,8 @@ module Ruflet
           "row" => RufletComponents::RowControl,
           "rotated_box" => RufletComponents::RotatedBoxControl,
           "rotatedbox" => RufletComponents::RotatedBoxControl,
+          "ruflet_app" => RufletComponents::RufletAppControl,
+          "rufletapp" => RufletComponents::RufletAppControl,
           "safe_area" => RufletComponents::SafeAreaControl,
           "safearea" => RufletComponents::SafeAreaControl,
           "screenshot" => RufletComponents::ScreenshotControl,

data/lib/ruflet_ui/ruflet/ui/controls/shared/{fletapp_control.rb → ruflet_app_control.rb}

@@ -4,8 +4,10 @@ module Ruflet
   module UI
     module Controls
       module RufletComponents
-        class FletAppControl < Ruflet::Control
-          TYPE = "fletapp".freeze
+        class RufletAppControl < Ruflet::Control
+          TYPE = "ruflet_app".freeze
+          # The client widget is still registered under its upstream name, so the
+          # wire type stays FletApp while the Ruby API is ruflet_app.
           WIRE = "FletApp".freeze
 
           KEYWORDS = [:align, :animate_align, :animate_margin, :animate_offset, :animate_opacity, :animate_position, :animate_rotation, :animate_scale, :animate_size, :app_error_message, :app_startup_screen_message, :args, :aspect_ratio, :badge, :bottom, :col, :data, :disabled, :expand, :expand_loose, :force_pyodide, :height, :key, :left, :margin, :offset, :opacity, :reconnect_interval_ms, :reconnect_timeout_ms, :right, :rotate, :rtl, :scale, :show_app_startup_screen, :size_change_interval, :tooltip, :top, :url, :visible, :width, :on_animation_end, :on_error, :on_size_change].freeze

data/lib/ruflet_ui/ruflet/ui/controls/shared/ruflet_controls.rb

@@ -14,7 +14,6 @@ require_relative "dismissible_control"
 require_relative "draggable_control"
 require_relative "dragtarget_control"
 require_relative "fill_control"
-require_relative "fletapp_control"
 require_relative "gesturedetector_control"
 require_relative "gridview_control"
 require_relative "hero_control"
@@ -39,6 +38,7 @@ require_relative "reorderabledraghandle_control"
 require_relative "responsiverow_control"
 require_relative "row_control"
 require_relative "rotatedbox_control"
+require_relative "ruflet_app_control"
 require_relative "safearea_control"
 require_relative "screenshot_control"
 require_relative "semantics_control"
@@ -81,8 +81,6 @@ module Ruflet
             "draggable" => RufletComponents::DraggableControl,
             "dragtarget" => RufletComponents::DragTargetControl,
             "fill" => RufletComponents::FillControl,
-            "flet_app" => RufletComponents::FletAppControl,
-            "fletapp" => RufletComponents::FletAppControl,
             "gesture_detector" => RufletComponents::GestureDetectorControl,
             "gesturedetector" => RufletComponents::GestureDetectorControl,
             "grid_view" => RufletComponents::GridViewControl,
@@ -117,6 +115,8 @@ module Ruflet
             "row" => RufletComponents::RowControl,
             "rotated_box" => RufletComponents::RotatedBoxControl,
             "rotatedbox" => RufletComponents::RotatedBoxControl,
+            "ruflet_app" => RufletComponents::RufletAppControl,
+            "rufletapp" => RufletComponents::RufletAppControl,
             "safe_area" => RufletComponents::SafeAreaControl,
             "safearea" => RufletComponents::SafeAreaControl,
             "screenshot" => RufletComponents::ScreenshotControl,

data/lib/ruflet_ui/ruflet/ui/material_control_methods.rb

@@ -21,7 +21,7 @@ module Ruflet
 
       def view(children = nil, **props, &block)
         mapped = props.dup
-        mapped[:children] = children unless children.nil?
+        mapped[:controls] = children unless children.nil?
         build_widget(:view, **mapped, &block)
       end
       def column(children = nil, **props, &block)
@@ -702,6 +702,11 @@ module Ruflet
         build_widget(:codeeditor, **mapped)
       end
       def codeeditor(value = nil, **props) = code_editor(value, **props)
+      def lottie(src = nil, **props)
+        mapped = props.dup
+        mapped[:src] = src unless src.nil?
+        build_widget(:lottie, **mapped)
+      end
       def rive(src = nil, **props)
         mapped = props.dup
         mapped[:src] = src unless src.nil?

data/lib/ruflet_ui/ruflet/ui/material_control_registry.rb

@@ -116,6 +116,7 @@ module Ruflet
         "simple_attribution" => "SimpleAttribution",
         "codeeditor" => "CodeEditor",
         "code_editor" => "CodeEditor",
+        "lottie" => "Lottie",
         "flashlight" => "Flashlight",
         "barchart" => "BarChart",
         "barchartgroup" => "group",

data/lib/ruflet_ui/ruflet/ui/shared_control_forwarders.rb

@@ -6,7 +6,11 @@ module Ruflet
       def control(type, **props, &block) = control_delegate.control(type, **props, &block)
       def widget(type, **props, &block) = control_delegate.widget(type, **props, &block)
       def service(type, **props, &block) = control_delegate.service(type, **props, &block)
-      def view(children = nil, **props, &block) = control_delegate.view(children, **props, &block)
+      def view(children = nil, **props, &block)
+        mapped = props.dup
+        mapped[:controls] = children unless children.nil?
+        control_delegate.control(:view, **mapped, &block)
+      end
       def column(children = nil, **props, &block) = control_delegate.column(children, **props, &block)
       def center(**props, &block) = control_delegate.center(**props, &block)
       def row(children = nil, **props, &block) = control_delegate.row(children, **props, &block)
@@ -278,6 +282,7 @@ module Ruflet
       def video(**props) = control_delegate.video(**props)
       def code_editor(value = nil, **props) = control_delegate.code_editor(value, **props)
       def codeeditor(value = nil, **props) = control_delegate.codeeditor(value, **props)
+      def lottie(src = nil, **props) = control_delegate.lottie(src, **props)
       def rive(src = nil, **props) = control_delegate.rive(src, **props)
       def cupertino_button(content = nil, **props) = control_delegate.cupertino_button(content, **props)
       def cupertinobutton(content = nil, **props) = control_delegate.cupertinobutton(content, **props)

data/lib/ruflet_ui.rb

@@ -3,8 +3,6 @@
 require "ruflet_protocol"
 require_relative "ruflet_ui/ruflet/colors"
 require_relative "ruflet_ui/ruflet/icon_data"
-require_relative "ruflet_ui/ruflet/icons/material/material_icons"
-require_relative "ruflet_ui/ruflet/icons/cupertino/cupertino_icons"
 require_relative "ruflet_ui/ruflet/types/text_style"
 require_relative "ruflet_ui/ruflet/types/geometry"
 require_relative "ruflet_ui/ruflet/control"
@@ -15,8 +13,25 @@ require_relative "ruflet_ui/ruflet/event"
 require_relative "ruflet_ui/ruflet/page"
 require_relative "ruflet_ui/ruflet/app"
 require_relative "ruflet_ui/ruflet/dsl"
+require_relative "ruflet_ui/ruflet/extensions"
+require_relative "ruflet_ui/ruflet/extensions/qrcode_scanner"
 
 module Ruflet
+  # Icon tables are large (the material set alone parses a ~234KB map and
+  # defines thousands of constants) but the common `icon("home")` path passes
+  # the name straight through — nothing in the runtime touches these modules
+  # unless an app references a constant like `Ruflet::Icons::HOME`. Autoload
+  # them so boot (and every full restart) skips that cost until first use.
+  #
+  # CRuby only: under the embedded mruby VM the framework is concatenated into
+  # one blob with no filesystem require, so these modules are already defined
+  # there and the guard keeps the autoload calls out of that path entirely.
+  if RUBY_ENGINE != "mruby"
+    icons_root = File.expand_path("ruflet_ui/ruflet/icons", __dir__)
+    autoload :MaterialIcons, File.join(icons_root, "material/material_icons")
+    autoload :CupertinoIcons, File.join(icons_root, "cupertino/cupertino_icons")
+  end
+
   TextStyle = UI::Types::TextStyle
   StrutStyle = UI::Types::StrutStyle
   TextOverflow = UI::Types::TextOverflow

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruflet_core
 version: !ruby/object:Gem::Version
-  version: 0.0.18
+  version: 0.0.20
 platform: ruby
 authors:
 - AdamMusa
@@ -29,6 +29,8 @@ files:
 - lib/ruflet_ui/ruflet/dsl.rb
 - lib/ruflet_ui/ruflet/event.rb
 - lib/ruflet_ui/ruflet/events/gesture_events.rb
+- lib/ruflet_ui/ruflet/extensions.rb
+- lib/ruflet_ui/ruflet/extensions/qrcode_scanner.rb
 - lib/ruflet_ui/ruflet/icon_data.rb
 - lib/ruflet_ui/ruflet/icons/cupertino/cupertino_icons.json
 - lib/ruflet_ui/ruflet/icons/cupertino/cupertino_icons.rb
@@ -161,7 +163,6 @@ files:
 - lib/ruflet_ui/ruflet/ui/controls/shared/draggable_control.rb
 - lib/ruflet_ui/ruflet/ui/controls/shared/dragtarget_control.rb
 - lib/ruflet_ui/ruflet/ui/controls/shared/fill_control.rb
-- lib/ruflet_ui/ruflet/ui/controls/shared/fletapp_control.rb
 - lib/ruflet_ui/ruflet/ui/controls/shared/gesturedetector_control.rb
 - lib/ruflet_ui/ruflet/ui/controls/shared/gridview_control.rb
 - lib/ruflet_ui/ruflet/ui/controls/shared/hero_control.rb
@@ -186,6 +187,7 @@ files:
 - lib/ruflet_ui/ruflet/ui/controls/shared/responsiverow_control.rb
 - lib/ruflet_ui/ruflet/ui/controls/shared/rotatedbox_control.rb
 - lib/ruflet_ui/ruflet/ui/controls/shared/row_control.rb
+- lib/ruflet_ui/ruflet/ui/controls/shared/ruflet_app_control.rb
 - lib/ruflet_ui/ruflet/ui/controls/shared/ruflet_controls.rb
 - lib/ruflet_ui/ruflet/ui/controls/shared/safearea_control.rb
 - lib/ruflet_ui/ruflet/ui/controls/shared/screenshot_control.rb