ruflet_core 0.0.13 → 0.0.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f384022aa476f52d7aa7e1315e1a5da2e71071cab839f04f7a0331cdb7da21f
-  data.tar.gz: f21fb7e4b2a9f401ef521d278128ac5b436d912182f2d1ddbcbb4b7597f4dfca
+  metadata.gz: c1823b100c3e97ee941849763509b25179554464310eb640d7954bb48a30d821
+  data.tar.gz: 80d3f6891f3418bf0b2b3aa2007e08e6578ca336b72bb48b9d84c54cac2397b5
 SHA512:
-  metadata.gz: f5ffaad8c7cee45c8b756d66d567e3a9e04c13dbb672dedb3c18545f7ecd6374af89b7267fc715711d73f8dc4b1fe3b9f597f5b62ca2fd9181f7dabb336178da
-  data.tar.gz: b52faf7ed1f6aa8980ba4c03e64c34c6b13760375261ef1e6121cf52eb774c035d8940d5d9cbb74f86de5174a768d758bba724fafa2f48a77aa1bc6a6d726524
+  metadata.gz: e37e04ea218fbc50da5d3a456ecdfe376f12d00fc802c0869da7dff977bafb6d0abab8eecff92e223b42002f94652e40f7d91d2eb7a62f04fbec72bf1c7dd600
+  data.tar.gz: 42458a85edccff3f66fd88cdc71724a7a94dbf1853fbf080d0751da7b57e783694e0ba65091c908bb4b1f203d6a8e8725e9e594df762f7deb1996e29e1bc88ed

data/lib/ruflet/version.rb

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

data/lib/ruflet_protocol/ruflet/protocol.rb

@@ -39,6 +39,12 @@ module Ruflet
         "height" => page["height"],
         "platform" => page["platform"],
         "platform_brightness" => page["platform_brightness"],
+        # The Flutter client reports the host OS in "platform" even inside a
+        # browser, so "web" is the only reliable way to tell a web client from a
+        # native one. (pwa/wasm passed through for completeness.)
+        "web" => page["web"],
+        "pwa" => page["pwa"],
+        "wasm" => page["wasm"],
         "media" => page["media"] || {}
       }
     end
@@ -97,7 +103,8 @@ module Ruflet
       }
     end
 
