scarpe 0.2.2 → 0.4.0

data/lib/scarpe/wv/web_wrangler.rb

@@ -8,9 +8,9 @@ require "cgi"
 # After creation, it starts in setup mode, and you can
 # use setup-mode callbacks.
 
-class Scarpe
+module Scarpe::Webview
   # The Scarpe WebWrangler, for Webview, manages a lot of Webviews quirks. It provides
-  # a simpler underlying abstraction for DOMWrangler and the Webview widgets.
+  # a simpler underlying abstraction for DOMWrangler and the Webview drawables.
   # Webview can be picky - if you send it too many messages, it can crash. If the
   # messages you send it are too large, it can crash. If you don't return control
   # to its event loop, it can crash. It doesn't save references to all event handlers,
@@ -51,26 +51,6 @@ class Scarpe
     # A reference to the control_interface that manages internal Scarpe Webview events.
     attr_reader :control_interface
 
-    # This error indicates a problem when running ConfirmedEval
-    class JSEvalError < Scarpe::Error
-      def initialize(data)
-        @data = data
-        super(data[:msg] || (self.class.name + "!"))
-      end
-    end
-
-    # An error running the supplied JS code string in confirmed_eval
-    class JSRuntimeError < JSEvalError
-    end
-
-    # The code timed out for some reason
-    class JSTimeoutError < JSEvalError
-    end
-
-    # We got weird or nonsensical results that seem like an error on WebWrangler's part
-    class InternalError < JSEvalError
-    end
-
     # This is the JS function name for eval results (internal-only)
     EVAL_RESULT = "scarpeAsyncEvalResult"
 
@@ -85,7 +65,7 @@ class Scarpe
     # @param resizable [Boolean] whether the window should be resizable by the user
     # @param heartbeat [Float] time between heartbeats in seconds
     def initialize(title:, width:, height:, resizable: false, heartbeat: 0.1)
-      log_init("WV::WebWrangler")
+      log_init("Webview::WebWrangler")
 
       @log.debug("Creating WebWrangler...")
 
@@ -149,7 +129,7 @@ class Scarpe
     # @param name [String] the Javascript name for the new function
     # @yield The Ruby block to be invoked when JS calls the function
     def bind(name, &block)
-      raise "App is running, javascript binding no longer works because it uses WebView init!" if @is_running
+      raise Scarpe::JSBindingError, "App is running, javascript binding no longer works because it uses WebView init!" if @is_running
 
       @webview.bind(name, &block)
     end
@@ -160,7 +140,7 @@ class Scarpe
     # @param name [String] the Javascript name for the init function
     # @yield The Ruby block to be invoked when Webview runs
     def init_code(name, &block)
-      raise "App is running, javascript init no longer works!" if @is_running
+      raise Scarpe::JSInitError, "App is running, javascript init no longer works!" if @is_running
 
       # Save a reference to the init string so that it doesn't get GC'd
       code_str = "#{name}();"
@@ -176,6 +156,8 @@ class Scarpe
     # so it should be invoked when the WebWrangler is in setup mode,
     # before the Webview is running.
     #
+    # TODO: add a way to stop this loop and unsubscribe.
+    #
     # @param name [String] the name of the Javascript init function, if needed
     # @param interval [Float] the duration between invoking this block
     # @yield the Ruby block to invoke periodically
@@ -188,7 +170,7 @@ class Scarpe
           # new window. But will there ever be a new page/window? Can we just
           # use eval instead of init to set up a periodic handler and call it
           # good?
-          raise "App is running, can't set up new periodic handlers with init!"
+          raise Scarpe::PeriodicHandlerSetupError, "App is running, can't set up new periodic handlers with init!"
         end
 
         js_interval = (interval.to_f * 1_000.0).to_i
@@ -214,7 +196,7 @@ class Scarpe
     # @param code [String] the Javascript code to attempt to execute
     # @return [void]
     def js_eventually(code)
-      raise "WebWrangler isn't running, eval doesn't work!" unless @is_running
+      raise Scarpe::WebWranglerNotRunningError, "WebWrangler isn't running, eval doesn't work!" unless @is_running
 
       @log.warn "Deprecated: please do NOT use js_eventually, it's basically never what you want!" unless ENV["CI"]
 
@@ -242,10 +224,10 @@ class Scarpe
     #
     # @param code [String] the Javascript code to execute
     # @param timeout [Float] how long to allow before raising a timeout exception
