bidi2pdf 0.1.13 → 0.1.14

data/lib/bidi2pdf/bidi/browser_tab.rb

@@ -444,6 +444,58 @@ module Bidi2pdf
 
       # rubocop:enable Metrics/AbcSize, Metrics/PerceivedComplexity
 
+      # Captures a screenshot of the browser tab, mirroring #print's own
+      # file/block/base64-return trichotomy.
+      #
+      # @param [String, nil] outputfile The output file for the PNG. Defaults to nil.
+      # @param [String] origin "document" (default) or "viewport" - see browsingContext.captureScreenshot.
+      # @param [String, nil] format Image format override, e.g. "image/png". Defaults to the browser's own default.
+      # @param [Hash, nil] clip A clip rectangle/element, passed through verbatim. Defaults to nil (full capture).
+      # @yield [png_base64] A block to handle the PNG content.
+      # @return [String, nil] The base64-encoded PNG content, or nil if outputfile or block is provided.
+      # rubocop:disable Metrics/AbcSize
+      def screenshot(outputfile = nil, origin: "document", format: nil, clip: nil, &block)
+        Bidi2pdf.notification_service.instrument("screenshot.bidi2pdf") do |instrumentation_payload|
+          cmd = Commands::CaptureScreenshot.new(context: browsing_context_id, origin: origin, format: format, clip: clip)
+
+          instrumentation_payload[:cmd] = cmd
+
+          client.send_cmd_and_wait(cmd) do |response|
+            if response["result"]
+              png_base64 = response.dig("result", "data")
+
+              instrumentation_payload[:png_base64] = png_base64
+
+              if outputfile
+                raise ScreenshotError, "Folder does not exist: #{File.dirname(outputfile)}" unless File.directory?(File.dirname(outputfile))
+
+                File.binwrite(outputfile, Base64.decode64(png_base64))
+                Bidi2pdf.logger.info "Screenshot saved as '#{outputfile}'."
+              end
+
+              block.call(png_base64) if block_given?
+
+              return png_base64 unless outputfile || block_given?
+            else
+              Bidi2pdf.logger.error "Error capturing screenshot: #{response}"
+            end
+          end
+        end
+      end
+
+      # rubocop:enable Metrics/AbcSize
+
+      # Sets the browsing context's viewport - makes a headless render deterministic across
+      # machines, unlike leaving it at the browser's own default.
+      #
+      # @param [Integer] width
+      # @param [Integer] height
+      # @param [Float, nil] device_pixel_ratio Defaults to nil (browser default).
+      def set_viewport(width:, height:, device_pixel_ratio: nil)
+        cmd = Commands::SetViewport.new(context: browsing_context_id, width: width, height: height, device_pixel_ratio: device_pixel_ratio)
+        client.send_cmd_and_wait(cmd) { |response| response }
+      end
+
       private
 
       def build_command_and_extractor(print_options)

