bidi2pdf 0.1.22 → 0.1.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '008d5b0569ba4b7f8bbcd4092da72ce14e5d0e42589a97813f7c64c8bc6a0d9f'
-  data.tar.gz: 8266f91bfa7606d843bed392cee203060cc3b13d98435cc9a0c4a679b5041285
+  metadata.gz: 9bff5f993e54cb0f70e6a2c83e022bf29fdef7b0fafc6ce8b641d5ec33aea7ea
+  data.tar.gz: e2466bb66703e3a7ac4ca16bfdea22f836c8fff07492e9f44904ecf5bc9c9c63
 SHA512:
-  metadata.gz: 27ce2475fa8d30bc9c5447353767c6d2c06db59f57daa7fab7e7a337e26703cc1a0df04439d2b8b68455e5a872138775321a7f31988beb02dba47df0dd06d48d
-  data.tar.gz: acb216b0c656916ee8e8ea797b1fccd026c67fa6260ac5f230f1c44190ffb00455fd83efb5238826c97af0f0051cf68a7335d09e51e0aaa25b85c2efdc802290
+  metadata.gz: 6958ef3cc24d5350fdb090598940410f5cd3ab9abef4003f118d52ab61142b45c6427e0225ed4d37a9fa3a23d0dfd033e67a07cc981f891cb2f1f95f7af67612
+  data.tar.gz: 74a366dc1c4953bb6e17e8c7578d3ec79cd7a0ea9f1f058f9d353ebdab12b2b046d7e25424b22745081895b09f60a5ca7a701eb29763472b9320e6a564142ad7

data/CHANGELOG.md

@@ -8,10 +8,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.22..HEAD
+[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.23..HEAD
 
 <!-- generated by git-cliff end -->
 
+## [0.1.23] - 2026-10-18
+
+### 🐛 Fixed
+- Spell the plugin version as semver
+- Keep screenshot names apart and stop browsers
+- Stop every browser even when one stop fails
+- Keep stdout to the JSON document or the PDF
+- Lay a mobile print out at the intended width
+
+### 📝 Docs
+- Explain how to install, pin and update the Claude Code skills
+- Fix the script path and weigh the Chrome sandbox
+
+### 🔄 Changed
+- Merge pull request #170 from dieter-medium/feat/claude-skills
+- Merge pull request #169 from dieter-medium/fix/clean-stdout
+- Merge pull request #160 from dieter-medium/dependabot/bundler/main/simplecov-1.3.2
+- Merge pull request #167 from dieter-medium/dependabot/bundler/main/rubocop-1.92.0
+- Merge pull request #168 from dieter-medium/feat/emulate-media
+
+### 🔧 Build
+- Bump simplecov from 1.3.1 to 1.3.2
+- Bump rubocop from 1.91.0 to 1.92.0
+
+### 🚀 Added
+- Ship Claude Code skills for bidi2pdf
+- Let a tab emulate a CSS media type
+
 ## [0.1.22] - 2026-10-11
 
 ### 🐛 Fixed
@@ -568,7 +596,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 🔄 Released
 
-- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.22..HEAD)
+- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.23..HEAD)
+- [0.1.23](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.22..v0.1.23)
 - [0.1.22](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.21..v0.1.22)
 - [0.1.21](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.20..v0.1.21)
 - [0.1.20](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.19..v0.1.20)

data/README.md

@@ -110,6 +110,26 @@ bidi2pdf render \
   --log-level debug
 ```
 
+#### The page as it looks on screen, dark mode, or its mobile version
+
+By default Chrome prints with the page's print stylesheet. `--media screen` prints its screen styles
+instead, `--color_scheme dark` its dark mode, `--reduced_motion reduce` with animations off.
+
+A narrow page adds the page's mobile layout. A printed page is laid out at the width between its side
+margins, not at the paper's width: page width minus `--margin_left` and `--margin_right`, at about
+37.8 CSS px per cm (96 / 2.54). Without margins of your own Chrome uses 1 cm a side, so a 9.5 cm page
+lays out at about 283 px. For a 360 px phone layout, set the side margins explicitly:
+
+```bash
+bidi2pdf render --url https://example.com --output mobile.pdf \
+  --media screen --color_scheme dark \
+  --page_width 9.525 --page_height 20 --margin_left 0 --margin_right 0
+```
+
+8.467 cm without side margins gives 320 px. All page sizes and margins are in centimetres.
+
+`bidi2pdf diagnose` takes the same three options, so its screenshot shows the same emulation.
+
 ---
 
 ## 🤖 Agent and Automation Usage
@@ -243,7 +263,7 @@ bidi2pdf run invoice.yml --json       # actions, then the PDF, then assertions a
 ```
 
 Actions (`wait_for`, `click`, `evaluate`, `inject_script`, `inject_style`, `set_viewport`,
-`wait_network_idle`) and page assertions (`selector_exists`, `text_present`, `no_console_errors`,
+`wait_network_idle`, `emulate_media`) and page assertions (`selector_exists`, `text_present`, `no_console_errors`,
 `no_network_failures`, `fonts_loaded`) are a thin layer over the same `BrowserTab` methods the
 [Programmatic API](#-programmatic-api) below uses directly. PDF assertions (`page_count`,
 `pdf_text_present`, `pdf_not_blank`) need the `pdf-reader` gem - a recipe using one fails
@@ -256,6 +276,91 @@ rejected by both `bidi2pdf schema recipe` and `--validate` rather than being sil
 `wait_for` needs exactly one of `selector`, `paged_js`, `script` - zero or more than one is
 rejected the same way, before any browser launches.
 