-    def register_response(session_id:, page_patch: {}, error: nil)
+    def register_response(session_id:, page_patch: nil, error: nil)
+      page_patch ||= {}
       {
         "session_id" => session_id,
         "page_patch" => page_patch,

data/lib/ruflet_ui/ruflet/control.rb

@@ -47,6 +47,37 @@ module Ruflet
       @handlers.key?(normalized_event_name(event_name))
     end
 
+    # Read a prop by name: control["value"] or control[:value].
+    def [](key)
+      @props[key.to_s]
+    end
+
+    # Write a prop by name: control["value"] = "x".
+    def []=(key, value)
+      @props[key.to_s] = value
+    end
+
+    # Convenience dot access to props, mirroring Flet-style controls:
+    #   control.value            # => @props["value"] (reads an existing prop)
+    #   control.value = "hello"  # => sets @props["value"]
+    # Reads only resolve props that exist, so typos still raise NoMethodError
+    # instead of silently returning nil. Defined methods (type, id, props,
+    # children, on, emit, to_patch, …) are never shadowed.
+    def method_missing(name, *args, &block)
+      key = name.to_s
+      if key.end_with?("=")
+        return @props[key[0..-2]] = args.first
+      end
+      return @props[key] if args.empty? && @props.key?(key)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      key = name.to_s
+      key.end_with?("=") || @props.key?(key) || super
+    end
+
     def to_patch
       wire_type = schema_wire_type_for_class
       if wire_type.nil?

data/lib/ruflet_ui/ruflet/page.rb

@@ -160,6 +160,8 @@ module Ruflet
       @root_controls = []
       @views = []
       @dialogs = []
+      @overlay_container_mounted = false
+      @dialogs_container_mounted = false
       @services_container_mounted = false
       @visual_service_controls = {}
       @page_event_handlers = {}
@@ -248,10 +250,10 @@ module Ruflet
       controls.each { |c| register_control_tree(c, visited) }
       @root_controls = controls
 
-      @view_props["appbar"] = appbar if appbar
-      @view_props["bottom_appbar"] = bottom_appbar if bottom_appbar
-      @view_props["floating_action_button"] = floating_action_button if floating_action_button
-      @view_props["navigation_bar"] = navigation_bar if navigation_bar
+      update_view_slot("appbar", appbar)
+      update_view_slot("bottom_appbar", bottom_appbar)
+      update_view_slot("floating_action_button", floating_action_button)
+      update_view_slot("navigation_bar", navigation_bar)
       @dialog = dialog if dialog
       @snack_bar = snack_bar if snack_bar
       @bottom_sheet = bottom_sheet if bottom_sheet
@@ -482,11 +484,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 snackbar=(value)
@@ -508,6 +512,7 @@ module Ruflet
       return self if dialog_open?(dialog_control)
 
       dialog_control.props["open"] = true
+      remove_existing_singleton_dialogs(dialog_control)
       @dialogs << dialog_control unless @dialogs.include?(dialog_control)
       refresh_dialogs_container!
       send_view_patch unless @dialogs_container.wire_id
@@ -528,7 +533,7 @@ module Ruflet
       call_id = "call_#{Ruflet::Control.generate_id}"
       if on_result.respond_to?(:call)
         @invoke_waiters_mutex.synchronize { @invoke_callbacks[call_id] = on_result }
-        unless timeout.nil?
+        if embedded_async_timeout_available? && !timeout.nil?
           Thread.new(call_id, timeout.to_f) do |pending_call_id, invoke_timeout|
             sleep([invoke_timeout, 0.0].max + 0.1)
             callback = @invoke_waiters_mutex.synchronize { @invoke_callbacks.delete(pending_call_id) }
@@ -1145,9 +1150,23 @@ module Ruflet
       return nil unless dialog_control
 
       dialog_control.props["open"] = false
+      update(dialog_control, open: false)
+      dialog_control
+    end
+
+    def close_dialog(dialog_control)
+      return self unless dialog_control
+
+      dialog_control.props["open"] = false
+      @dialog = nil if @dialog.equal?(dialog_control)
+      remove_dialog_tracking(dialog_control)
       refresh_dialogs_container!
+      # Patch the dialogs container in place. Forcing a full view re-render
+      # here would remount the whole overlay — fatal while another dialog
+      # (e.g. the form behind a nested picker) is still open. The empty case
+      # is handled inside push_dialogs_update!.
       push_dialogs_update!
-      dialog_control
+      self
     end
 
     def update(control_or_id = nil, **props)
@@ -1185,6 +1204,7 @@ module Ruflet
 
       visited = Set.new
       patch.each_value { |value| register_embedded_value(value, visited) }
+      patch.each { |k, v| control.props[k] = v }
 
       patch_ops = patch.map { |k, v| [0, 0, k, serialize_patch_value(v)] }
 
@@ -1207,8 +1227,6 @@ module Ruflet
       patch = normalize_props(props || {})
       patch.each { |k, v| control.props[k] = v }
 
-      remove_dialog_tracking(control) if patch.key?("open") && patch["open"] == false
-
       self
     end
 
@@ -1216,6 +1234,10 @@ module Ruflet
       if page_control_target?(target)
         if name.to_s == "route_change"
           route_from_event = extract_route(data)
+          # Dialogs (including pickers) belong to the view that opened them.
+          # Navigating away must dismiss them, or they ghost onto the next
+          # view — the picker that "reappears after going home".
+          dismiss_tracked_dialogs! if route_from_event && route_from_event != @page_props["route"]
           @page_props["route"] = route_from_event if route_from_event
         end
         dispatch_page_event(name: name, data: data)
@@ -1225,13 +1247,19 @@ module Ruflet
       control = @wire_index[target.to_i] || @control_index[target.to_s]
       return unless control
 
-      event = Event.new(name: name, target: target, raw_data: data, page: self, control: control)
+      event = Ruflet::Event.new(name: name, target: target, raw_data: data, page: self, control: control)
       apply_event_value_to_control(control, event) if %w[change select select_change].include?(name.to_s)
-      control.emit(name, event)
-
-      if name.to_s == "dismiss" && remove_dialog_tracking(control)
+      # Material/Cupertino pickers dismiss themselves on the client once a
+      # value is confirmed, but only send a value event — never a close. Mark
+      # the dialog closed here so show_dialog can reopen it next time.
+      mark_picker_dialog_closed(control, name)
+      if dialog_close_event?(control, name) && remove_dialog_tracking(control)
+        # Patch the container in place; never force a full view re-render that
+        # would remount a still-open parent dialog (the nested-picker case).
         push_dialogs_update!
       end
+
+      control.emit(name, event)
     end
 
     def method_missing(name, *args, &block)
@@ -1273,6 +1301,10 @@ module Ruflet
 
     private
 
+    def embedded_async_timeout_available?
+      !Object.const_defined?(:RUFLET_EMBEDDED_FAKE_THREAD)
+    end
+
     def invoke_and_wait(control_or_id, method_name, args: nil, timeout: 10)
       control_id =
         if page_control_target?(control_or_id)
@@ -1370,6 +1402,14 @@ module Ruflet
       @sender.call(action, payload)
     end
 
+    def update_view_slot(name, value)
+      if value.nil?
+        @view_props.delete(name)
+      else
+        @view_props[name] = value
+      end
+    end
+
     def send_view_patch
       refresh_control_indexes!
       view_patches = build_view_patches
@@ -1379,10 +1419,12 @@ module Ruflet
         "id" => 1,
         "patch" => [
           [0],
-          [0, 0, "views", view_patches],
-          *page_patch_ops
+          *page_patch_ops,
+          [0, 0, "views", view_patches]
         ]
       })
