unmagic-browser 0.1.0

data/lib/unmagic/browser/console/graphics.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "base64"
+require "fileutils"
+require "tmpdir"
+
+module Unmagic
+  class Browser
+    module Console
+      # Drawing an image in the terminal, over the [kitty graphics
+      # protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).
+      #
+      # The terminal is handed the PNG bytes themselves, base64'd, wrapped in an
+      # APC escape sequence. That's the transmission mode every implementing
+      # terminal supports — the alternative, pointing at a file on disk, is
+      # faster but only works when the terminal is on the same machine and
+      # allowed to read it.
+      module Graphics
+        # The protocol caps a single escape sequence's payload, so anything
+        # bigger goes out as a run of chunks flagged `m=1` until the last.
+        CHUNK = 4096
+
+        # Leave a little room so an image drawn at the full width doesn't wrap.
+        MARGIN = 2
+
+        # How much of the terminal's width a drawn image may take.
+        #
+        # A screenshot in a console is for glancing at — "did the page load,
+        # did the button move" — and a 1280px capture drawn edge to edge pushes
+        # the command that produced it off the screen. Half leaves the
+        # conversation readable, and the full-size file on disk is there when
+        # you want to look properly.
+        DEFAULT_SCALE = 0.5
+
+        # Where this process starts numbering its images.
+        #
+        # Every transmission needs an id the terminal hasn't seen, or it may
+        # treat the new bytes as a redraw of an image it already has and leave
+        # the old one on screen — a screenshot that never seems to change.
+        # Untagged transmissions all land on the same implicit id, which is
+        # exactly that trap, so ids are seeded from the pid to keep two consoles
+        # sharing a terminal out of each other's way.
+        ID_BASE = (Process.pid % 10_000) * 100_000
+
+        module_function
+
+        # @return [Integer] an id no image drawn from this process has used
+        def next_id
+          @drawn = (@drawn || 0) + 1
+          ID_BASE + @drawn
+        end
+
+        # @return [Float] the fraction of the terminal's width an image may take
+        def scale
+          @scale ||= DEFAULT_SCALE
+        end
+
+        # Draw images larger or smaller — `Graphics.scale = 1.0` for full width.
+        #
+        # @param fraction [Float] a fraction of the terminal's width
+        # @return [void]
+        def scale=(fraction)
+          @scale = fraction
+        end
+
+        # Write the image somewhere durable and draw it if the terminal can.
+        #
+        # It's written either way: half the point of a screenshot in a console is
+        # being able to open it in something that isn't a terminal.
+        #
+        # @param image [Image] the PNG bytes
+        # @return [String] the path it was written to
+        def show(image)
+          path = save(image)
+          draw(image) if Terminal.graphics?
+          path
+        end
+
+        # @param image [Tagged] the bytes to write
+        # @return [String] the path written to
+        def save(image)
+          directory = File.join(Dir.tmpdir, "unmagic-browser")
+          FileUtils.mkdir_p(directory)
+          path = File.join(directory, "#{image.name}-#{timestamp}.#{image.extension}")
+          File.binwrite(path, image)
+          path
+        end
+
+        # @param image [Image] the PNG bytes to draw
+        # @return [void]
+        def draw(image)
+          payload = Base64.strict_encode64(image).scan(/.{1,#{CHUNK}}/)
+
+          payload.each_with_index do |chunk, index|
+            more = index == payload.size - 1 ? 0 : 1
+            # Only the first chunk carries the full control data; the rest just
+            # say whether more is coming.
+            control = index.zero? ? "#{settings(image)},m=#{more}" : "m=#{more}"
+            $stdout.write("\e_G#{control};#{chunk}\e\\")
+          end
+
+          $stdout.write("\n")
+          $stdout.flush
+        end
+
+        # `a=T` transmits and displays in one go; `f=100` says the payload is a
+        # PNG, so the terminal does the decoding; `i=` gives this image an id of
+        # its own; and `q=2` tells the terminal to keep its acknowledgement to
+        # itself — it would otherwise write `OK` back down the tty, where the
+        # console is reading keystrokes and would take it for typing.
+        #
+        # @param image [Image]
+        # @return [String] the protocol's control data
+        def settings(image)
+          control = "a=T,f=100,i=#{next_id},q=2"
+          columns = scaled_columns(image)
+          # Given a width and no height, the terminal keeps the aspect ratio.
+          # Left off entirely, the image draws at its true pixel size.
+          control += ",c=#{columns}" if columns
+          control
+        end
+
+        # The width to draw at: {#scale} of the terminal, but never wider than
+        # the image really is. Scaling *up* would turn a screenshot of one
+        # button into a blurry banner — the cap is a ceiling, not a target.
+        #
+        # @param image [Image]
+        # @return [Integer, nil] the width to scale to, or nil to draw at native size
+        def scaled_columns(image)
+          width, = image.dimensions
+          return nil unless width
+
+          ceiling = [((Terminal.columns - MARGIN) * scale).round, 1].max
+          natural = (width.to_f / Terminal.cell.first).ceil
+          natural > ceiling ? ceiling : nil
+        end
+
+        # @return [String] a sortable, collision-resistant filename fragment
+        def timestamp
+          Time.now.strftime("%Y%m%d-%H%M%S-%L")
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/browser/console/helpers.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Browser
+    module Console
+      # The verbs, as bare words.
+      #
+      # A console is the one place where `open "https://example.com"` beats
+      # `session = browser.open("https://example.com")` — you're typing, not
+      # writing code that has to survive. Every verb here drives one current
+      # session, opened by {#open} and remembered until you {#close} it, so the
+      # reads and the actions all know what page they're on without being told.
+      #
+      # The four verbs that work on a whole page — {#markdown}, {#html},
+      # {#screenshot} and {#pdf} — take an optional URL. With one they're a
+      # one-off grab that opens nothing; without one they read the current
+      # session.
+      #
+      # {Console.start} mixes this into a console's `main`. Mix it in yourself
+      # to get the same verbs somewhere else.
+      module Helpers
+        # ---------------------------------------------------------------- setup
+
+        # @return [Unmagic::Browser] the browser the verbs run against
+        def browser
+          Console.browser
+        end
+
+        # Switch drivers, closing whatever's open.
+        #
+        # @param driver [Symbol, Unmagic::Browser::Driver::Base] `:local`, `:remote`,
+        #   `:cloudflare`, or an instance
+        # @return [Unmagic::Browser] the new browser
+        def use(driver)
+          Console.reset(driver)
+          browser
+        end
+
+        # @return [Unmagic::Browser::Session, nil] the session the verbs are driving
+        def session
+          Console.session
+        end
+
+        # ------------------------------------------------------------- navigate
+
+        # Open a page and make it the one every other verb drives. Closes
+        # whatever was open first — one session at a time is what a console
+        # wants.
+        #
+        # @param url [String, nil] the page to open, or nil for a blank one
+        # @param options [Hash] see {Unmagic::Browser#open}
+        # @return [Unmagic::Browser::Session]
+        def open(url = nil, **options)
+          Console.session&.close
+          Console.session = browser.open(url, **options)
+        end
+
+        # @param url [String] where to go, in the session that's already open
+        # @return [Unmagic::Browser::Session]
+        def visit(url)
+          current.visit(url)
+        end
+
+        # @return [Unmagic::Browser::Session]
+        def reload
+          current.reload
+        end
+
+        # @return [Unmagic::Browser::Session]
+        def back
+          current.go_back
+        end
+
+        # @return [Unmagic::Browser::Session]
+        def forward
+          current.go_forward
+        end
+
+        # @return [String] the URL currently shown
+        def url
+          current.current_url
+        end
+
+        # @return [String] the page's title
+        def title
+          current.title
+        end
+
+        # ----------------------------------------------------------------- act
+
+        # @param query [String, nil] the field's label, placeholder, name or id
+        # @param with [String] what to type
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Unmagic::Browser::Session]
+        def fill_in(query = nil, with:, **options)
+          current.fill_in(query, with: with, **options)
+        end
+
+        # @param query [String, nil] see {Unmagic::Browser::Locator.build}
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Unmagic::Browser::Session]
+        def click(query = nil, **options)
+          current.click(query, **options)
+        end
+
+        # @param query [String, nil] the button's text, value or name
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Unmagic::Browser::Session]
+        def click_button(query = nil, **options)
+          current.click_button(query, **options)
+        end
+
+        # @param query [String, nil] the link's text
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Unmagic::Browser::Session]
+        def click_link(query = nil, **options)
+          current.click_link(query, **options)
+        end
+
+        # @param option [String] the option's visible label, or its value
+        # @param from [String, nil] the select's label or name
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Unmagic::Browser::Session]
+        def select(option, from: nil, **options)
+          current.select(option, from: from, **options)
+        end
+
+        # @param query [String, nil] the checkbox's label or name
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Unmagic::Browser::Session]
+        def check(query = nil, **options)
+          current.check(query, **options)
+        end
+
+        # @param query [String, nil] the checkbox's label or name
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Unmagic::Browser::Session]
+        def uncheck(query = nil, **options)
+          current.uncheck(query, **options)
+        end
+
+        # @param query [String, nil] the radio button's label or name
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Unmagic::Browser::Session]
+        def choose(query = nil, **options)
+          current.choose(query, **options)
+        end
+
+        # @param query [String, nil] the file field's label or name
+        # @param paths [Array<String>] the files to attach
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Unmagic::Browser::Session]
+        def attach_file(query = nil, *paths, **options)
+          current.attach_file(query, *paths, **options)
+        end
+
+        # @param key [Symbol, String] e.g. `:enter`
+        # @param options [Hash] see {Unmagic::Browser::Session#press}
+        # @return [Unmagic::Browser::Session]
+        def press(key, **options)
+          current.press(key, **options)
+        end
+
+        # @param query [String, nil] see {Unmagic::Browser::Locator.build}
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Unmagic::Browser::Session]
+        def hover(query = nil, **options)
+          current.hover(query, **options)
+        end
+
+        # ---------------------------------------------------------------- read
+
+        # @return [String] the visible text of the page
+        def text
+          current.text
+        end
+
+        # @param target [String, nil] a URL to grab, or nil to read the open session
+        # @return [Code] the HTML, syntax-highlighted when shown
+        def html(target = nil)
+          Code.new(target ? browser.html(target) : current.html, language: "html", name: "page")
+        end
+
+        # @param target [String, nil] a URL to grab, or nil to read the open session
+        # @return [Code] the Markdown, syntax-highlighted when shown
+        def markdown(target = nil)
+          Code.new(target ? browser.markdown(target) : current.markdown, language: "markdown", name: "page")
+        end
+
+        # @param target [String, nil] a URL to capture, or nil to shoot the open session
+        # @param full_page [Boolean] capture the whole scrollable page
+        # @param selector [String, nil] capture just this element
+        # @return [Image] PNG bytes, drawn in the terminal when shown
+        def screenshot(target = nil, full_page: false, selector: nil)
+          bytes = if target
+            browser.screenshot(target, full_page: full_page, selector: selector)
+          else
+            current.screenshot(full_page: full_page, selector: selector)
+          end
+          Image.new(bytes)
+        end
+
+        # @param target [String, nil] a URL to print, or nil to print the open session
+        # @return [Document] PDF bytes, written to a file when shown
+        def pdf(target = nil)
+          Document.new(target ? browser.pdf(target) : current.pdf, name: "page")
+        end
+
+        # @param query [String, nil] the field's label, placeholder, name or id
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [String, nil] what's in the field
+        def value(query = nil, **options)
+          current.value(query, **options)
+        end
+
+        # @param script [String] an expression, or a function like `"() => document.title"`
+        # @param args [Array] arguments for the function form
+        # @return [Object] whatever it returns
+        def js(script, *args)
+          current.evaluate(script, *args)
+        end
+        alias_method :evaluate, :js
+
+        # ---------------------------------------------------------- wait & ask
+
+        # @param options [Hash] `text:` or `selector:`, see {Unmagic::Browser::Session#wait_for}
+        # @return [Unmagic::Browser::Session]
+        def wait_for(**options)
+          current.wait_for(**options)
+        end
+
+        # @param string [String] the text to look for
+        # @return [Boolean] whether it's on the page right now
+        def has_text?(string)
+          current.has_text?(string)
+        end
+
+        # @param query [String, nil] see {Unmagic::Browser::Locator.build}
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Boolean] whether such a button is on the page right now
+        def has_button?(query = nil, **options)
+          current.has_button?(query, **options)
+        end
+
+        # @param query [String, nil] see {Unmagic::Browser::Locator.build}
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Boolean] whether such a link is on the page right now
+        def has_link?(query = nil, **options)
+          current.has_link?(query, **options)
+        end
+
+        # @param query [String, nil] see {Unmagic::Browser::Locator.build}
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Boolean] whether such a field is on the page right now
+        def has_field?(query = nil, **options)
+          current.has_field?(query, **options)
+        end
+
+        # @param css [String] a CSS selector
+        # @return [Boolean] whether anything matches it right now
+        def has_selector?(css)
+          current.has_selector?(css)
+        end
+
+        # --------------------------------------------------------------- scope
+
+        # @param query [String, nil] see {Unmagic::Browser::Locator.build}
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Unmagic::Browser::Element]
+        def find(query = nil, **options)
+          current.find(query, **options)
+        end
+
+        # @param query [String, nil] see {Unmagic::Browser::Locator.build}
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @return [Array<Unmagic::Browser::Element>]
+        def all(query = nil, **options)
+          current.all(query, **options)
+        end
+
+        # Narrow every verb inside the block to one part of the page.
+        #
+        # @param query [String, nil] see {Unmagic::Browser::Locator.build}
+        # @param options [Hash] see {Unmagic::Browser::Locator.build}
+        # @yield with the scope in force
+        # @return [Object] whatever the block returns
+        def within(query = nil, **options, &block)
+          current.within(query, **options) { block.call }
+        end
+
+        # ----------------------------------------------------------- lifecycle
+
+        # @param config [Unmagic::Browser::Emulation, Hash, nil] a whole configuration
+        # @param knobs [Hash] individual settings, layered over what's already emulated
+        # @return [Unmagic::Browser::Emulation] what's being emulated now
+        def emulate(config = nil, **knobs)
+          current.emulate(config, **knobs)
+        end
+
+        # @return [nil]
+        def close
+          Console.session&.close
+          Console.session = nil
+        end
+
+        # What you can type, and what it does.
+        #
+        # @return [nil]
+        def help
+          puts(Banner.help)
+          nil
+        end
+
+        private
+
+        # The session the verbs drive, or a nudge towards opening one — a bare
+        # NoMethodError on nil would say nothing about what to do next.
+        def current
+          Console.session ||
+            raise(Console::NothingOpen, "Nothing's open. Start with `open \"https://example.com\"`.")
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/browser/console/prompt.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Browser
+    module Console
+      # An opt-in prompt that says what's open.
+      #
+      # `browser> ` until there's a page, and then the same green dot and title
+      # the renderer already shows for a session:
+      #
+      #     ● Sign in · jobs.town> click "Email"
+      #
+      # Off by default — the console prompts with a plain `browser> `. Ask for
+      # it with `Unmagic::Browser::Console.start(prompt: :page)`.
+      #
+      # IRB asks its context for the prompt every time it redraws the line —
+      # once per keystroke, not once per statement — so nothing here may talk to
+      # the browser. The page is read once after each statement instead, and
+      # what it said is held until the next one.
+      module Prompt
+        # What to say when nothing's open.
+        IDLE = "browser"
+
+        # Long enough to tell two pages apart, short enough to leave room to
+        # type. Titles run long — "Sign in · jobs.town" is a short one.
+        MAX_LABEL = 32
+
+        # How much of a narrow terminal the label may take before that limit
+        # comes down to meet it.
+        SHARE = 3
+
+        # Below this there's no room for a title worth reading anyway.
+        MIN_LABEL = 12
+
+        # Control characters would tear the line apart — a title with a newline
+        # in it is rare, but it only has to happen once.
+        CONTROL = "\x00-\x1F"
+
+        @live = false
+        @label = IDLE
+        @width = IDLE.length + 2
+
+        class << self
+          # Give a context a prompt that follows the browser around.
+          #
+          # IRB reads `prompt_i` and friends off its context every time it
+          # draws, so overriding them there is all it takes; the formats in
+          # `IRB.conf` stay as they are for anyone who switches prompt modes.
+          #
+          # @param context [IRB::Context]
+          # @return [void]
+          def install(context)
+            context.define_singleton_method(:prompt_i) { Prompt.render }
+            context.define_singleton_method(:prompt_s) { Prompt.continuation("%l") }
+            context.define_singleton_method(:prompt_c) { Prompt.continuation("*") }
+
+            # Any statement can have moved the page — a click that follows a
+            # link says nothing about it, and neither does `js "location = ..."`
+            # — so the page gets asked after every one of them rather than after
+            # the verbs we could think of.
+            context.define_singleton_method(:evaluate) do |*args, **options, &block|
+              super(*args, **options, &block)
+            ensure
+              Prompt.refresh
+            end
+
+            refresh
+          end
+
+          # Ask the page where it is. Everything that could raise or block
+          # happens here, so that drawing the prompt is only string work.
+          #
+          # @return [void]
+          def refresh
+            @live, @label = read
+            @width = (@live ? 2 : 0) + columns_of(@label) + 2
+          end
+
+          # @return [String] the prompt
+          def render
+            "#{marker}#{escape(@label)}> "
+          end
+
+          # Lined up under {render}, so a multi-line statement reads as one
+          # block however long the title is.
+          #
+          # @param mark [String] one visible character — IRB's `%l`, or a `*`
+          # @return [String]
+          def continuation(mark)
+            "#{" " * (@width - 2)}#{mark} "
+          end
+
+          private
+
+          # @return [Array(Boolean, String)] whether a page is open, and what to
+          #   call it
+          def read
+            session = Console.session
+            return [false, IDLE] if session.nil? || session.closed?
+
+            [true, name(session)]
+          rescue StandardError
+            # A page that's gone answers nothing. Saying so quietly beats a
+            # backtrace across the prompt every time it's drawn.
+            [false, IDLE]
+          end
+
+          # Plenty of pages have no <title> — the one you land on after a
+          # redirect to a login screen, often enough — and a blank prompt reads
+          # as something having broken. The host is always something.
+          def name(session)
+            title = tidy(session.title)
+            title = tidy(host(session.current_url)) if title.empty?
+            title.empty? ? IDLE : truncate(title)
+          end
+
+          def tidy(text)
+            text.to_s.tr(CONTROL, " ").squeeze(" ").strip
+          end
+
+          def host(url)
+            url.to_s[%r{\A[a-z][\w+.-]*://([^/]+)}i, 1]
+          end
+
+          def truncate(text)
+            limit = [[Terminal.columns / SHARE, MAX_LABEL].min, MIN_LABEL].max
+            return text if columns_of(text) <= limit
+
+            "#{text[0, limit - 1].rstrip}…"
+          end
+
+          def marker
+            @live ? "#{Terminal.paint(Terminal::GREEN, "●")} " : ""
+          end
+
+          # IRB runs the prompt through its own `%` formatting on the way out,
+          # where a title like "100% Cotton" would lose the `% C`.
+          def escape(text)
+            text.gsub("%", "%%")
+          end
+
+          # Reline measures the prompt this way too, so the padding matches what
+          # it will actually draw: an emoji in a title is two columns wide, not
+          # one character.
+          def columns_of(text)
+            defined?(Reline::Unicode) ? Reline::Unicode.calculate_width(text) : text.length
+          end
+        end
+      end
+    end
+  end
+end