data/lib/bidi2pdf/bidi/commands/capture_screenshot.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module Bidi
+    module Commands
+      class CaptureScreenshot
+        include Base
+
+        attr_reader :context, :origin, :format, :clip
+
+        def initialize(context:, origin: "document", format: nil, clip: nil)
+          @context = context
+          @origin = origin
+          @format = format
+          @clip = clip
+        end
+
+        def method_name
+          "browsingContext.captureScreenshot"
+        end
+
+        def params
+          {
+            context: context,
+            origin: origin,
+            format: format,
+            clip: clip
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/bidi2pdf/bidi/commands/set_viewport.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module Bidi
+    module Commands
+      class SetViewport
+        include Base
+
+        attr_reader :context, :width, :height, :device_pixel_ratio
+
+        def initialize(context:, width:, height:, device_pixel_ratio: nil)
+          @context = context
+          @width = width
+          @height = height
+          @device_pixel_ratio = device_pixel_ratio
+        end
+
+        def method_name
+          "browsingContext.setViewport"
+        end
+
+        def params
+          {
+            context: context,
+            viewport: { width: width, height: height },
+            devicePixelRatio: device_pixel_ratio
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/bidi2pdf/bidi/commands.rb

@@ -18,6 +18,8 @@ module Bidi2pdf
       require_relative "commands/browsing_context_close"
       require_relative "commands/browsing_context_navigate"
       require_relative "commands/browsing_context_print"
+      require_relative "commands/capture_screenshot"
+      require_relative "commands/set_viewport"
       require_relative "commands/cdp_get_session"
       require_relative "commands/page_print"
       require_relative "commands/session_subscribe"

data/lib/bidi2pdf/cli.rb

@@ -40,6 +40,8 @@ module Bidi2pdf
     option :header, type: :array, default: [], banner: "name=value", desc: "One or more custom headers", aliases: "-H"
     option :auth, type: :string, banner: "user:pass", desc: "Basic auth credentials", aliases: "-a"
     option :headless, type: :boolean, default: true, desc: "Run Chrome in headless mode"
+    option :no_sandbox, type: :boolean, default: false, desc: "Disable Chrome sandbox (needed inside containers)"
+    option :chrome_flag, type: :array, default: [], banner: "--flag[=value]", desc: "Extra Chrome flags appended to defaults", aliases: "--cf"
     option :port, type: :numeric, default: 0, desc: "Port to run ChromeDriver on (0 = auto)"
     option :wait_window_loaded,
            type: :boolean,
@@ -114,6 +116,8 @@ module Bidi2pdf
         "url" => "https://example.com",
         "output" => "output.pdf",
         "headless" => true,
+        "no_sandbox" => false,
+        "chrome_flag" => [],
         "print_options" => {
           "background" => true,
           "orientation" => "portrait",
@@ -210,6 +214,11 @@ module Bidi2pdf
       @launcher ||= begin
                       username, password = parse_auth(merged_options[:auth]) if merged_options[:auth]
 
+                      chrome_args = Bidi2pdf::Bidi::Session::DEFAULT_CHROME_ARGS.dup
+                      no_sandbox = merged_options[:no_sandbox] || ENV["DISABLE_CHROME_SANDBOX"] == "true"
+                      chrome_args << "--no-sandbox" if no_sandbox
+                      chrome_args.concat(Array(merged_options[:chrome_flag]))
+
                       Bidi2pdf::Launcher.new(
                         url: merged_options[:url],
                         inputfile: merged_options[:hmtl_file],
@@ -223,7 +232,8 @@ module Bidi2pdf
                         wait_window_loaded: merged_options[:wait_window_loaded],
                         wait_network_idle: merged_options[:wait_network_idle],
                         print_options: print_options,
-                        network_log_format: merged_options[:network_log_format]
+                        network_log_format: merged_options[:network_log_format],
+                        chrome_args: chrome_args
                       )
                     end
     end

data/lib/bidi2pdf/launcher.rb

@@ -38,7 +38,8 @@ module Bidi2pdf
   class Launcher
     # rubocop:disable Metrics/ParameterLists
     def initialize(url:, inputfile:, output:, cookies:, headers:, auth:, headless: true, port: 0, wait_window_loaded: false,
-                   wait_network_idle: false, print_options: {}, remote_browser_url: nil, network_log_format: :console)
+                   wait_network_idle: false, print_options: {}, remote_browser_url: nil, network_log_format: :console,
+                   chrome_args: Bidi::Session::DEFAULT_CHROME_ARGS)
       @url = url
       @inputfile = inputfile
       @port = port
@@ -54,6 +55,7 @@ module Bidi2pdf
       @remote_browser_url = remote_browser_url
       @custom_session = nil
       @network_log_format = network_log_format
+      @chrome_args = chrome_args
     end
 
     # rubocop:enable Metrics/ParameterLists
@@ -84,9 +86,9 @@ module Bidi2pdf
 
     def session
       if @remote_browser_url
-        @custom_session = Bidi::Session.new(session_url: @remote_browser_url, headless: @headless)
+        @custom_session = Bidi::Session.new(session_url: @remote_browser_url, headless: @headless, chrome_args: @chrome_args)
       else
-        @manager = ChromedriverManager.new(port: @port, headless: @headless)
+        @manager = ChromedriverManager.new(port: @port, headless: @headless, chrome_args: @chrome_args)
         @manager.start
         @manager.session
       end

data/lib/bidi2pdf/test_helpers/images.rb

@@ -6,6 +6,14 @@ rescue LoadError
   warn "Missing #{dep}. Add it to your Gemfile if you're using Bidi2pdf image test helpers."
 end
 
+# CVE-2026-66066 (Rails Active Storage, 2026-07-29): libvips ships loaders/savers that were never
+# fuzz-tested (SVG, JPEG XL, JPEG 2000, BMP, ICO, PSD, anything delegated to ImageMagick, ...) -
+# left reachable, a crafted file can trigger arbitrary file read or RCE. Applied once, here, for
+# every consumer of this opt-in module (Extractor, ImageSimilarityChecker, contains_pdf_image),
+# rather than left to each call site to remember - PNG/JPEG (what this gem's own screenshot/PDF
+# rendering actually produces) load through already-fuzzed loaders and are unaffected.
+Vips.block_untrusted(true) if defined?(Vips)
+
 require_relative "images/tiff_helper"
 require_relative "images/extractor"
 require_relative "images/image_similarity_checker"

data/lib/bidi2pdf/test_helpers/pdf_reader_utils.rb

@@ -49,7 +49,7 @@ module Bidi2pdf
         # @param pdf_data [String, StringIO, File] The PDF data to be converted.
         # @return [IO] An IO object containing the PDF data.
         def convert_data_to_io(pdf_data)
-          # rubocop:disable Lint/DuplicateBranch
+          # rubocop:disable-next Lint/DuplicateBranch
           if pdf_data.is_a?(String) && (pdf_data.start_with?("JVBERi") || pdf_data.start_with?("JVBER"))
             StringIO.new(Base64.decode64(pdf_data))
           elsif pdf_data.start_with?("%PDF-")
@@ -61,7 +61,6 @@ module Bidi2pdf
           else
             StringIO.new(pdf_data)
           end
-          # rubocop:enable Lint/DuplicateBranch
         end
       end
 

data/lib/bidi2pdf/test_helpers/pdf_text_sanitizer.rb

@@ -6,7 +6,7 @@ require "diff/lcs/hunk"
 
 module Bidi2pdf
   module TestHelpers
-    # rubocop: disable Metrics/ModuleLength
+    # rubocop: disable-next Metrics/ModuleLength
     module PDFTextSanitizer
       class << self
         def clean(text)
@@ -148,6 +148,5 @@ module Bidi2pdf
         end
       end
     end
-    # rubocop:enable Metrics/ModuleLength
   end
 end

data/lib/bidi2pdf/test_helpers/testcontainers/chromedriver_container.rb

@@ -73,7 +73,7 @@ module Bidi2pdf
         # rubocop: enable Metrics/AbcSize
 
         def session_url(protocol: "http")
-          "#{protocol}://#{host}:#{mapped_port(port)}/session"
+          ContainerEndpoint.new(self, port).url(scheme: protocol, path: "session")
         end
       end
     end

data/lib/bidi2pdf/test_helpers/testcontainers/chromedriver_test_helper.rb

@@ -36,6 +36,24 @@ module Bidi2pdf
         def create_session(session_url)
           Bidi2pdf::Bidi::Session.new(session_url: session_url, headless: true, chrome_args: chrome_args)
         end
+
+        # Full session/tab lifecycle in one call - create_session above only builds the session
+        # object, it never starts or closes it, and there is no after(:each) teardown for a spec
+        # that uses it directly. Mirrors Bidi2pdf::DSL.with_tab's own ensure-based teardown, but
+        # against a session_url this module already knows about (a long-lived remote-chrome
+        # reached over `session:` metadata, not a freshly spawned local chromedriver per call).
+        def with_tab(session_url)
+          session = create_session(session_url)
+          session.start
+          user_context = session.browser.create_user_context
+          tab = user_context.create_browser_window
+
+          yield tab
+        ensure
+          tab&.close
+          user_context&.close
+          session&.close
+        end
       end
     end
   end

data/lib/bidi2pdf/test_helpers/testcontainers/container_endpoint.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module TestHelpers
+    module Testcontainers
+      # Builds a URL for reaching a container's published port from the test
+      # process, using the container's own host/port resolution.
+      class ContainerEndpoint
+        def initialize(container, port)
+          @container = container
+          @port = port
+        end
+
+        def url(scheme: "http", path: "")
+          "#{scheme}://#{@container.accessible_host}:#{@container.mapped_port(@port)}/#{path}"
+        end
+
+        # Address reachable from another container on the same Docker network (e.g. remote-chrome
+        # reaching nginx), by alias and internal port - as opposed to #url's host-accessible,
+        # externally-mapped port. Uses the same @port this instance was built with, not a
+        # container_ports.first guess: the two methods must agree on which port they're both
+        # describing for the same container, or a caller comparing #url and #alias_url for what's
+        # meant to be the same endpoint could silently get two different services.
+        def alias_url(scheme: "http", path: "")
+          "#{scheme}://#{@container.aliases.first}:#{@port}/#{path}"
+        end
+      end
+    end
+  end
+end

data/lib/bidi2pdf/test_helpers/testcontainers/testcontainers_refinement.rb

@@ -29,6 +29,39 @@ module Bidi2pdf
         self
       end
 
+      def container_json
+        @_container&.json
+      end
+
+      # Address of the Docker host at which this container's *mapped* ports
+      # are reachable from the test process.
+      #
+      # Resolution belongs to testcontainers: it honours TC_HOST, a tcp:/ssh:
+      # DOCKER_HOST, a native local daemon, and a sibling container reaching
+      # the daemon over the bridge gateway — and it derives #mapped_port from
+      # the same decision, so the two must stay on one path. We only add a
+      # fallback for the cases 0.2.0 leaves unresolved.
+      #
+      # This is not the address containers use to reach each other; for that
+      # the helpers join a shared network and address containers by alias.
+      def accessible_host
+        resolved_host || "localhost"
+      end
+
+      # testcontainers-core 0.2.0 cannot resolve a host when the test process
+      # runs inside a container and the container under test is on a custom
+      # network: #container_gateway_ip hardcodes the "bridge" network key
+      # (docker_container.rb:1074), so #host returns nil. On the default
+      # bridge it can instead reach docker_container.rb:703, which calls an
+      # undefined `bridge_ip`. Both are fixed on testcontainers-ruby main;
+      # treat either as "unresolved" and fall back.
+      def resolved_host
+        value = host
+        value unless value.nil? || value.empty?
+      rescue NoMethodError
+        nil
+      end
+
       def _container_create_options
         opts = super
         network_name = network&.info&.[]("Name")

data/lib/bidi2pdf/test_helpers/testcontainers.rb

@@ -10,6 +10,7 @@ module Bidi2pdf
   module TestHelpers
     module Testcontainers
       require_relative "testcontainers/testcontainers_refinement"
+      require_relative "testcontainers/container_endpoint"
       require_relative "testcontainers/chromedriver_container"
       require_relative "testcontainers/chromedriver_test_helper"
     end

data/lib/bidi2pdf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bidi2pdf
-  VERSION = "0.1.13"
+  VERSION = "0.1.14"
 end

data/lib/bidi2pdf.rb

@@ -51,6 +51,8 @@ module Bidi2pdf
 
   class PrintError < Error; end
 
+  class ScreenshotError < Error; end
+
   class ScriptInjectionError < Error; end
 
   class StyleInjectionError < Error; end

data/sig/bidi2pdf/bidi/add_headers_interceptor.rbs

@@ -1,20 +1,27 @@
 module Bidi2pdf
   module Bidi
     class AddHeadersInterceptor
-      @id: String
-      @client: untyped
-      @headers: Hash[String, String]
+      @headers: untyped
 
-      attr_reader id: String
-      attr_reader headers: Hash[String, String]
+      @url_patterns: untyped
 
-      def initialize: (String id, Hash[String, String] headers, untyped client) -> void
+      @context: untyped
 
-      def handle_event: (Hash[String, untyped] response) -> (nil | untyped)
+      include Interceptor
 
-      private
+      def self.phases: () -> ::Array[untyped]
 
-      attr_reader client: untyped
+      def self.events: () -> ::Array["network.beforeRequestSent"]
+
+      attr_reader headers: untyped
+
+      attr_reader url_patterns: untyped
+
+      attr_reader context: untyped
+
+      def initialize: (headers: untyped, url_patterns: untyped, context: untyped) -> void
+
+      def process_interception: (untyped _event_response, untyped _navigation_id, untyped network_id, untyped _url) -> untyped
     end
   end
 end

data/sig/bidi2pdf/bidi/auth_interceptor.rbs

@@ -1,17 +1,42 @@
 module Bidi2pdf
   module Bidi
     class AuthInterceptor
-      @credentials: Hash[Symbol, String]?
+      @url_patterns: untyped
 
-      def initialize: (?credentials: Hash[Symbol, String]?) -> void
+      @context: untyped
 
-      def intercept: (untyped request) -> untyped
+      @username: untyped
 
-      private
+      @password: untyped
+
+      @network_ids: untyped
+
+      include Interceptor
+
+      def self.phases: () -> ::Array[untyped]
+
+      def self.events: () -> ::Array["network.authRequired"]
+
+      attr_reader headers: untyped
+
+      attr_reader url_patterns: untyped
 
-      def add_auth_header: (untyped request) -> void
+      attr_reader context: untyped
+
+      attr_reader username: untyped
+
+      attr_reader password: untyped
+
+      attr_reader network_ids: untyped
+
+      def initialize: (username: untyped, password: untyped, url_patterns: untyped, context: untyped) -> void
+
+      def process_interception: (untyped _event_response, untyped navigation_id, untyped network_id, untyped url) -> untyped
+
+      private
 
-      def auth_header_value: () -> String?
+      # rubocop:disable Naming/PredicateMethod
+      def handled_bad_credentials: (untyped navigation_id, untyped network_id, untyped url) -> (false | true)
     end
   end
-end
+end

data/sig/bidi2pdf/bidi/browser.rbs

@@ -1,38 +1,11 @@
 module Bidi2pdf
   module Bidi
     class Browser
-      @url: String
-      @chromedriver_manager: Bidi2pdf::ChromedriverManager
-      @browser: untyped
-      @timeout: Integer
-      @debug: bool
+      @client: untyped
 
-      attr_reader browser: untyped
-      attr_reader timeout: Integer
+      def initialize: (untyped client) -> void
 
-      def initialize: (
-          url: String,
-          chromedriver_manager: Bidi2pdf::ChromedriverManager,
-          ?timeout: Integer,
-          ?debug: bool
-        ) -> void
-
-      def navigate: (?reload: bool) -> void
-
-      def current_url: -> String
-
-      def wait_until: [T] (
-          ?timeout: Integer,
-          ?message: String
-        ) { () -> T? } -> T
-
-      def close: () -> void
-
-      private
-
-      def connect: () -> untyped
-
-      def setup_browser: () -> untyped
+      def create_user_context: () -> untyped
     end
   end
-end
+end

data/sig/bidi2pdf/bidi/browser_console_logger.rbs

@@ -0,0 +1,59 @@
+module Bidi2pdf
+  module Bidi
+    class BrowserConsoleLoggerSuggar
+      @browser_console_logger: untyped
+
+      @level: untyped
+
+      @prefix: untyped
+
+      @timestamp: untyped
+
+      @text: untyped
+
+      @args: untyped
+
+      @stack_trace: untyped
+
+      attr_reader browser_console_logger: untyped
+
+      def initialize: (untyped browser_console_logger) -> void
+
+      def with_level: (untyped level) -> self
+
+      def with_prefix: (untyped prefix) -> self
+
+      def with_timestamp: (untyped timestamp) -> self
+
+      def with_text: (untyped text) -> self
+
+      def with_args: (untyped args) -> self
+
+      def with_stack_trace: (untyped stack_trace) -> self
+
+      def log_event: () -> untyped
+
+      def prefix: () -> untyped
+    end
+
+    class BrowserConsoleLogger
+      @logger: untyped
+
+      include JsLoggerHelper
+
+      attr_accessor logger: untyped
+
+      def initialize: (untyped logger) -> void
+
+      def builder: () -> untyped
+
+      def log_message: (untyped level, untyped prefix, untyped text) -> (nil | untyped)
+
+      def log_args: (untyped prefix, untyped args) -> (nil | untyped)
+
+      def log_stack_trace: (untyped prefix, untyped trace) -> untyped
+
+      def self.format_timestamp: (untyped timestamp) -> ("N/A" | untyped)
+    end
+  end
+end