+      @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
     end
 
@@ -1534,8 +1576,8 @@ module Ruflet
           end_value = range_value["end_value"] || range_value[:end_value]
           control.props["start_value"] = start_value unless start_value.nil?
           control.props["end_value"] = end_value unless end_value.nil?
-          return
         end
+        return
       end
 
       return if value.nil?
@@ -1582,7 +1624,7 @@ module Ruflet
     end
 
     def refresh_dialogs_container!
-      dialog_controls = (@dialogs + dialog_slots).uniq
+      dialog_controls = (dialog_slots + @dialogs).uniq
       @dialogs_container.props["controls"] = dialog_controls
       @page_props["_dialogs"] = @dialogs_container
     end
@@ -1611,6 +1653,12 @@ module Ruflet
     def push_dialogs_update!
       refresh_control_indexes!
 
+      # Once the dialogs container is mounted, every change — opening, closing,
+      # even down to no dialogs at all — is an in-place patch of its controls
+      # list. Re-sending the view (or the container as a whole object) would
+      # replace the live container instance on the Flutter side, detaching its
+      # listeners and breaking any other dialog still open. Only the very first
+      # dialog, before the container has a wire id, needs a view patch to mount.
       if @dialogs_container.wire_id
         send_message(Protocol::ACTIONS[:patch_control], {
           "id" => @dialogs_container.wire_id,
@@ -1633,6 +1681,41 @@ module Ruflet
       @dialogs.include?(dialog_control) && dialog_control.props["open"] == true
     end
 
+    def dialog_close_event?(control, name)
+      name = name.to_s
+      name == "dismiss" || (%w[change select select_change].include?(name) && @dialogs.include?(control) && control.props["open"] == false)
+    end
+
+    # Picker dialogs that auto-dismiss on the client after a selection. Their
+    # confirm sends a value event (change/select), not a close, so the server
+    # must flip `open` to false or show_dialog's open-guard blocks reopening.
+    PICKER_DIALOG_TYPES = %w[
+      datepicker daterangepicker timepicker
+      cupertinodatepicker cupertinotimerpicker
+    ].freeze
+
+    def picker_dialog?(control)
+      PICKER_DIALOG_TYPES.include?(control.type.to_s.tr("_", "").downcase)
+    end
+
+    def mark_picker_dialog_closed(control, name)
+      return unless picker_dialog?(control)
+      return unless %w[change select select_change dismiss].include?(name.to_s)
+
+      control.props["open"] = false
+    end
+
+    # Close and untrack every dialog currently shown. Called on navigation so
+    # a dialog opened in one view does not linger as an overlay on the next.
+    def dismiss_tracked_dialogs!
+      return if @dialogs.empty?
+
+      @dialogs.each { |dialog| dialog.props["open"] = false }
+      @dialogs.clear
+      refresh_dialogs_container!
+      push_dialogs_update! if @dialogs_container_mounted
+    end
+
     def remove_dialog_tracking(control)
       return false unless @dialogs.include?(control)
 
@@ -1641,6 +1724,16 @@ module Ruflet
       true
     end
 
+    def remove_existing_singleton_dialogs(control)
+      return unless singleton_dialog_control?(control)
+
+      @dialogs.delete_if { |dialog| dialog != control && singleton_dialog_control?(dialog) }
+    end
+
+    def singleton_dialog_control?(control)
+      control.type.to_s.tr("_", "").downcase == "snackbar"
+    end
+
     def assign_split_prop(key, value)
       if key == "vertical_alignment" || key == "horizontal_alignment"
         @page_props[key] = value
@@ -1668,8 +1761,8 @@ module Ruflet
         # Keep internal containers stable after initial mount.
         # Re-sending them as full objects can replace Control instances with
         # same IDs and detach service invoke listeners on the Flutter side.
-        next nil if k == "_overlay" && @overlay_container.wire_id
-        next nil if k == "_dialogs" && @dialogs_container.wire_id
+        next nil if k == "_overlay" && @overlay_container_mounted
+        next nil if k == "_dialogs" && @dialogs_container_mounted
         next nil if k == "_services" && @services_container_mounted
 
         [0, 0, k, serialize_patch_value(v)]
@@ -1774,7 +1867,7 @@ module Ruflet
       call_id = "call_#{Ruflet::Control.generate_id}"
       if on_result.respond_to?(:call)
         @invoke_waiters_mutex.synchronize { @invoke_callbacks[call_id] = on_result }
-        unless timeout.nil?
+        if embedded_async_timeout_available? && !timeout.nil?
           Thread.new(call_id, timeout.to_f) do |pending_call_id, invoke_timeout|
             sleep([invoke_timeout, 0.0].max + 0.1)
             callback = @invoke_waiters_mutex.synchronize { @invoke_callbacks.delete(pending_call_id) }

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

@@ -44,10 +44,8 @@ module Ruflet
             runtime_page&.invoke(self, "pause", timeout: timeout, on_result: on_result)
           end
 
-          def play(position: nil, timeout: 10, on_result: nil)
-            args = {}
-            args["position"] = position unless position.nil?
-            runtime_page&.invoke(self, "play", args: args.empty? ? nil : args, timeout: timeout, on_result: on_result)
+          def play(position: 0, timeout: 10, on_result: nil)
+            runtime_page&.invoke(self, "play", args: { "position" => position }, timeout: timeout, on_result: on_result)
           end
 
           def release(timeout: 10, on_result: nil)

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

@@ -4,14 +4,37 @@ module Ruflet
   module UI
     module Controls
       module RufletComponents
+        module MapValueNormalizer
+          private
+
+          def normalize_map_coordinate(value)
+            case value
+            when Array
+              if value.length == 2 && value.all? { |item| item.is_a?(Numeric) }
+                { "latitude" => value[0], "longitude" => value[1] }
+              else
+                value.map { |item| normalize_map_coordinate(item) }
+              end
+            when Hash
+              value.transform_keys(&:to_s).each_with_object({}) do |(key, item), result|
+                result[key] = normalize_map_coordinate(item)
+              end
+            else
+              value.respond_to?(:to_h) ? normalize_map_coordinate(value.to_h) : value
+            end
+          end
+        end
+
         class MapControl < Ruflet::Control
+          include MapValueNormalizer
+
           TYPE = "map".freeze
           WIRE = "Map".freeze
 
           def initialize(id: nil, layers: nil, initial_center: nil, initial_zoom: nil, min_zoom: nil, max_zoom: nil, interaction_configuration: nil, keep_alive: nil, bgcolor: nil, data: nil, expand: nil, height: nil, key: nil, visible: nil, width: nil, on_init: nil, on_long_press: nil, on_position_change: nil, on_secondary_tap: nil, on_tap: nil)
             props = {}
             props[:layers] = layers unless layers.nil?
-            props[:initial_center] = initial_center unless initial_center.nil?
+            props[:initial_center] = normalize_map_coordinate(initial_center) unless initial_center.nil?
             props[:initial_zoom] = initial_zoom unless initial_zoom.nil?
             props[:min_zoom] = min_zoom unless min_zoom.nil?
             props[:max_zoom] = max_zoom unless max_zoom.nil?
@@ -32,12 +55,52 @@ module Ruflet
             super(type: TYPE, id: id, **props)
           end
 
-          def center_on(coordinates, zoom: nil, timeout: 10, on_result: nil)
-            invoke_map("center_on", args: compact_args("coordinates" => coordinates, "zoom" => zoom), timeout: timeout, on_result: on_result)
+          def center_on(point = nil, coordinates: nil, zoom: nil, duration: nil, curve: nil, cancel_ongoing_animations: nil, timeout: 10, on_result: nil)
+            point ||= coordinates
+            invoke_map(
+              "center_on",
+              args: compact_args(
+                "point" => normalize_map_coordinate(point),
+                "zoom" => zoom,
+                "duration" => duration,
+                "curve" => curve,
+                "cancel_ongoing_animations" => cancel_ongoing_animations
+              ),
+              timeout: timeout,
+              on_result: on_result
+            )
+          end
+
+          def move_to(destination = nil, coordinates: nil, zoom: nil, rotation: nil, offset: nil, duration: nil, curve: nil, cancel_ongoing_animations: nil, timeout: 10, on_result: nil)
+            destination ||= coordinates
+            invoke_map(
+              "move_to",
+              args: compact_args(
+                "destination" => normalize_map_coordinate(destination),
+                "zoom" => zoom,
+                "rotation" => rotation,
+                "offset" => offset,
+                "duration" => duration,
+                "curve" => curve,
+                "cancel_ongoing_animations" => cancel_ongoing_animations
+              ),
+              timeout: timeout,
+              on_result: on_result
+            )
           end
 
-          def move_to(coordinates, zoom: nil, timeout: 10, on_result: nil)
-            invoke_map("move_to", args: compact_args("coordinates" => coordinates, "zoom" => zoom), timeout: timeout, on_result: on_result)
+          def zoom_to(zoom, duration: nil, curve: nil, cancel_ongoing_animations: nil, timeout: 10, on_result: nil)
+            invoke_map(
+              "zoom_to",
+              args: compact_args(
+                "zoom" => zoom,
+                "duration" => duration,
+                "curve" => curve,
+                "cancel_ongoing_animations" => cancel_ongoing_animations
+              ),
+              timeout: timeout,
+              on_result: on_result
+            )
           end
 
           def zoom_in(delta: nil, timeout: 10, on_result: nil)
@@ -118,12 +181,14 @@ module Ruflet
         end
 
         class MarkerControl < Ruflet::Control
+          include MapValueNormalizer
+
           TYPE = "marker".freeze
           WIRE = "Marker".freeze
 
           def initialize(id: nil, coordinates: nil, content: nil, height: nil, rotate: nil, width: nil, alignment: nil)
             props = {}
-            props[:coordinates] = coordinates unless coordinates.nil?
+            props[:coordinates] = normalize_map_coordinate(coordinates) unless coordinates.nil?
             props[:content] = content unless content.nil?
             props[:height] = height unless height.nil?
             props[:rotate] = rotate unless rotate.nil?
@@ -146,12 +211,14 @@ module Ruflet
         end
 
         class CircleMarkerControl < Ruflet::Control
+          include MapValueNormalizer
+
           TYPE = "circlemarker".freeze
           WIRE = "CircleMarker".freeze
 
           def initialize(id: nil, coordinates: nil, radius: nil, color: nil, border_color: nil, border_stroke_width: nil, use_radius_in_meter: nil)
             props = {}
-            props[:coordinates] = coordinates unless coordinates.nil?
+            props[:coordinates] = normalize_map_coordinate(coordinates) unless coordinates.nil?
             props[:radius] = radius unless radius.nil?
             props[:color] = color unless color.nil?
             props[:border_color] = border_color unless border_color.nil?
@@ -174,12 +241,14 @@ module Ruflet
         end
 
         class PolylineMarkerControl < Ruflet::Control
+          include MapValueNormalizer
+
           TYPE = "polylinemarker".freeze
           WIRE = "PolylineMarker".freeze
 
           def initialize(id: nil, coordinates: nil, color: nil, stroke_width: nil, border_color: nil, border_stroke_width: nil, gradient_colors: nil, stroke_cap: nil, stroke_join: nil)
             props = {}
-            props[:coordinates] = coordinates unless coordinates.nil?
+            props[:coordinates] = normalize_map_coordinate(coordinates) unless coordinates.nil?
             props[:color] = color unless color.nil?
             props[:stroke_width] = stroke_width unless stroke_width.nil?
             props[:border_color] = border_color unless border_color.nil?
@@ -204,12 +273,14 @@ module Ruflet
         end
 
         class PolygonMarkerControl < Ruflet::Control
+          include MapValueNormalizer
+
           TYPE = "polygonmarker".freeze
           WIRE = "PolygonMarker".freeze
 
           def initialize(id: nil, coordinates: nil, color: nil, border_color: nil, border_stroke_width: nil, disable_holes_border: nil, label: nil)
             props = {}
-            props[:coordinates] = coordinates unless coordinates.nil?
+            props[:coordinates] = normalize_map_coordinate(coordinates) unless coordinates.nil?
             props[:color] = color unless color.nil?
             props[:border_color] = border_color unless border_color.nil?
             props[:border_stroke_width] = border_stroke_width unless border_stroke_width.nil?

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

@@ -4,11 +4,33 @@ 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 (and therefore run_javascript and the
+        # events/methods) runs on iOS, Android and macOS. On web it falls back to
+        # an <iframe>, which cannot run the methods and which most external sites
+        # block via X-Frame-Options/CSP — embed your own same-origin pages there.
         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 +40,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 +49,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/shared/window_control.rb

@@ -50,10 +50,28 @@ module Ruflet
             super(type: TYPE, id: id, **props)
           end
 
-          %w[wait_until_ready_to_show to_front center close destroy start_dragging].each do |method_name|
-            define_method(method_name) do |timeout: 10, on_result: nil|
-              runtime_page&.invoke(self, method_name, timeout: timeout, on_result: on_result)
-            end
+          def wait_until_ready_to_show(timeout: 10, on_result: nil)
+            invoke_window_method("wait_until_ready_to_show", timeout: timeout, on_result: on_result)
+          end
+
+          def to_front(timeout: 10, on_result: nil)
+            invoke_window_method("to_front", timeout: timeout, on_result: on_result)
+          end
+
+          def center(timeout: 10, on_result: nil)
+            invoke_window_method("center", timeout: timeout, on_result: on_result)
+          end
+
+          def close(timeout: 10, on_result: nil)
+            invoke_window_method("close", timeout: timeout, on_result: on_result)
+          end
+
+          def destroy(timeout: 10, on_result: nil)
+            invoke_window_method("destroy", timeout: timeout, on_result: on_result)
+          end
+
+          def start_dragging(timeout: 10, on_result: nil)
+            invoke_window_method("start_dragging", timeout: timeout, on_result: on_result)
           end
 
           def start_resizing(edge, timeout: 10, on_result: nil)
@@ -65,6 +83,12 @@ module Ruflet
               on_result: on_result
             )
           end
+
+          private
+
+          def invoke_window_method(method_name, timeout:, on_result:)
+            runtime_page&.invoke(self, method_name, timeout: timeout, on_result: on_result)
+          end
         end
       end
     end

data/lib/ruflet_ui/ruflet/ui/services/ruflet/audio_recorder_control.rb

@@ -9,6 +9,7 @@ module Ruflet
           WIRE = "AudioRecorder".freeze
 
           def initialize(id: nil, configuration: nil, data: nil, key: nil, on_state_change: nil, on_stream: nil, on_upload: nil)
+            configuration ||= {}
             props = {}
             props[:configuration] = configuration unless configuration.nil?
             props[:data] = data unless data.nil?
@@ -44,6 +45,7 @@ module Ruflet
           end
 
           def start_recording(output_path: nil, configuration: nil, upload: nil, timeout: 10, on_result: nil)
+            configuration ||= {}
             invoke_audio_recorder(
               "start_recording",
               args: compact_args(

data/lib/ruflet_ui/ruflet/ui/services/ruflet/permissionhandler_control.rb

@@ -44,6 +44,8 @@ module Ruflet
           end
 
           def normalize_service_value(value)
+            return value.to_s if value.is_a?(Symbol)
+
             value.respond_to?(:to_h) ? value.to_h.transform_keys(&:to_s) : value
           end
         end

data/lib/ruflet_ui/ruflet/ui/services/ruflet/securestorage_control.rb

@@ -23,6 +23,8 @@ module Ruflet
           end
 
           def set(key, value, **options)
+            raise ArgumentError, "value must not be nil" if value.nil?
+
             invoke_secure_storage("set", args: option_args(options).merge("key" => key, "value" => value), **invoke_options(options))
           end
 

data/lib/ruflet_ui.rb

@@ -140,7 +140,7 @@ module Ruflet
       private
 
       def control_delegate
-        Ruflet::DSL
+        Ruflet::WidgetBuilder.new
       end
     end
   end
@@ -154,8 +154,12 @@ module Kernel
   def app(**opts, &block) = Ruflet::DSL.app(**opts, &block)
   def page(**props, &block) = Ruflet::DSL.page(**props, &block)
 
+  # Bare widget helpers (view, text, container, …) build real controls anywhere
+  # — top-level scripts and Ruflet.run blocks — with no builder to instantiate.
+  # The framework owns this plumbing so dev code stays free of it; a fresh
+  # builder per call keeps the helpers stateless.
   def control_delegate
-    Ruflet::DSL
+    Ruflet::WidgetBuilder.new
   end
 
   if Ruflet::UI::SharedControlForwarders.respond_to?(:instance_methods)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruflet_core
 version: !ruby/object:Gem::Version
-  version: 0.0.13
+  version: 0.0.15
 platform: ruby
 authors:
 - AdamMusa