-    # @param wait_for [Array<Promise>] promises that must complete successfully before this JS is scheduled
+    # @param wait_for [Array<Scarpe::Promise>] promises that must complete successfully before this JS is scheduled
     def eval_js_async(code, timeout: EVAL_DEFAULT_TIMEOUT, wait_for: [])
       unless @is_running
-        raise "WebWrangler isn't running, so evaluating JS won't work!"
+        raise Scarpe::WebWranglerNotRunningError, "WebWrangler isn't running, so evaluating JS won't work!"
       end
 
       this_eval_serial = @eval_counter
@@ -279,6 +261,7 @@ class Scarpe
           @log.debug("Scheduled JS: (#{this_eval_serial})\n#{wrapped_code}")
         else
           # We're mid-shutdown. No more scheduling things.
+          @log.warn "Mid-shutdown JS eval. Not scheduling JS!"
         end
       end
 
@@ -320,7 +303,7 @@ class Scarpe
     def receive_eval_result(r_type, id, val)
       entry = @pending_evals.delete(id)
       unless entry
-        raise "Received an eval result for a nonexistent ID #{id.inspect}!"
+        raise Scarpe::NonexistentEvalResultError, "Received an eval result for a nonexistent ID #{id.inspect}!"
       end
 
       @log.debug("Got JS value: #{r_type} / #{id} / #{val.inspect}")
@@ -331,13 +314,13 @@ class Scarpe
       when "success"
         promise.fulfilled!(val)
       when "error"