+### Claude Code skills
+
+The repository ships a [Claude Code](https://claude.com/claude-code) plugin with six skills, so an
+agent uses bidi2pdf the way it is meant to be used instead of guessing options:
+
+| Skill | For |
+|---|---|
+| `render-pdf` | a URL or HTML file to PDF with the CLI: order of commands, waits, screen/dark/mobile view, reading the JSON result and exit codes |
+| `pdf-recipe` | a recipe for pages that need steps before printing, validated without a browser |
+| `diagnose-pdf` | a blank, unstyled or wrongly paged PDF: a checklist around `bidi2pdf diagnose` |
+| `remote-chrome` | a shared chromedriver container: settings, sizing, session cleanup, untrusted HTML |
+| `page-screenshots` | review screenshots per page at phone and desktop width, light and dark (with a script) |
+| `pdf-specs` | RSpec specs with the gem's PDF matchers and Chrome container helpers |
+
+#### Installing the skills
+
+The plugin is not in a central store: this repository is its own Claude Code marketplace
+(`.claude-plugin/marketplace.json`, marketplace name `bidi2pdf`). You add the repository as a
+marketplace once, then install the plugin from it. In a Claude Code session:
+
+```text
+/plugin marketplace add dieter-medium/bidi2pdf
+/plugin install bidi2pdf@bidi2pdf
+```
+
+`/plugin install` does not install right away: it opens the plugin's details, where you choose the scope
+(just you, the project, or only this checkout) and confirm the installation.
+
+Or from a shell, where the install happens at once:
+
+```bash
+claude plugin marketplace add dieter-medium/bidi2pdf
+claude plugin install bidi2pdf@bidi2pdf          # --scope user (default), project or local
+```
+
+The skills then load on their own when a task fits them; nothing else needs configuring.
+
+**Which version you get.** The plugin's version is the gem's (`claude-plugin/.claude-plugin/plugin.json`),
+and Claude Code installs an update only when that version changes - not with every commit. Adding the
+marketplace as above follows the default branch, so after a release the skills there can already
+describe the next, unreleased gem (the version then reads e.g. `0.1.24-pre`). To stay on the skills of
+the gem you actually use, add the marketplace at its release tag:
+
+```bash
+claude plugin marketplace add dieter-medium/bidi2pdf#v0.1.23
+```
+
+**Updating and removing.** Auto-update is off for this marketplace unless you turn it on (`/plugin` >
+Marketplaces). By hand:
+
+```bash
+claude plugin marketplace update bidi2pdf     # fetch the marketplace again
+claude plugin update bidi2pdf@bidi2pdf        # take the new version
+claude plugin uninstall bidi2pdf@bidi2pdf     # remove the plugin only
+claude plugin marketplace remove bidi2pdf     # remove the marketplace and every plugin installed from it
+```
+
+**For a whole team.** To give everyone working in a project the skills, commit this to the project's
+`.claude/settings.json` - each member gets them after accepting Claude Code's trust prompt for the
+folder:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "bidi2pdf": { "source": { "source": "github", "repo": "dieter-medium/bidi2pdf" } }
+  },
+  "enabledPlugins": { "bidi2pdf@bidi2pdf": true }
+}
+```
+
+`claude plugin marketplace add dieter-medium/bidi2pdf --scope project` and
+`claude plugin install bidi2pdf@bidi2pdf --scope project` write the same entries for you.
+
+**From a checkout, without installing** (to try a change to a skill):
+
+```bash
+claude --plugin-dir ./claude-plugin                   # for this one session
+claude plugin validate ./claude-plugin --strict       # check the plugin's structure
+```
+
+The skills point at `bidi2pdf help <command>` and `bidi2pdf schema <kind>` for exact options and
+shapes; a spec (`spec/unit/claude_plugin_spec.rb`) checks every command, option, error code, recipe and
+method they name against the gem, so they cannot drift from it. The plugin is not part of the gem
+itself.
+
 ---
 
 ## 🧠 Programmatic API
@@ -350,6 +455,10 @@ tab.navigate_to "https://example.com/invoice/14432423"
 # Printing HTML you do not trust? Switch its scripts off before navigating:
 # tab.disable_script_execution
 
+# Print the screen styles in dark mode instead of the print stylesheet (holds for later
+# navigations in this tab; tab.emulate_media without arguments ends it):
+# tab.emulate_media(media: "screen", color_scheme: "dark")
+
 tab.wait_until_network_idle
 tab.print("my.pdf")
 

data/lib/bidi2pdf/bidi/browser_tab.rb

@@ -41,6 +41,13 @@ module Bidi2pdf
     class BrowserTab
       include JsLoggerHelper
 
+      # The values #emulate_media accepts, by argument - what Chrome's Emulation.setEmulatedMedia knows.
+      EMULATED_MEDIA = {
+        media: %w[screen print],
+        color_scheme: %w[light dark],
+        reduced_motion: %w[reduce no-preference]
+      }.freeze
+
       # @return [Object] The WebSocket client.
       attr_reader :client
 
@@ -439,7 +446,9 @@ module Bidi2pdf
 
               block.call(pdf_base64) if block_given?
 
-              return pdf_base64 unless outputfile || block_given?
+              # The block's value, not a `return`: returning out of the instrumented block would
+              # skip the print event, and with it every subscriber (ResultCollector, --output -).
+              outputfile || block_given? ? nil : pdf_base64
             else
               Bidi2pdf.logger.error "Error printing: #{response}"
             end
@@ -480,7 +489,8 @@ module Bidi2pdf
 
               block.call(png_base64) if block_given?
 
-              return png_base64 unless outputfile || block_given?
+              # The block's value, not a `return` - see #print.
+              outputfile || block_given? ? nil : png_base64
             else
               Bidi2pdf.logger.error "Error capturing screenshot: #{response}"
             end
@@ -513,8 +523,43 @@ module Bidi2pdf
         client.send_cmd_and_wait(cmd) { |response| response }
       end
 
+      # Emulates a CSS media type and media features for this tab, through Chrome's own
+      # Emulation.setEmulatedMedia (CDP, via goog:cdp.sendCommand). It holds for every later
+      # navigation in the tab and for printing: +media: "screen"+ prints a page with its screen styles
+      # instead of its print stylesheet, +color_scheme: "dark"+ in its dark mode. On a narrow page the
+      # screen media type prints a page's mobile layout: the layout width is the page width minus the
+      # side margins (Chrome's default is 1 cm each), at 96 / 2.54 CSS px per cm - e.g.
+      # +page: { width: 9.525 }, margin: { left: 0, right: 0 }+ lays out at 360 px. Each call replaces
+      # the previous emulation, so a media type or feature it omits is reset; a call without arguments
+      # ends it.
+      #
+      # @param [String, Symbol, nil] media "screen" or "print"; nil leaves it to the browser.
+      # @param [String, Symbol, nil] color_scheme "light" or "dark" (prefers-color-scheme).
+      # @param [String, Symbol, nil] reduced_motion "reduce" or "no-preference" (prefers-reduced-motion).
+      # @raise [ArgumentError] for a value Chrome does not know, before anything is sent.
+      def emulate_media(media: nil, color_scheme: nil, reduced_motion: nil)
+        params = emulated_media_params(media: media, color_scheme: color_scheme, reduced_motion: reduced_motion)
+        cmd = Commands::CdpSendCommand.new(method: "Emulation.setEmulatedMedia", params: params, session: cdp_session)
+        client.send_cmd_and_wait(cmd) { |response| response }
+      end
+
       private
 
+      def emulated_media_params(**values)
+        values.each { |name, value| check_emulated_media(name, value) }
+
+        features = { "prefers-color-scheme" => values[:color_scheme], "prefers-reduced-motion" => values[:reduced_motion] }
+                   .filter_map { |name, value| { name: name, value: value.to_s } unless value.nil? }
+        { media: values[:media].to_s, features: features }
+      end
+
+      def check_emulated_media(name, value)
+        allowed = EMULATED_MEDIA.fetch(name)
+        return if value.nil? || allowed.include?(value.to_s)
+
+        raise ArgumentError, "#{name} must be one of #{allowed.join(", ")}, got #{value.inspect}"
+      end
+
       def build_command_and_extractor(print_options)
         cmd_type = (print_options.delete(:cmd_type) || :bidi).to_sym
 

data/lib/bidi2pdf/cli.rb

@@ -78,10 +78,10 @@ module Bidi2pdf
     option :manifest, type: :string, desc: "Write a render manifest (see `bidi2pdf schema manifest`) to this file"
 
     option :background, type: :boolean, default: true, desc: "Print background graphics"
-    option :margin_top, type: :numeric, default: 1.0, desc: "Top margin in inches"
-    option :margin_bottom, type: :numeric, default: 1.0, desc: "Bottom margin in inches"
-    option :margin_left, type: :numeric, default: 1.0, desc: "Left margin in inches"
-    option :margin_right, type: :numeric, default: 1.0, desc: "Right margin in inches"
+    option :margin_top, type: :numeric, default: 1.0, desc: "Top margin in cm"
+    option :margin_bottom, type: :numeric, default: 1.0, desc: "Bottom margin in cm"
+    option :margin_left, type: :numeric, default: 1.0, desc: "Left margin in cm"
+    option :margin_right, type: :numeric, default: 1.0, desc: "Right margin in cm"
     option :orientation, type: :string, default: "portrait", enum: %w[portrait landscape], desc: "Page orientation"
     option :page_width, type: :numeric, default: 21.59, desc: "Page width in cm (min 0.0352)"
     option :page_height, type: :numeric, default: 27.94, desc: "Page height in cm (min 0.0352)"
@@ -90,6 +90,9 @@ module Bidi2pdf
     option :shrink_to_fit, type: :boolean, default: true, desc: "Shrink content to fit page"
     option :generate_tagged_pdf, type: :boolean, default: false, desc: "Generate tagged PDF"
     option :generate_document_outline, type: :boolean, default: false, desc: "Generate document outline"
+    option :media, type: :string, enum: %w[screen print], desc: "Emulate a CSS media type; screen prints the page with its screen styles. For its mobile layout, narrow the page: the layout width is --page_width minus the side margins, 9.525 cm with --margin_left 0 --margin_right 0 = 360 CSS px"
+    option :color_scheme, type: :string, enum: %w[light dark], desc: "Emulate prefers-color-scheme"
+    option :reduced_motion, type: :string, enum: %w[reduce no-preference], desc: "Emulate prefers-reduced-motion"
 
     class << self
       def exit_on_failure?
@@ -152,6 +155,9 @@ module Bidi2pdf
     option :json, type: :boolean, default: false, desc: "Emit a single structured JSON document (see `bidi2pdf schema diagnose`) instead of a human-readable summary"
     option :json_stream, type: :boolean, default: false, desc: "Emit one JSON progress event per line to stderr as diagnostics run, with or without --json (see `bidi2pdf schema event`)"
     option :screenshot, type: :string, desc: "Also capture a screenshot to this PNG file"
+    option :media, type: :string, enum: %w[screen print], desc: "Emulate a CSS media type; screen prints the page with its screen styles. For its mobile layout, narrow the page: the layout width is --page_width minus the side margins, 9.525 cm with --margin_left 0 --margin_right 0 = 360 CSS px"
+    option :color_scheme, type: :string, enum: %w[light dark], desc: "Emulate prefers-color-scheme"
+    option :reduced_motion, type: :string, enum: %w[reduce no-preference], desc: "Emulate prefers-reduced-motion"
     option :pdf, type: :string, desc: "Also render a PDF to this file and report its page count / blank-check"
 
     def diagnose
@@ -307,9 +313,11 @@ module Bidi2pdf
         emit_structured_render_output(result, collector)
 
         exit_for_result(result)
+      ensure
+        stop_browsers
       end
     ensure
-      launcher.stop if defined?(@launcher) && @launcher
+      stop_browsers
       stream&.unsubscribe
       cleanup_stdin_tempfile
     end
@@ -369,9 +377,11 @@ module Bidi2pdf
         $stdout.puts(diagnose_payload(result, diagnostics).to_json)
 
         exit_for_result(result)
+      ensure
+        stop_browsers
       end
     ensure
-      launcher.stop if defined?(@launcher) && @launcher
+      stop_browsers
       stream&.unsubscribe
       cleanup_stdin_tempfile
     end
@@ -413,7 +423,6 @@ module Bidi2pdf
     # --- run - Loader/Validator run before any browser work, both in --validate and in a real
     # run, so an invalid recipe never launches one.
 
-    # rubocop:disable-next Metrics/CyclomaticComplexity
     def perform_human_run(recipe_path)
       recipe = load_and_validate_recipe(recipe_path)
       return puts "Recipe '#{recipe_path}' is valid." if merged_options[:validate]
@@ -448,12 +457,12 @@ module Bidi2pdf
     rescue Bidi2pdf::Error => e
       raise Thor::Error, e.message
     ensure
-      @run_launcher&.stop
+      stop_browsers
       stream&.unsubscribe
       cleanup_stdin_tempfile
     end
 
-    # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    # rubocop:disable-next Metrics/CyclomaticComplexity
     def perform_structured_run(recipe_path)
       recipe = load_and_validate_recipe(recipe_path)
 
@@ -490,12 +499,14 @@ module Bidi2pdf
         $stdout.puts(payload.to_json)
 
         exit_for_result(result)
+      ensure
+        stop_browsers
       end
     rescue Bidi2pdf::InvalidRecipeError, Bidi2pdf::PdfInspectionUnavailableError, Bidi2pdf::InvalidPrintOptionError => e
       $stdout.puts Bidi2pdf::Result.failure(command: "run", error: ErrorCodes.describe(e)).to_json
       exit(Bidi2pdf::ExitCodes.for(ErrorCodes.for(e)))
     ensure
-      @run_launcher&.stop
+      stop_browsers
       stream&.unsubscribe
       cleanup_stdin_tempfile
     end
@@ -510,6 +521,22 @@ module Bidi2pdf
       recipe.source["url"] || recipe.source["file"] || "(stdin)"
     end
 
+    # Stops whatever browser this command started, once. The structured paths call it inside
+    # reserve_stdout_for_machine_output, while the loggers still write to stderr: stopping logs
+    # ("WebSocket closed"), and after the block those lines would land on stdout behind the JSON
+    # document or the PDF bytes. Each browser is stopped on its own, and a failing stop is logged,
+    # not raised: this runs in an ensure, where raising would replace the command's own result and
+    # exit status.
+    def stop_browsers
+      launchers = [(@launcher if defined?(@launcher)), (@run_launcher if defined?(@run_launcher))].compact
+      @launcher = @run_launcher = nil
+      launchers.each do |launcher|
+        launcher.stop
+      rescue StandardError => e
+        Bidi2pdf.logger.error "Stopping the browser failed: #{e.class}: #{e.message}"
+      end
+    end
+
     def with_recipe_tab(recipe)
       @run_launcher = launcher_for_recipe(recipe)
       tab = @run_launcher.diagnose
@@ -818,11 +845,18 @@ module Bidi2pdf
                         wait_network_idle: merged_options[:wait_network_idle],
                         print_options: print_options,
                         network_log_format: merged_options[:network_log_format],
-                        chrome_args: chrome_args
+                        chrome_args: chrome_args,
+                        emulate_media: emulate_media_options
                       )
                     end
     end
 
+    # The --media/--color_scheme/--reduced_motion choices for BrowserTab#emulate_media; empty when none
+    # is given, so the browser keeps its own.
+    def emulate_media_options
+      { media: merged_options[:media], color_scheme: merged_options[:color_scheme], reduced_motion: merged_options[:reduced_motion] }.compact
+    end
+
     def configure
       Bidi2pdf.configure do |config|
         config.logger.level = log_level

data/lib/bidi2pdf/launcher.rb

@@ -35,45 +35,31 @@ module Bidi2pdf
   # @param [Hash] print_options Options for printing the page. Defaults to an empty hash.
   # @param [String, nil] remote_browser_url The URL of a remote browser to connect to. Defaults to nil.
   # @param [Symbol] network_log_format The format for network logs. Defaults to :console.
+  # @param [Hash] emulate_media Media type and features for BrowserTab#emulate_media (media:,
+  #   color_scheme:, reduced_motion:). Defaults to none.
   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,
-                   chrome_args: Bidi::Session::DEFAULT_CHROME_ARGS)
-      @url = url
-      @inputfile = inputfile
+                   chrome_args: Bidi::Session::DEFAULT_CHROME_ARGS, emulate_media: {})
+      # What both runners get, unchanged - SessionRunner's own keyword arguments.
+      @runner_options = {
+        url: url, inputfile: inputfile, output: output, cookies: cookies, headers: headers, auth: auth,
+        wait_window_loaded: wait_window_loaded, wait_network_idle: wait_network_idle, print_options: print_options || {},
+        network_log_format: network_log_format, emulate_media: emulate_media || {}
+      }
       @port = port
       @headless = headless
-      @output = output
-      @cookies = cookies
-      @headers = headers
-      @auth = auth
       @manager = nil
-      @wait_window_loaded = wait_window_loaded
-      @wait_network_idle = wait_network_idle
-      @print_options = print_options || {}
       @remote_browser_url = remote_browser_url
       @custom_session = nil
-      @network_log_format = network_log_format
       @chrome_args = chrome_args
     end
 
     # rubocop:enable Metrics/ParameterLists
 
     def launch
-      runner = SessionRunner.new(
-        session: session,
-        url: @url,
-        inputfile: @inputfile,
-        output: @output,
-        cookies: @cookies,
-        headers: @headers,
-        auth: @auth,
-        wait_window_loaded: @wait_window_loaded,
-        wait_network_idle: @wait_network_idle,
-        print_options: @print_options,
-        network_log_format: @network_log_format
-      )
+      runner = SessionRunner.new(session: session, **@runner_options)
       runner.run
     end
 
@@ -83,19 +69,7 @@ module Bidi2pdf
     #
     # @return [Bidi2pdf::Bidi::BrowserTab] the navigated tab.
     def diagnose
-      @diagnose_runner = SessionRunner.new(
-        session: session,
-        url: @url,
-        inputfile: @inputfile,
-        output: @output,
-        cookies: @cookies,
-        headers: @headers,
-        auth: @auth,
-        wait_window_loaded: @wait_window_loaded,
-        wait_network_idle: @wait_network_idle,
-        print_options: @print_options,
-        network_log_format: @network_log_format
-      )
+      @diagnose_runner = SessionRunner.new(session: session, **@runner_options)
       @diagnose_runner.run_diagnose
     end
 

data/lib/bidi2pdf/recipe/runner.rb

@@ -90,6 +90,7 @@ module Bidi2pdf
         when "inject_style" then @tab.inject_style(url: opts["url"], content: opts["content"], id: opts["id"])
         when "set_viewport" then @tab.set_viewport(width: opts["width"], height: opts["height"], device_pixel_ratio: opts["device_pixel_ratio"])
         when "wait_network_idle" then @tab.wait_until_network_idle(timeout: opts.fetch("timeout", 10))
+        when "emulate_media" then @tab.emulate_media(media: opts["media"], color_scheme: opts["color_scheme"], reduced_motion: opts["reduced_motion"])
         end
       end
 

data/lib/bidi2pdf/recipe.rb

@@ -12,7 +12,7 @@ module Bidi2pdf
   # launches) -> Validator -> Runner.
   class Recipe
     KNOWN_TOP_LEVEL_KEYS = %w[version source browser headers cookies auth actions assert print output].freeze
-    KNOWN_ACTIONS = %w[wait_for click evaluate inject_script inject_style set_viewport wait_network_idle].freeze
+    KNOWN_ACTIONS = %w[wait_for click evaluate inject_script inject_style set_viewport wait_network_idle emulate_media].freeze
     PAGE_ASSERTIONS = %w[selector_exists text_present no_console_errors no_network_failures fonts_loaded].freeze
     PDF_ASSERTIONS = %w[page_count pdf_text_present pdf_not_blank].freeze
     KNOWN_ASSERTIONS = (PAGE_ASSERTIONS + PDF_ASSERTIONS).freeze

data/lib/bidi2pdf/schema.rb

@@ -219,7 +219,7 @@ module Bidi2pdf
     }.freeze
 
     RECIPE_ACTIONS = {
-      "description" => "one of the 7 known actions - a thin dispatch over BrowserTab's own methods, see README's " \
+      "description" => "one of the 8 known actions - a thin dispatch over BrowserTab's own methods, see README's " \
                         "Agent and Automation Usage section",
       "oneOf" => [
         {
@@ -271,6 +271,18 @@ module Bidi2pdf
           "type" => "object", "required" => %w[wait_network_idle], "additionalProperties" => false,
           "properties" => { "wait_network_idle" => { "type" => "object", "additionalProperties" => false,
                                                      "properties" => { "timeout" => { "type" => "number" } } } }
+        },
+        {
+          "type" => "object", "required" => %w[emulate_media], "additionalProperties" => false,
+          "properties" => {
+            "emulate_media" => {
+              "type" => "object", "additionalProperties" => false,
+              "description" => "the CSS media type and media features the page is shown and printed with, from here on; " \
+                               "media: screen prints the screen styles; on a narrow print page (layout width = page width minus the side margins, " \
+                               "9.525 cm without side margins = 360 CSS px) the mobile layout",
+              "properties" => Bidi2pdf::Bidi::BrowserTab::EMULATED_MEDIA.to_h { |name, values| [name.to_s, { "type" => "string", "enum" => values }] }
+            }
+          }
         }
       ]
     }.freeze

data/lib/bidi2pdf/session_runner.rb

@@ -33,10 +33,12 @@ module Bidi2pdf
   # @param [Boolean] wait_network_idle Whether to wait for the network to become idle. Defaults to false.
   # @param [Hash] print_options Options for printing the page. Defaults to an empty hash.
   # @param [Symbol] network_log_format The format for network logs. Defaults to :console.
+  # @param [Hash] emulate_media Media type and features for BrowserTab#emulate_media (media:,
+  #   color_scheme:, reduced_motion:), applied before navigating. Defaults to none.
   class SessionRunner
     # rubocop: disable Metrics/ParameterLists
     def initialize(session:, url:, inputfile:, output:, cookies: {}, headers: {}, auth: {}, wait_window_loaded: false,
-                   wait_network_idle: false, print_options: {}, network_log_format: :console)
+                   wait_network_idle: false, print_options: {}, network_log_format: :console, emulate_media: {})
       @session = session
       @url = url
       @inputfile = inputfile
@@ -48,6 +50,7 @@ module Bidi2pdf
       @wait_network_idle = wait_network_idle
       @print_options = print_options || {}
       @network_log_format = network_log_format
+      @emulate_media = emulate_media || {}
     end
 
     # rubocop: enable Metrics/ParameterLists
@@ -100,6 +103,7 @@ module Bidi2pdf
 
       add_headers
       add_basic_auth
+      @tab.emulate_media(**@emulate_media) if @emulate_media.any?
     end
 
     def add_cookies(tab)

data/lib/bidi2pdf/version.rb

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

data/sig/bidi2pdf/bidi/browser_tab.rbs

@@ -56,6 +56,9 @@ module Bidi2pdf
 
       include JsLoggerHelper
 
+      # The values #emulate_media accepts, by argument - what Chrome's Emulation.setEmulatedMedia knows.
+      EMULATED_MEDIA: { media: ::Array["screen" | "print"], color_scheme: ::Array["light" | "dark"], reduced_motion: ::Array["reduce" | "no-preference"] }
+
       # @return [Object] The WebSocket client.
       attr_reader client: untyped
 
@@ -238,8 +241,28 @@ module Bidi2pdf
       # @param [Boolean] disabled Defaults to true.
       def disable_script_execution: (?disabled: bool) -> untyped
 
+      # Emulates a CSS media type and media features for this tab, through Chrome's own
+      # Emulation.setEmulatedMedia (CDP, via goog:cdp.sendCommand). It holds for every later
+      # navigation in the tab and for printing: +media: "screen"+ prints a page with its screen styles
+      # instead of its print stylesheet, +color_scheme: "dark"+ in its dark mode. On a narrow page the
+      # screen media type prints a page's mobile layout: the layout width is the page width minus the
+      # side margins (Chrome's default is 1 cm each), at 96 / 2.54 CSS px per cm - e.g.
+      # +page: { width: 9.525 }, margin: { left: 0, right: 0 }+ lays out at 360 px. Each call replaces
+      # the previous emulation, so a media type or feature it omits is reset; a call without arguments
+      # ends it.
+      #
+      # @param [String, Symbol, nil] media "screen" or "print"; nil leaves it to the browser.
+      # @param [String, Symbol, nil] color_scheme "light" or "dark" (prefers-color-scheme).
+      # @param [String, Symbol, nil] reduced_motion "reduce" or "no-preference" (prefers-reduced-motion).
+      # @raise [ArgumentError] for a value Chrome does not know, before anything is sent.
+      def emulate_media: (?media: untyped?, ?color_scheme: untyped?, ?reduced_motion: untyped?) -> untyped
+
       private
 
+      def emulated_media_params: (**untyped values) -> { media: untyped, features: untyped }
+
+      def check_emulated_media: (untyped name, untyped value) -> (nil | untyped)
+
       def build_command_and_extractor: (untyped print_options) -> ::Array[untyped]
 
       def cdp_session: () -> untyped

data/sig/bidi2pdf/cli.rbs

@@ -1,6 +1,8 @@
 module Bidi2pdf
   # rubocop:disable Metrics/AbcSize
   class CLI < Thor
+    @launcher: untyped
+
     @run_launcher: untyped
 
     @render_input_path: untyped
@@ -9,8 +11,6 @@ module Bidi2pdf
 
     @stdin_tempfile: untyped
 
-    @launcher: untyped
-
     include JsonOutput
 
     include SessionCommands
@@ -55,16 +55,23 @@ module Bidi2pdf
 
     def capture_diagnose_pdf: (untyped tab) -> (nil | { path: untyped, pages: untyped, not_blank: untyped })
 
-    # rubocop:disable-next Metrics/CyclomaticComplexity
     def perform_human_run: (untyped recipe_path) -> untyped
 
-    # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    # rubocop:disable-next Metrics/CyclomaticComplexity
     def perform_structured_run: (untyped recipe_path) -> untyped
 
     def load_and_validate_recipe: (untyped recipe_path) -> untyped
 
     def recipe_requested_url: (untyped recipe) -> untyped
 
+    # Stops whatever browser this command started, once. The structured paths call it inside
+    # reserve_stdout_for_machine_output, while the loggers still write to stderr: stopping logs
+    # ("WebSocket closed"), and after the block those lines would land on stdout behind the JSON
+    # document or the PDF bytes. Each browser is stopped on its own, and a failing stop is logged,
+    # not raised: this runs in an ensure, where raising would replace the command's own result and
+    # exit status.
+    def stop_browsers: () -> untyped
+
     def with_recipe_tab: (untyped recipe) { (untyped) -> untyped } -> untyped
 
     # A failing action/assertion raises Recipe::Runner::StepFailure (its own entries plus the real
@@ -144,6 +151,10 @@ module Bidi2pdf
 
     def launcher: () -> untyped
 
+    # The --media/--color_scheme/--reduced_motion choices for BrowserTab#emulate_media; empty when none
+    # is given, so the browser keeps its own.
+    def emulate_media_options: () -> untyped
+
     def configure: () -> untyped
 
     def log_level: () -> untyped

data/sig/bidi2pdf/launcher.rbs

@@ -29,43 +29,28 @@ module Bidi2pdf
   # @param [Hash] print_options Options for printing the page. Defaults to an empty hash.
   # @param [String, nil] remote_browser_url The URL of a remote browser to connect to. Defaults to nil.
   # @param [Symbol] network_log_format The format for network logs. Defaults to :console.
+  # @param [Hash] emulate_media Media type and features for BrowserTab#emulate_media (media:,
+  #   color_scheme:, reduced_motion:). Defaults to none.
   class Launcher
-    @url: untyped
-
-    @inputfile: untyped
+    # What both runners get, unchanged - SessionRunner's own keyword arguments.
+    @runner_options: untyped
 
     @port: untyped
 
     @headless: untyped
 
-    @output: untyped
-
-    @cookies: untyped
-
-    @headers: untyped
-
-    @auth: untyped
-
     @manager: untyped
 
-    @wait_window_loaded: untyped
-
-    @wait_network_idle: untyped
-
-    @print_options: untyped
-
     @remote_browser_url: untyped
 
     @custom_session: untyped
 
-    @network_log_format: untyped
-
     @chrome_args: untyped
 
     @diagnose_runner: untyped
 
     # rubocop:disable Metrics/ParameterLists
-    def initialize: (url: untyped, inputfile: untyped, output: untyped, cookies: untyped, headers: untyped, auth: untyped, ?headless: bool, ?port: ::Integer, ?wait_window_loaded: bool, ?wait_network_idle: bool, ?print_options: ::Hash[untyped, untyped], ?remote_browser_url: untyped?, ?network_log_format: ::Symbol, ?chrome_args: untyped) -> void
+    def initialize: (url: untyped, inputfile: untyped, output: untyped, cookies: untyped, headers: untyped, auth: untyped, ?headless: bool, ?port: ::Integer, ?wait_window_loaded: bool, ?wait_network_idle: bool, ?print_options: ::Hash[untyped, untyped], ?remote_browser_url: untyped?, ?network_log_format: ::Symbol, ?chrome_args: untyped, ?emulate_media: ::Hash[untyped, untyped]) -> void
 
     def launch: () -> untyped
 

data/sig/bidi2pdf/recipe.rbs

@@ -10,7 +10,7 @@ module Bidi2pdf
 
     KNOWN_TOP_LEVEL_KEYS: ::Array["version" | "source" | "browser" | "headers" | "cookies" | "auth" | "actions" | "assert" | "print" | "output"]
 
-    KNOWN_ACTIONS: ::Array["wait_for" | "click" | "evaluate" | "inject_script" | "inject_style" | "set_viewport" | "wait_network_idle"]
+    KNOWN_ACTIONS: ::Array["wait_for" | "click" | "evaluate" | "inject_script" | "inject_style" | "set_viewport" | "wait_network_idle" | "emulate_media"]
 
     PAGE_ASSERTIONS: ::Array["selector_exists" | "text_present" | "no_console_errors" | "no_network_failures" | "fonts_loaded"]
 

data/sig/bidi2pdf/schema.rbs

@@ -30,7 +30,7 @@ module Bidi2pdf
 
     RECIPE_SOURCE: { "description" => "exactly one of url, file, stdin", "oneOf" => ::Array[{ "type" => "object", "required" => ::Array["url"], "properties" => { "url" => { "type" => "string" } }, "additionalProperties" => false } | { "type" => "object", "required" => ::Array["file"], "properties" => { "file" => { "type" => "string" } }, "additionalProperties" => false } | { "type" => "object", "required" => ::Array["stdin"], "properties" => { "stdin" => { "const" => true } }, "additionalProperties" => false }] }
 
-    RECIPE_ACTIONS: { "description" => "one of the 7 known actions - a thin dispatch over BrowserTab's own methods, see README's Agent and Automation Usage section", "oneOf" => ::Array[{ "type" => "object", "required" => ::Array["wait_for"], "additionalProperties" => false, "properties" => { "wait_for" => { "type" => "object", "description" => "exactly one of selector, paged_js, script; timeout is always optional", "oneOf" => ::Array[{ "type" => "object", "required" => ::Array["selector"], "additionalProperties" => false, "properties" => { "selector" => { "type" => "string" }, "timeout" => { "type" => "number" } } } | { "type" => "object", "required" => ::Array["paged_js"], "additionalProperties" => false, "properties" => { "paged_js" => { "type" => "boolean" }, "timeout" => { "type" => "number" } } } | { "type" => "object", "required" => ::Array["script"], "additionalProperties" => false, "properties" => { "script" => { "type" => "string" }, "timeout" => { "type" => "number" } } }] } } } | { "type" => "object", "required" => ::Array["click"], "additionalProperties" => false, "properties" => { "click" => { "type" => "object", "required" => ::Array["selector"], "additionalProperties" => false, "properties" => { "selector" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["evaluate"], "additionalProperties" => false, "properties" => { "evaluate" => { "type" => "object", "required" => ::Array["script"], "additionalProperties" => false, "properties" => { "script" => { "type" => "string" }, "assign" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["inject_script"], "additionalProperties" => false, "properties" => { "inject_script" => { "type" => "object", "additionalProperties" => false, "properties" => { "url" => { "type" => "string" }, "content" => { "type" => "string" }, "id" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["inject_style"], "additionalProperties" => false, "properties" => { "inject_style" => { "type" => "object", "additionalProperties" => false, "properties" => { "url" => { "type" => "string" }, "content" => { "type" => "string" }, "id" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["set_viewport"], "additionalProperties" => false, "properties" => { "set_viewport" => { "type" => "object", "required" => ::Array["width" | "height"], "additionalProperties" => false, "properties" => { "width" => { "type" => "number" }, "height" => { "type" => "number" }, "device_pixel_ratio" => { "type" => "number" } } } } } | { "type" => "object", "required" => ::Array["wait_network_idle"], "additionalProperties" => false, "properties" => { "wait_network_idle" => { "type" => "object", "additionalProperties" => false, "properties" => { "timeout" => { "type" => "number" } } } } }] }
+    RECIPE_ACTIONS: { "description" => "one of the 8 known actions - a thin dispatch over BrowserTab's own methods, see README's Agent and Automation Usage section", "oneOf" => ::Array[{ "type" => "object", "required" => ::Array["wait_for"], "additionalProperties" => false, "properties" => { "wait_for" => { "type" => "object", "description" => "exactly one of selector, paged_js, script; timeout is always optional", "oneOf" => ::Array[{ "type" => "object", "required" => ::Array["selector"], "additionalProperties" => false, "properties" => { "selector" => { "type" => "string" }, "timeout" => { "type" => "number" } } } | { "type" => "object", "required" => ::Array["paged_js"], "additionalProperties" => false, "properties" => { "paged_js" => { "type" => "boolean" }, "timeout" => { "type" => "number" } } } | { "type" => "object", "required" => ::Array["script"], "additionalProperties" => false, "properties" => { "script" => { "type" => "string" }, "timeout" => { "type" => "number" } } }] } } } | { "type" => "object", "required" => ::Array["click"], "additionalProperties" => false, "properties" => { "click" => { "type" => "object", "required" => ::Array["selector"], "additionalProperties" => false, "properties" => { "selector" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["evaluate"], "additionalProperties" => false, "properties" => { "evaluate" => { "type" => "object", "required" => ::Array["script"], "additionalProperties" => false, "properties" => { "script" => { "type" => "string" }, "assign" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["inject_script"], "additionalProperties" => false, "properties" => { "inject_script" => { "type" => "object", "additionalProperties" => false, "properties" => { "url" => { "type" => "string" }, "content" => { "type" => "string" }, "id" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["inject_style"], "additionalProperties" => false, "properties" => { "inject_style" => { "type" => "object", "additionalProperties" => false, "properties" => { "url" => { "type" => "string" }, "content" => { "type" => "string" }, "id" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["set_viewport"], "additionalProperties" => false, "properties" => { "set_viewport" => { "type" => "object", "required" => ::Array["width" | "height"], "additionalProperties" => false, "properties" => { "width" => { "type" => "number" }, "height" => { "type" => "number" }, "device_pixel_ratio" => { "type" => "number" } } } } } | { "type" => "object", "required" => ::Array["wait_network_idle"], "additionalProperties" => false, "properties" => { "wait_network_idle" => { "type" => "object", "additionalProperties" => false, "properties" => { "timeout" => { "type" => "number" } } } } } | { "type" => "object", "required" => ::Array["emulate_media"], "additionalProperties" => false, "properties" => { "emulate_media" => { "type" => "object", "additionalProperties" => false, "description" => "the CSS media type and media features the page is shown and printed with, from here on; media: screen prints the screen styles; on a narrow print page (layout width = page width minus the side margins, 9.525 cm without side margins = 360 CSS px) the mobile layout", "properties" => untyped } } }] }
 
     RECIPE_ASSERT: { "description" => "one of the 8 known assertions. The presence-only ones (no_console_errors, no_network_failures, fonts_loaded, pdf_not_blank) never have their value read at run time - Recipe::Runner only checks the key is there - so they must be written as `true`; `false` or any other value is rejected as misleading rather than silently ignored. The last 3 assertions also require the pdf-reader gem at --validate time - a runtime fact this schema cannot express, see the top-level description", "oneOf" => ::Array[{ "type" => "object", "required" => ::Array["selector_exists"], "additionalProperties" => false, "properties" => { "selector_exists" => { "type" => "object", "required" => ::Array["selector"], "additionalProperties" => false, "properties" => { "selector" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["text_present"], "additionalProperties" => false, "properties" => { "text_present" => { "type" => "object", "required" => ::Array["text"], "additionalProperties" => false, "properties" => { "text" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["no_console_errors"], "additionalProperties" => false, "properties" => { "no_console_errors" => { "const" => true } } } | { "type" => "object", "required" => ::Array["no_network_failures"], "additionalProperties" => false, "properties" => { "no_network_failures" => { "const" => true } } } | { "type" => "object", "required" => ::Array["fonts_loaded"], "additionalProperties" => false, "properties" => { "fonts_loaded" => { "const" => true } } } | { "type" => "object", "required" => ::Array["page_count"], "additionalProperties" => false, "properties" => { "page_count" => { "oneOf" => ::Array[{ "type" => "integer" } | { "type" => "object", "properties" => { "min" => { "type" => "integer" }, "max" => { "type" => "integer" } }, "additionalProperties" => false }] } } } | { "type" => "object", "required" => ::Array["pdf_text_present"], "additionalProperties" => false, "properties" => { "pdf_text_present" => { "type" => "object", "required" => ::Array["text"], "additionalProperties" => false, "properties" => { "text" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["pdf_not_blank"], "additionalProperties" => false, "properties" => { "pdf_not_blank" => { "const" => true } } }] }
 

data/sig/bidi2pdf/session_runner.rbs

@@ -31,6 +31,8 @@ module Bidi2pdf
   # @param [Boolean] wait_network_idle Whether to wait for the network to become idle. Defaults to false.
   # @param [Hash] print_options Options for printing the page. Defaults to an empty hash.
   # @param [Symbol] network_log_format The format for network logs. Defaults to :console.
+  # @param [Hash] emulate_media Media type and features for BrowserTab#emulate_media (media:,
+  #   color_scheme:, reduced_motion:), applied before navigating. Defaults to none.
   class SessionRunner
     @session: untyped
 
@@ -54,6 +56,8 @@ module Bidi2pdf
 
     @network_log_format: untyped
 
+    @emulate_media: untyped
+
     @window: untyped
 
     @tab: untyped
@@ -63,7 +67,7 @@ module Bidi2pdf
     @uri: untyped
 
     # rubocop: disable Metrics/ParameterLists
-    def initialize: (session: untyped, url: untyped, inputfile: untyped, output: untyped, ?cookies: ::Hash[untyped, untyped], ?headers: ::Hash[untyped, untyped], ?auth: ::Hash[untyped, untyped], ?wait_window_loaded: bool, ?wait_network_idle: bool, ?print_options: ::Hash[untyped, untyped], ?network_log_format: ::Symbol) -> void
+    def initialize: (session: untyped, url: untyped, inputfile: untyped, output: untyped, ?cookies: ::Hash[untyped, untyped], ?headers: ::Hash[untyped, untyped], ?auth: ::Hash[untyped, untyped], ?wait_window_loaded: bool, ?wait_network_idle: bool, ?print_options: ::Hash[untyped, untyped], ?network_log_format: ::Symbol, ?emulate_media: ::Hash[untyped, untyped]) -> void
 
     def run: () -> untyped
 

data/sig/bidi2pdf/version.rbs

@@ -1,3 +1,3 @@
 module Bidi2pdf
-  VERSION: "0.1.22"
+  VERSION: "0.1.23"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bidi2pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.22
+  version: 0.1.23
 platform: ruby
 authors:
 - Dieter S.