unmagic-browser 0.1.0

data/lib/unmagic/browser.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+# The class is declared before its parts are required, because they reopen it.
+# Its documentation lives at the bottom of this file, with the implementation.
+module Unmagic
+  class Browser; end
+end
+
+require_relative "browser/version"
+require_relative "browser/error"
+require_relative "browser/failures"
+require_relative "browser/configuration"
+require_relative "browser/emulation"
+require_relative "browser/markdown"
+require_relative "browser/locator"
+require_relative "browser/element"
+require_relative "browser/session"
+require_relative "browser/driver"
+require_relative "browser/driver/connection"
+require_relative "browser/driver/base"
+require_relative "browser/driver/local"
+require_relative "browser/driver/remote"
+require_relative "browser/driver/cloudflare"
+
+module Unmagic
+  # A real browser you can drive from Ruby — for one-off page grabs *and*
+  # multi-step automation.
+  #
+  # The same API runs against local Chrome, any remote Puppeteer endpoint, and
+  # Cloudflare Browser Rendering. Which one is a construction-time decision;
+  # nothing else in your code changes.
+  #
+  # There are two ways in. Call {#markdown}, {#html}, {#screenshot} or {#pdf}
+  # straight on the browser for "just get me this page", and each takes the
+  # cheapest path its driver offers. Call {#open} for anything with more than
+  # one step, and you get a {Session} — a live page with Capybara-flavoured
+  # verbs that auto-wait.
+  #
+  # @example One-off
+  #   Unmagic::Browser.new.markdown("https://example.com")
+  #
+  # @example Multi-step
+  #   Unmagic::Browser.open("https://news.ycombinator.com/login") do |session|
+  #     session.fill_in "acct", with: "pg"
+  #     session.click_button "login"
+  #     session.wait_for text: "logout"
+  #   end
+  class Browser
+    # Environment names that mean "someone is sitting at this machine", where a
+    # local Chrome you can watch beats a remote one you can't.
+    DEVELOPMENT = ["development", "dev", "test"].freeze
+
+    class << self
+      # Set the gem's global defaults.
+      #
+      # @yieldparam config [Configuration]
+      # @return [Configuration]
+      #
+      # @example
+      #   Unmagic::Browser.configure do |config|
+      #     config.default_driver = :cloudflare
+      #   end
+      def configure
+        yield(configuration) if block_given?
+        configuration
+      end
+
+      # @return [Configuration] the current global defaults
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Throw the configuration away. Mostly for tests.
+      #
+      # @return [void]
+      def reset!
+        @configuration = Configuration.new
+      end
+
+      # Shorthand for `Unmagic::Browser.new.open(url)`.
+      #
+      # @param url [String] the page to open
+      # @param options [Hash] see {Browser#open}
+      # @yieldparam session [Session]
+      # @return [Session, Object] the session, or the block's value
+      def open(url, **options, &block)
+        new.open(url, **options, &block)
+      end
+
+      # Whether this process looks like somebody's machine rather than a
+      # server. Checked only when no driver was asked for.
+      #
+      # @return [Boolean]
+      def development?
+        return Rails.env.development? || Rails.env.test? if defined?(Rails) && Rails.respond_to?(:env) && Rails.env
+
+        environment = ENV["RAILS_ENV"] || ENV["RACK_ENV"] || ENV["APP_ENV"]
+        environment.nil? || DEVELOPMENT.include?(environment)
+      end
+    end
+
+    # The driver doing the real work. The mirror of the `driver:` option: you
+    # pick one when you construct the browser, and this hands the instance back
+    # for anything the curated API doesn't wrap.
+    #
+    # @return [Driver::Base]
+    attr_reader :driver
+
+    # @param driver [Symbol, Driver::Base, nil] `:local`, `:remote`, `:cloudflare`, or an
+    #   instance. Defaults to `:local` in development and to
+    #   {Configuration#default_driver} everywhere else.
+    # @param timeout [Numeric, nil] seconds a locator waits, defaulting to {Configuration#timeout}
+    # @param navigation_timeout [Numeric, nil] seconds a navigation is given,
+    #   defaulting to {Configuration#navigation_timeout}
+    def initialize(driver: nil, timeout: nil, navigation_timeout: nil)
+      @driver = Driver.build(driver || default_driver)
+      @timeout = timeout
+      @navigation_timeout = navigation_timeout
+    end
+
+    # @param url [String] the page to render
+    # @return [String] the page as Markdown
+    def markdown(url)
+      @driver.markdown(url)
+    end
+
+    # @param url [String] the page to render
+    # @return [String] the page's HTML, after JavaScript has run
+    def html(url)
+      @driver.html(url)
+    end
+
+    # @param url [String] the page to render
+    # @param full_page [Boolean] capture the whole scrollable page
+    # @param selector [String, nil] capture just the first element matching this CSS
+    # @return [String] PNG bytes
+    def screenshot(url, full_page: false, selector: nil)
+      @driver.screenshot(url, full_page: full_page, selector: selector)
+    end
+
+    # @param url [String] the page to render
+    # @return [String] PDF bytes
+    def pdf(url)
+      @driver.pdf(url)
+    end
+
+    # Open a page you can drive step by step.
+    #
+    # Works like `File.open`: with a block you get a session already on that
+    # page, cleaned up when the block ends. Without one, the session is yours to
+    # keep — and yours to {Session#close}, because it holds a real browser (and
+    # on Cloudflare, one of a limited number of concurrent slots) until you do.
+    #
+    # @param url [String, nil] the page to start on, or nil for a blank one
+    # @param emulate [Emulation, Hash, nil] how the page should render
+    # @param timeout [Numeric, nil] seconds a locator waits in this session
+    # @param navigation_timeout [Numeric, nil] seconds a navigation is given in this session
+    # @yieldparam session [Session]
+    # @return [Session, Object] the session, or the block's value
+    def open(url = nil, emulate: nil, timeout: nil, navigation_timeout: nil)
+      session = start_session(emulate: emulate, timeout: timeout, navigation_timeout: navigation_timeout)
+      begin
+        session.visit(url) if url
+      rescue StandardError
+        session.close
+        raise
+      end
+
+      return session unless block_given?
+
+      begin
+        yield(session)
+      ensure
+        session.close
+      end
+    end
+
+    # Release the shared browser one-off grabs run on. Sessions are unaffected —
+    # each holds its own.
+    #
+    # @return [void]
+    def close
+      @driver.close
+    end
+
+    # @return [String] the browser and the driver behind it
+    def inspect
+      "#<#{self.class.name} driver=#{@driver.name}>"
+    end
+
+    private
+
+    def start_session(emulate:, timeout:, navigation_timeout:)
+      connection = @driver.open_connection
+      begin
+        Session.new(
+          browser: self,
+          connection: connection,
+          page: connection.new_page,
+          emulation: emulate,
+          timeout: timeout || @timeout,
+          navigation_timeout: navigation_timeout || @navigation_timeout,
+        )
+      rescue StandardError
+        connection.close
+        raise
+      end
+    end
+
+    def default_driver
+      self.class.development? ? :local : self.class.configuration.default_driver
+    end
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: unmagic-browser
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Keith Pitt
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: puppeteer-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.53'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.53'
+- !ruby/object:Gem::Dependency
+  name: reverse_markdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Drive a real browser from Ruby for one-off page grabs and multi-step
+  automation. Runs against local Chrome, any remote Puppeteer endpoint, or Cloudflare
+  Browser Rendering — behind one Capybara-flavoured API with smart locators, auto-waiting,
+  and sessions that outlive a single call.
+email:
+- keith@unreasonable-magic.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/unmagic/browser.rb
+- lib/unmagic/browser/configuration.rb
+- lib/unmagic/browser/console.rb
+- lib/unmagic/browser/console/banner.rb
+- lib/unmagic/browser/console/graphics.rb
+- lib/unmagic/browser/console/helpers.rb
+- lib/unmagic/browser/console/prompt.rb
+- lib/unmagic/browser/console/renderer.rb
+- lib/unmagic/browser/console/terminal.rb
+- lib/unmagic/browser/console/values.rb
+- lib/unmagic/browser/driver.rb
+- lib/unmagic/browser/driver/base.rb
+- lib/unmagic/browser/driver/cloudflare.rb
+- lib/unmagic/browser/driver/cloudflare/transport.rb
+- lib/unmagic/browser/driver/connection.rb
+- lib/unmagic/browser/driver/local.rb
+- lib/unmagic/browser/driver/remote.rb
+- lib/unmagic/browser/element.rb
+- lib/unmagic/browser/emulation.rb
+- lib/unmagic/browser/error.rb
+- lib/unmagic/browser/failures.rb
+- lib/unmagic/browser/locator.rb
+- lib/unmagic/browser/markdown.rb
+- lib/unmagic/browser/session.rb
+- lib/unmagic/browser/version.rb
+homepage: https://github.com/unreasonable-magic/unmagic-browser
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/unreasonable-magic/unmagic-browser
+  source_code_uri: https://github.com/unreasonable-magic/unmagic-browser
+  changelog_uri: https://github.com/unreasonable-magic/unmagic-browser/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.7
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A real browser you can drive from Ruby, locally or on Cloudflare
+test_files: []