-        promise.rejected! JSRuntimeError.new(
+        promise.rejected! Scarpe::JSRuntimeError.new(
           msg: "JS runtime error: #{val.inspect}!",
           code: entry[:code],
           ret_value: val,
         )
       else
-        promise.rejected! InternalError.new(
+        promise.rejected! Scarpe::JSInternalError.new(
           msg: "JS eval internal error! r_type: #{r_type.inspect}",
           code: entry[:code],
           ret_value: val,
@@ -373,13 +356,15 @@ class Scarpe
       timed_out_ids.each do |id|
         @log.error "Timing out JS eval! #{@pending_evals[id][:code]}"
         entry = @pending_evals.delete(id)
-        err = JSTimeoutError.new(msg: "JS timeout error!", code: entry[:code], ret_value: nil)
+        err = Scarpe::JSTimeoutError.new(msg: "JS timeout error!", code: entry[:code], ret_value: nil)
         entry[:promise].rejected!(err)
       end
     end
 
     public
 
+    attr_writer :empty_page
+
     # After setup, we call run to go to "running" mode.
     # No more setup callbacks should be called, only running callbacks.
     def run
@@ -387,14 +372,18 @@ class Scarpe
 
       # From webview:
       # 0 - Width and height are default size
-      # 1 - Width and height are minimum bonds
-      # 2 - Width and height are maximum bonds
+      # 1 - Width and height are minimum bounds
+      # 2 - Width and height are maximum bounds
       # 3 - Window size can not be changed by a user
       hint = @resizable ? 0 : 3
 
       @webview.set_title(@title)
       @webview.set_size(@width, @height, hint)
-      @webview.navigate("data:text/html, #{empty}")
+      unless @empty_page
+        raise Scarpe::EmptyPageNotSetError, "No empty page markup was set!"
+      end
+
+      @webview.navigate("data:text/html, #{CGI.escape @empty_page}")
 
       monkey_patch_console(@webview)
 
@@ -440,29 +429,7 @@ class Scarpe
     end
 
     def empty
-      html = <<~HTML
-        <html>
-          <head id='head-wvroot'>
-            <style id='style-wvroot'>
-              /** Style resets **/
-              body {
-                font-family: arial, Helvetica, sans-serif;
-                margin: 0;
-                height: 100%;
-                overflow: hidden;
-              }
-              p {
-                margin: 0;
-              }
-            </style>
-          </head>
-          <body id='body-wvroot'>
-            <div id='wrapper-wvroot'></div>
-          </body>
-        </html>
-      HTML
-
-      CGI.escape(html)
+      Scarpe::Components::Calzini.empty_page_element
     end
 
     public
@@ -535,325 +502,350 @@ class Scarpe
   end
 end
 
-class Scarpe
-  class WebWrangler
-    # Leaving DOM changes as "meh, async, we'll see when it happens" is terrible for testing.
-    # Instead, we need to track whether particular changes have committed yet or not.
-    # So we add a single gateway for all DOM changes, and we make sure its work is done
-    # before we consider a redraw complete.
-    #
-    # DOMWrangler batches up changes into fewer RPC calls. It's fine to have a redraw
-    # "in flight" and have changes waiting to catch the next bus. But we don't want more
-    # than one in flight, since it seems like having too many pending RPC requests can
-    # crash Webview. So we allow one redraw scheduled and one redraw promise waiting,
-    # at maximum.
-    #
-    # A WebWrangler will create and wrap a DOMWrangler, serving as the interface
-    # for all DOM operations.
-    #
-    # A batch of DOMWrangler changes may be removed if a full update is scheduled. That
-    # update is considered to replace the previous incremental changes. Any changes that
-    # need to execute even if a full update happens should be scheduled through
-    # WebWrangler#eval_js_async, not DOMWrangler.
-    class DOMWrangler
-      include Shoes::Log
-
-      # Changes that have not yet been executed
-      attr_reader :waiting_changes
+class Scarpe::Webview::WebWrangler
+  # Leaving DOM changes as "meh, async, we'll see when it happens" is terrible for testing.
+  # Instead, we need to track whether particular changes have committed yet or not.
+  # So we add a single gateway for all DOM changes, and we make sure its work is done
+  # before we consider a redraw complete.
+  #
+  # DOMWrangler batches up changes into fewer RPC calls. It's fine to have a redraw
+  # "in flight" and have changes waiting to catch the next bus. But we don't want more
+  # than one in flight, since it seems like having too many pending RPC requests can
+  # crash Webview. So we allow one redraw scheduled and one redraw promise waiting,
+  # at maximum.
+  #
+  # A WebWrangler will create and wrap a DOMWrangler, serving as the interface
+  # for all DOM operations.
+  #
+  # A batch of DOMWrangler changes may be removed if a full update is scheduled. That
+  # update is considered to replace the previous incremental changes. Any changes that
+  # need to execute even if a full update happens should be scheduled through
+  # WebWrangler#eval_js_async, not DOMWrangler.
+  class DOMWrangler
+    include Shoes::Log
 
-      # A Scarpe::Promise for JS that has been scheduled to execute but is not yet verified complete
-      attr_reader :pending_redraw_promise
+    # Changes that have not yet been executed
+    attr_reader :waiting_changes
+
+    # A Scarpe::Promise for JS that has been scheduled to execute but is not yet verified complete
+    attr_reader :pending_redraw_promise
+
+    # A Scarpe::Promise for waiting changes - it will be fulfilled when all waiting changes
+    # have been verified complete, or when a full redraw that removed them has been
+    # verified complete. If many small changes are scheduled, the same promise will be
+    # returned for many of them.
+    attr_reader :waiting_redraw_promise
+
+    # Create a DOMWrangler that is paired with a WebWrangler. The WebWrangler is
+    # treated as an underlying abstraction for reliable JS evaluation.
+    def initialize(web_wrangler)
+      log_init("Webview::WebWrangler::DOMWrangler")
+
+      @wrangler = web_wrangler
+
+      @waiting_changes = []
+      @pending_redraw_promise = nil
+      @waiting_redraw_promise = nil
+
+      @fully_up_to_date_promise = nil
+
+      # Initially we're waiting for a full replacement to happen.
+      # It's possible to request updates/changes before we have
+      # a DOM in place and before Webview is running. If we do
+      # that, we should discard those updates.
+      @first_draw_requested = false
+
+      @redraw_handlers = []
+
+      # The "fully up to date" logic is complicated and not
+      # as well tested as I'd like. This makes it far less
+      # likely that the event simply won't fire.
+      # With more comprehensive testing, this should be
+      # removable.
+      web_wrangler.periodic_code("scarpeDOMWranglerHeartbeat") do
+        if @fully_up_to_date_promise && fully_updated?
+          @log.info("Fulfilling up-to-date promise on heartbeat")
+          @fully_up_to_date_promise.fulfilled!
+          @fully_up_to_date_promise = nil
+        end
+      end
+    end
 
-      # A Scarpe::Promise for waiting changes - it will be fulfilled when all waiting changes
-      # have been verified complete, or when a full redraw that removed them has been
-      # verified complete. If many small changes are scheduled, the same promise will be
-      # returned for many of them.
-      attr_reader :waiting_redraw_promise
+    def request_change(js_code)
+      # No updates until there's something to update
+      return unless @first_draw_requested
 
-      # Create a DOMWrangler that is paired with a WebWrangler. The WebWrangler is
-      # treated as an underlying abstraction for reliable JS evaluation.
-      def initialize(web_wrangler)
-        log_init("WV::WebWrangler::DOMWrangler")
+      @waiting_changes << js_code
 
-        @wrangler = web_wrangler
+      promise_redraw
+    end
 
-        @waiting_changes = []
-        @pending_redraw_promise = nil
-        @waiting_redraw_promise = nil
-
-        @fully_up_to_date_promise = nil
-
-        # Initially we're waiting for a full replacement to happen.
-        # It's possible to request updates/changes before we have
-        # a DOM in place and before Webview is running. If we do
-        # that, we should discard those updates.
-        @first_draw_requested = false
-
-        @redraw_handlers = []
-
-        # The "fully up to date" logic is complicated and not
-        # as well tested as I'd like. This makes it far less
-        # likely that the event simply won't fire.
-        # With more comprehensive testing, this should be
-        # removable.
-        web_wrangler.periodic_code("scarpeDOMWranglerHeartbeat") do
-          if @fully_up_to_date_promise && fully_updated?
-            @log.info("Fulfilling up-to-date promise on heartbeat")
-            @fully_up_to_date_promise.fulfilled!
-            @fully_up_to_date_promise = nil
-          end
-        end
-      end
+    def self.replacement_code(html_text)
+      "document.getElementById('wrapper-wvroot').innerHTML = `#{html_text}`; true"
+    end
 
-      def request_change(js_code)
-        # No updates until there's something to update
-        return unless @first_draw_requested
+    def request_replace(html_text)
+      # Replace other pending changes, they're not needed any more
+      @waiting_changes = [DOMWrangler.replacement_code(html_text)]
+      @first_draw_requested = true
 
-        @waiting_changes << js_code
+      @log.debug("Requesting DOM replacement...")
+      promise_redraw
+    end
 
-        promise_redraw
-      end
+    def on_every_redraw(&block)
+      @redraw_handlers << block
+    end
 
-      def self.replacement_code(html_text)
-        "document.getElementById('wrapper-wvroot').innerHTML = `#{html_text}`; true"
+    # promise_redraw returns a Scarpe::Promise which will be fulfilled after all current
+    # pending or waiting changes have completed. This may require creating a new
+    # promise.
+    #
+    # What are the states of redraw?
+    # "empty" - no waiting promise, no pending-redraw promise, no pending changes
+    # "pending only" - no waiting promise, but we have a pending redraw with some changes; it hasn't committed yet
+    # "pending and waiting" - we have a waiting promise for our unscheduled changes; we can add more unscheduled
+    #     changes since we haven't scheduled them yet.
+    #
+    # This is often called after adding a new waiting change or replacing them, so the state may have just changed.
+    # It can also be called when no changes have been made and no updates need to happen.
+    def promise_redraw
+      if fully_updated?
+        # No changes to make, nothing in-process or waiting, so just return a pre-fulfilled promise
+        @log.debug("Requesting redraw but there are no pending changes or promises, return pre-fulfilled")
+        return ::Scarpe::Promise.fulfilled
       end
 
-      def request_replace(html_text)
-        # Replace other pending changes, they're not needed any more
-        @waiting_changes = [DOMWrangler.replacement_code(html_text)]
-        @first_draw_requested = true
-
-        @log.debug("Requesting DOM replacement...")
-        promise_redraw
+      # Already have a redraw requested *and* one on deck? Then all current changes will have committed
+      # when we (eventually) fulfill the waiting_redraw_promise.
+      if @waiting_redraw_promise
+        @log.debug("Promising eventual redraw of #{@waiting_changes.size} waiting unscheduled changes.")
+        return @waiting_redraw_promise
       end
 
-      def on_every_redraw(&block)
-        @redraw_handlers << block
+      if @waiting_changes.empty?
+        # There's no waiting_redraw_promise. There are no waiting changes. But we're not fully updated.
+        # So there must be a redraw in flight, and we don't need to schedule a new waiting_redraw_promise.
+        @log.debug("Returning in-flight redraw promise")
+        return @pending_redraw_promise
       end
 
-      # promise_redraw returns a Scarpe::Promise which will be fulfilled after all current
-      # pending or waiting changes have completed. This may require creating a new
-      # promise.
-      #
-      # What are the states of redraw?
-      # "empty" - no waiting promise, no pending-redraw promise, no pending changes
-      # "pending only" - no waiting promise, but we have a pending redraw with some changes; it hasn't committed yet
-      # "pending and waiting" - we have a waiting promise for our unscheduled changes; we can add more unscheduled
-      #     changes since we haven't scheduled them yet.
-      #
-      # This is often called after adding a new waiting change or replacing them, so the state may have just changed.
-      # It can also be called when no changes have been made and no updates need to happen.
-      def promise_redraw
-        if fully_updated?
-          # No changes to make, nothing in-process or waiting, so just return a pre-fulfilled promise
-          @log.debug("Requesting redraw but there are no pending changes or promises, return pre-fulfilled")
-          return Promise.fulfilled
-        end
+      @log.debug("Requesting redraw with #{@waiting_changes.size} waiting changes and no waiting promise - need to schedule something!")
 
-        # Already have a redraw requested *and* one on deck? Then all current changes will have committed
-        # when we (eventually) fulfill the waiting_redraw_promise.
-        if @waiting_redraw_promise
-          @log.debug("Promising eventual redraw of #{@waiting_changes.size} waiting unscheduled changes.")
-          return @waiting_redraw_promise
-        end
-
-        if @waiting_changes.empty?
-          # There's no waiting_redraw_promise. There are no waiting changes. But we're not fully updated.
-          # So there must be a redraw in flight, and we don't need to schedule a new waiting_redraw_promise.
-          @log.debug("Returning in-flight redraw promise")
-          return @pending_redraw_promise
-        end
+      # We have at least one waiting change, possibly newly-added. We have no waiting_redraw_promise.
+      # Do we already have a redraw in-flight?
+      if @pending_redraw_promise
+        # Yes we do. Schedule a new waiting promise. When it turns into the pending_redraw_promise it will
+        # grab all waiting changes. In the mean time, it sits here and waits.
+        #
+        # We *could* do a fancy promise thing and have it update @waiting_changes for itself, etc, when it
+        # schedules itself. But we should always be calling promise_redraw or having a redraw fulfilled (see below)
+        # when these things change. I'd rather keep the logic in this method. It's easier to reason through
+        # all the cases.
+        @waiting_redraw_promise = ::Scarpe::Promise.new
 
-        @log.debug("Requesting redraw with #{@waiting_changes.size} waiting changes and no waiting promise - need to schedule something!")
-
-        # We have at least one waiting change, possibly newly-added. We have no waiting_redraw_promise.
-        # Do we already have a redraw in-flight?
-        if @pending_redraw_promise
-          # Yes we do. Schedule a new waiting promise. When it turns into the pending_redraw_promise it will
-          # grab all waiting changes. In the mean time, it sits here and waits.
-          #
-          # We *could* do a fancy promise thing and have it update @waiting_changes for itself, etc, when it
-          # schedules itself. But we should always be calling promise_redraw or having a redraw fulfilled (see below)
-          # when these things change. I'd rather keep the logic in this method. It's easier to reason through
-          # all the cases.
-          @waiting_redraw_promise = Promise.new
-
-          @log.debug("Creating a new waiting promise since a pending promise is already in place")
-          return @waiting_redraw_promise
-        end
+        @log.debug("Creating a new waiting promise since a pending promise is already in place")
+        return @waiting_redraw_promise
+      end
 
-        # We have no redraw in-flight and no pre-existing waiting line. The new change(s) are presumably right
-        # after things were fully up-to-date. We can schedule them for immediate redraw.
+      # We have no redraw in-flight and no pre-existing waiting line. The new change(s) are presumably right
+      # after things were fully up-to-date. We can schedule them for immediate redraw.
 
-        @log.debug("Requesting redraw with #{@waiting_changes.size} waiting changes - scheduling a new redraw for them!")
-        promise = schedule_waiting_changes # This clears the waiting changes
-        @pending_redraw_promise = promise
+      @log.debug("Requesting redraw with #{@waiting_changes.size} waiting changes - scheduling a new redraw for them!")
+      promise = schedule_waiting_changes # This clears the waiting changes
+      @pending_redraw_promise = promise
 
-        promise.on_fulfilled do
-          @redraw_handlers.each(&:call)
-          @pending_redraw_promise = nil
+      promise.on_fulfilled do
+        @redraw_handlers.each(&:call)
+        @pending_redraw_promise = nil
 
-          if @waiting_redraw_promise
-            # While this redraw was in flight, more waiting changes got added and we made a promise
-            # about when they'd complete. Now they get scheduled, and we'll fulfill the waiting
-            # promise when that redraw finishes. Clear the old waiting promise. We'll add a new one
-            # when/if more changes are scheduled during this redraw.
-            old_waiting_promise = @waiting_redraw_promise
-            @waiting_redraw_promise = nil
+        if @waiting_redraw_promise
+          # While this redraw was in flight, more waiting changes got added and we made a promise
+          # about when they'd complete. Now they get scheduled, and we'll fulfill the waiting
+          # promise when that redraw finishes. Clear the old waiting promise. We'll add a new one
+          # when/if more changes are scheduled during this redraw.
+          old_waiting_promise = @waiting_redraw_promise
+          @waiting_redraw_promise = nil
 
-            @log.debug "Fulfilled redraw with #{@waiting_changes.size} waiting changes - scheduling a new redraw for them!"
+          @log.debug "Fulfilled redraw with #{@waiting_changes.size} waiting changes - scheduling a new redraw for them!"
 
-            new_promise = promise_redraw
-            new_promise.on_fulfilled { old_waiting_promise.fulfilled! }
-          else
-            # The in-flight redraw completed, and there's still no waiting promise. Good! That means
-            # we should be fully up-to-date.
-            @log.debug "Fulfilled redraw with no waiting changes - marking us as up to date!"
-            if @waiting_changes.empty?
-              # We're fully up to date! Fulfill the promise. Now we don't need it again until somebody asks
-              # us for another.
-              if @fully_up_to_date_promise
-                @fully_up_to_date_promise.fulfilled!
-                @fully_up_to_date_promise = nil
-              end
-            else
-              @log.error "WHOAH, WHAT? My logic must be wrong, because there's " +
-                "no waiting promise, but waiting changes!"
+          new_promise = promise_redraw
+          new_promise.on_fulfilled { old_waiting_promise.fulfilled! }
+        else
+          # The in-flight redraw completed, and there's still no waiting promise. Good! That means
+          # we should be fully up-to-date.
+          @log.debug "Fulfilled redraw with no waiting changes - marking us as up to date!"
+          if @waiting_changes.empty?
+            # We're fully up to date! Fulfill the promise. Now we don't need it again until somebody asks
+            # us for another.
+            if @fully_up_to_date_promise
+              @fully_up_to_date_promise.fulfilled!
+              @fully_up_to_date_promise = nil
             end
+          else
+            @log.error "WHOAH, WHAT? My logic must be wrong, because there's " +
+              "no waiting promise, but waiting changes!"
           end
+        end
 
-          @log.debug("Redraw is now fully up-to-date") if fully_updated?
-        end.on_rejected do
-          @log.error "Could not complete JS redraw! #{promise.reason.full_message}"
-          @log.debug("REDRAW FULLY UP TO DATE BUT JS FAILED") if fully_updated?
-
-          raise "JS Redraw failed! Bailing!"
+        @log.debug("Redraw is now fully up-to-date") if fully_updated?
+      end.on_rejected do
+        @log.error "Could not complete JS redraw! #{promise.reason.full_message}"
+        @log.debug("REDRAW FULLY UP TO DATE BUT JS FAILED") if fully_updated?
 
-          # Later we should figure out how to handle this. Clear the promises and queues and request another redraw?
-        end
-      end
+        raise Scarpe::JSRedrawError, "JS Redraw failed! Bailing!"
 
-      def fully_updated?
-        @pending_redraw_promise.nil? && @waiting_redraw_promise.nil? && @waiting_changes.empty?
+        # Later we should figure out how to handle this. Clear the promises and queues and request another redraw?
       end
+    end
 
-      # Return a promise which will be fulfilled when the DOM is fully up-to-date
-      def promise_fully_updated
-        if fully_updated?
-          # No changes to make, nothing in-process or waiting, so just return a pre-fulfilled promise
-          return Promise.fulfilled
-        end
+    def fully_updated?
+      @pending_redraw_promise.nil? && @waiting_redraw_promise.nil? && @waiting_changes.empty?
+    end
 
-        # Do we already have a promise for this? Return it. Everybody can share one.
-        if @fully_up_to_date_promise
-          return @fully_up_to_date_promise
-        end
+    # Return a promise which will be fulfilled when the DOM is fully up-to-date
+    def promise_fully_updated
+      if fully_updated?
+        # No changes to make, nothing in-process or waiting, so just return a pre-fulfilled promise
+        return ::Scarpe::Promise.fulfilled
+      end
 
-        # We're not fully updated, so we need a promise. Create it, return it.
-        @fully_up_to_date_promise = Promise.new
+      # Do we already have a promise for this? Return it. Everybody can share one.
+      if @fully_up_to_date_promise
+        return @fully_up_to_date_promise
       end
 
-      private
+      # We're not fully updated, so we need a promise. Create it, return it.
+      @fully_up_to_date_promise = ::Scarpe::Promise.new
+    end
+
+    private
 
-      # Put together the waiting changes into a new in-flight redraw request.
-      # Return it as a promise.
-      def schedule_waiting_changes
-        return if @waiting_changes.empty?
+    # Put together the waiting changes into a new in-flight redraw request.
+    # Return it as a promise.
+    def schedule_waiting_changes
+      return if @waiting_changes.empty?
 
-        js_code = @waiting_changes.join(";")
-        @waiting_changes = [] # They're not waiting any more!
-        @wrangler.eval_js_async(js_code)
-      end
+      js_code = @waiting_changes.join(";")
+      @waiting_changes = [] # They're not waiting any more!
+      @wrangler.eval_js_async(js_code)
     end
   end
-end
 
-class Scarpe
-  class WebWrangler
-    # An ElementWrangler provides a way for a Widget to manipulate is DOM element(s)
-    # via their HTML IDs. The most straightforward Widgets can have a single HTML ID
-    # and use a single ElementWrangler to make any needed changes.
-    #
-    # For now we don't need an ElementWrangler to add DOM elements, just to manipulate them
-    # after initial render. New DOM objects for Widgets are normally added via full
-    # redraws rather than incremental updates.
+  # An ElementWrangler provides a way for a Drawable to manipulate is DOM element(s)
+  # via their HTML IDs. The most straightforward Drawables can have a single HTML ID
+  # and use a single ElementWrangler to make any needed changes.
+  #
+  # For now we don't need an ElementWrangler to add DOM elements, just to manipulate them
+  # after initial render. New DOM objects for Drawables are normally added via full
+  # redraws rather than incremental updates.
+  #
+  # Any changes made via ElementWrangler may be cancelled if a full redraw occurs,
+  # since it is assumed that small DOM manipulations are no longer needed. If a
+  # change would need to be made even if a full redraw occurred, it should be
+  # scheduled via WebWrangler#eval_js_async, not via an ElementWrangler.
+  class ElementWrangler
+    attr_reader :html_id
+
+    # Create an ElementWrangler for the given HTML ID or selector.
+    # The caller should provide exactly one of the html_id or selector.
     #
-    # Any changes made via ElementWrangler may be cancelled if a full redraw occurs,
-    # since it is assumed that small DOM manipulations are no longer needed. If a
-    # change would need to be made even if a full redraw occurred, it should be
-    # scheduled via WebWrangler#eval_js_async, not via an ElementWrangler.
-    class ElementWrangler
-      attr_reader :html_id
-
-      # Create an ElementWrangler for the given HTML ID
-      #
-      # @param html_id [String] the HTML ID for the DOM element
-      def initialize(html_id)
-        @webwrangler = WebviewDisplayService.instance.wrangler
-        @html_id = html_id
+    # @param html_id [String] the HTML ID for the DOM element
+    def initialize(html_id: nil, selector: nil, multi: false)
+      @webwrangler = ::Scarpe::Webview::DisplayService.instance.wrangler
+      raise Scarpe::MissingWranglerError, "Can't get WebWrangler!" unless @webwrangler
+
+      if html_id && !selector
+        @selector = "document.getElementById('" + html_id + "')"
+      elsif selector && !html_id
+        @selector = selector
+      else
+        raise ArgumentError, "Must provide exactly one of html_id or selector!"
       end
 
-      # Return a promise that will be fulfilled when all changes scheduled via
-      # this ElementWrangler are verified complete.
-      #
-      # @return [Scarpe::Promise] a promise that will be fulfilled when scheduled changes are complete
-      def promise_update
-        @webwrangler.dom_promise_redraw
-      end
+      @multi = multi
+    end
 
-      # Update the JS DOM element's value. The given Ruby value will be converted to string and assigned in backquotes.
-      #
-      # @param new_value [String] the new value
-      # @return [Scarpe::Promise] a promise that will be fulfilled when the change is complete
-      def value=(new_value)
-        @webwrangler.dom_change("document.getElementById('" + html_id + "').value = `" + new_value + "`; true")
-      end
+    private
 
-      # Update the JS DOM element's inner_text. The given Ruby value will be converted to string and assigned in single-quotes.
-      #
-      # @param new_text [String] the new inner_text
-      # @return [Scarpe::Promise] a promise that will be fulfilled when the change is complete
-      def inner_text=(new_text)
-        @webwrangler.dom_change("document.getElementById('" + html_id + "').innerText = '" + new_text + "'; true")
+    def on_each(fragment)
+      if @multi
+        @webwrangler.dom_change("a = Array.from(#{@selector}); a.forEach((item) => item#{fragment}); true")
+      else
+        @webwrangler.dom_change(@selector + fragment + ";true")
       end
+    end
 
-      # Update the JS DOM element's inner_html. The given Ruby value will be converted to string and assigned in backquotes.
-      #
-      # @param new_html [String] the new inner_html
-      # @return [Scarpe::Promise] a promise that will be fulfilled when the change is complete
-      def inner_html=(new_html)
-        @webwrangler.dom_change("document.getElementById(\"" + html_id + "\").innerHTML = `" + new_html + "`; true")
-      end
+    public
 
-      # Update the JS DOM element's inner_html. The given Ruby value will be inspected and assigned.
-      #
-      # @param attribute [String] the attribute name
-      # @param value [String] the new attribute value
-      # @return [Scarpe::Promise] a promise that will be fulfilled when the change is complete
-      def set_attribute(attribute, value)
-        @webwrangler.dom_change("document.getElementById(\"" + html_id + "\").setAttribute(" + attribute.inspect + "," + value.inspect + "); true")
-      end
+    # Return a promise that will be fulfilled when all changes scheduled via
+    # this ElementWrangler are verified complete.
+    #
+    # @return [Scarpe::Promise] a promise that will be fulfilled when scheduled changes are complete
+    def promise_update
+      @webwrangler.dom_promise_redraw
+    end
 
-      # Update an attribute of the JS DOM element's style. The given Ruby value will be inspected and assigned.
-      #
-      # @param style_attr [String] the style attribute name
-      # @param value [String] the new style attribute value
-      # @return [Scarpe::Promise] a promise that will be fulfilled when the change is complete
-      def set_style(style_attr, value)
-        @webwrangler.dom_change("document.getElementById(\"" + html_id + "\").style.#{style_attr} = " + value.inspect + "; true")
-      end
+    # Update the JS DOM element's value. The given Ruby value will be converted to string and assigned in backquotes.
+    #
+    # @param new_value [String] the new value
+    # @return [Scarpe::Promise] a promise that will be fulfilled when the change is complete
+    def value=(new_value)
+      on_each(".value = `" + new_value + "`")
+    end
 
-      # Remove the specified DOM element
-      #
-      # @return [Scarpe::Promise] a promise that wil be fulfilled when the element is removed
-      def remove
-        @webwrangler.dom_change("document.getElementById('" + html_id + "').remove(); true")
-      end
+    # Update the JS DOM element's inner_text. The given Ruby value will be converted to string and assigned in single-quotes.
+    #
+    # @param new_text [String] the new inner_text
+    # @return [Scarpe::Promise] a promise that will be fulfilled when the change is complete
+    def inner_text=(new_text)
+      on_each(".innerText = '" + new_text + "'")
+    end
 
-      def toggle_input_button(mark)
-        checked_value = mark ? "true" : "false"
-        @webwrangler.dom_change("document.getElementById('#{html_id}').checked = #{checked_value};")
-      end
+    # Update the JS DOM element's inner_html. The given Ruby value will be converted to string and assigned in backquotes.
+    #
+    # @param new_html [String] the new inner_html
+    # @return [Scarpe::Promise] a promise that will be fulfilled when the change is complete
+    def inner_html=(new_html)
+      on_each(".innerHTML = `" + new_html + "`")
+    end
+
+    # Update the JS DOM element's outer_html. The given Ruby value will be converted to string and assigned in backquotes.
+    #
+    # @param new_html [String] the new outer_html
+    # @return [Scarpe::Promise] a promise that will be fulfilled when the change is complete
+    def outer_html=(new_html)
+      on_each(".outerHTML = `" + new_html + "`")
+    end
+
+    # Update the JS DOM element's attribute. The given Ruby value will be inspected and assigned.
+    #
+    # @param attribute [String] the attribute name
+    # @param value [String] the new attribute value
+    # @return [Scarpe::Promise] a promise that will be fulfilled when the change is complete
+    def set_attribute(attribute, value)
+      on_each(".setAttribute(" + attribute.inspect + "," + value.inspect + ")")
+    end
+
+    # Update an attribute of the JS DOM element's style. The given Ruby value will be inspected and assigned.
+    #
+    # @param style_attr [String] the style attribute name
+    # @param value [String] the new style attribute value
+    # @return [Scarpe::Promise] a promise that will be fulfilled when the change is complete
+    def set_style(style_attr, value)
+      on_each(".style.#{style_attr} = " + value.inspect + ";")
+    end
+
+    # Remove the specified DOM element
+    #
+    # @return [Scarpe::Promise] a promise that wil be fulfilled when the element is removed
+    def remove
+      on_each(".remove()")
+    end
+
+    def toggle_input_button(mark)
+      checked_value = mark ? "true" : "false"
+      on_each(".checked = #{checked_value}")
     end
   end
 end