bidi2pdf 0.1.14 → 0.1.16

data/lib/bidi2pdf/result.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bidi2pdf
+  # Structured result of a CLI command (render/diagnose/run) - the shape behind --json output, a
+  # render manifest, and the final "result" event of --json-stream. Construct via .success/
+  # .failure rather than .new directly so every Result is unambiguously one or the other.
+  class Result
+    SCHEMA_VERSION = 1
+
+    attr_reader :command, :output, :bytes, :sha256, :pages, :duration_ms, :navigation,
+                :console, :network_failures, :warnings, :error, :metadata
+
+    # rubocop:disable-next Metrics/ParameterLists, Naming/MethodParameterName
+    def initialize(command:, ok:, output: nil, bytes: nil, sha256: nil, pages: nil, duration_ms: nil,
+                   navigation: nil, console: [], network_failures: [], warnings: [], error: nil, metadata: {})
+      @command = command
+      @ok = ok
+      @output = output
+      @bytes = bytes
+      @sha256 = sha256
+      @pages = pages
+      @duration_ms = duration_ms
+      @navigation = navigation
+      @console = console
+      @network_failures = network_failures
+      @warnings = warnings
+      @error = error
+      @metadata = metadata
+    end
+
+    def self.success(**)
+      new(ok: true, **)
+    end
+
+    def self.failure(error:, **)
+      new(ok: false, error: error, **)
+    end
+
+    def ok? = @ok
+
+    def to_h
+      base = {
+        schema_version: SCHEMA_VERSION,
+        ok: ok?,
+        command: command,
+        output: output,
+        bytes: bytes,
+        sha256: sha256,
+        pages: pages,
+        duration_ms: duration_ms,
+        navigation: navigation,
+        console: console,
+        network_failures: network_failures,
+        warnings: warnings,
+        error: error
+      }
+
+      metadata.empty? ? base : base.merge(metadata: metadata)
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+  end
+end

data/lib/bidi2pdf/result_collector.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "digest"
+require "base64"
+
+module Bidi2pdf
+  # Builds a Bidi2pdf::Result by subscribing to the gem's own instrumentation events
+  # (Bidi2pdf::Notifications) around a block that does the actual rendering, rather than changing
+  # what Launcher/SessionRunner/BrowserTab return - Launcher#launch keeps returning the raw base64
+  # PDF when no output file is given, exactly as the programmatic API already promises (see
+  # spec/acceptance/launcher_spec.rb).
+  class ResultCollector
+    # #pdf_bytes is the raw, decoded PDF (nil if nothing was printed) - not part of Result#to_h
+    # (which only carries bytesize/sha256/pages), but what a stdout-output render (--output -)
+    # writes to $stdout, and what a caller can hand to Bidi2pdf::PdfInspection itself.
+    #
+    # #console/#network_failures are exposed live (not only via the Result #around eventually
+    # returns) so a caller running inside the block - Recipe::Runner's assertions - can read them
+    # before the block itself finishes.
+    attr_reader :requested_url, :navigation_event, :pdf_bytes, :console
+
+    def initialize(requested_url:, command:, output: nil)
+      @requested_url = requested_url
+      @command = command
+      @output = output
+      @console = []
+      @network_events = {}
+      @pdf_bytes = nil
+    end
+
+    # Runs the block with the collector subscribed, then returns a Bidi2pdf::Result - success with
+    # whatever was captured, or failure describing whatever the block raised. Never itself raises.
+    def around
+      subscribe
+      start = now_ms
+
+      begin
+        yield
+        build_result(ok: true, duration_ms: elapsed_ms(start))
+      rescue StandardError => e
+        build_result(ok: false, duration_ms: elapsed_ms(start), error: e)
+      end
+    ensure
+      unsubscribe
+    end
+
+    def network_failures
+      @network_events.values
+                     .select { |event| event.state == "error" || (event.http_status_code && event.http_status_code >= 400) }
+                     .map { |event| { url: event.url, method: event.http_method, status: event.http_status_code, state: event.state } }
+    end
+
+    private
+
+    def now_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+
+    def elapsed_ms(start) = (now_ms - start).round
+
+    def subscribe
+      handlers = {
+        "navigate_to.bidi2pdf" => method(:on_navigate),
+        "render_html_content.bidi2pdf" => method(:on_navigate),
+        "browser_console_log_received.bidi2pdf" => method(:on_console),
+        "network_event_received.bidi2pdf" => method(:on_network_event),
+        "print.bidi2pdf" => method(:on_print)
+      }
+
+      # Capture the Proc #subscribe actually stored (it converts &handler into one), so
+      # #unsubscribe below can remove exactly this registration - passing the handler positionally
+      # rather than as a second &block, since Notifications#unsubscribe(pattern, block = nil)
+      # clears *every* subscriber for that pattern when block is nil/omitted.
+      @registered = handlers.map { |pattern, handler| [pattern, Bidi2pdf.notification_service.subscribe(pattern, &handler)] }
+    end
+
+    def unsubscribe
+      Array(@registered).each { |pattern, block| Bidi2pdf.notification_service.unsubscribe(pattern, block) }
+    end
+
+    # Kept for its #duration (used by Manifest's navigation.duration_ms); Result itself doesn't
+    # surface navigation timing separately from the overall duration_ms.
+    def on_navigate(event)
+      @navigation_event = event
+    end
+
+    def on_console(event)
+      payload = event.payload
+      @console << { level: payload[:level], text: payload[:text] }
+    end
+
+    def on_network_event(event)
+      network_event = event.payload[:event]
+      return unless network_event
+
+      @network_events[network_event.id] = network_event
+    end
+
+    def on_print(event)
+      pdf_base64 = event.payload[:pdf_base64]
+      @pdf_bytes = pdf_base64 ? Base64.decode64(pdf_base64) : nil
+    end
+
+    # rubocop:disable-next Naming/MethodParameterName
+    def build_result(ok:, duration_ms:, error: nil)
+      Result.new(
+        command: @command,
+        ok: ok,
+        output: @output,
+        bytes: pdf_bytes&.bytesize,
+        sha256: pdf_bytes ? Digest::SHA256.hexdigest(pdf_bytes) : nil,
+        pages: PdfInspection.page_count(pdf_bytes),
+        duration_ms: duration_ms,
+        navigation: navigation_info,
+        console: @console,
+        network_failures: network_failures,
+        warnings: warnings,
+        error: ok ? nil : ErrorCodes.describe(error)
+      )
+    end
+
+    def navigation_info
+      final = final_navigation_event
+
+      {
+        requested_url: requested_url,
+        final_url: final&.url || requested_url,
+        status: final&.http_status_code
+      }
+    end
+
+    # Best-effort external approximation of what BrowserTab#send(:correlated_navigation_response)
+    # already computes internally (not exposed publicly): among the network events this collector
+    # observed, the ones carrying a real BiDi "navigation" id are main-frame document requests: the
+    # one with the latest start_timestamp among those sharing the most recent such navigation id is
+    # the final hop of that navigation, and its own #url is therefore the page actually reached.
+    def final_navigation_event
+      candidates = @network_events.values.select { |event| event.navigation && event.http_status_code }
+      return nil if candidates.empty?
+
+      winning_navigation = candidates.max_by(&:start_timestamp).navigation
+      candidates.select { |event| event.navigation == winning_navigation }.max_by(&:start_timestamp)
+    end
+
+    def warnings
+      return [] unless pdf_bytes
+      return [] if PdfInspection.available?
+
+      ["pages requires the pdf-reader gem"]
+    end
+  end
+end

data/lib/bidi2pdf/schema.rb

@@ -0,0 +1,382 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  # JSON Schema documents behind `bidi2pdf schema <kind>` - how an agent discovers the shape of
+  # --json/--manifest/--json-stream/a recipe file without reading prose documentation. These are
+  # the source of truth for those shapes; a change to Result/Diagnose's payload/Recipe::Runner's
+  # result shape/Manifest/JsonSubscriber/Recipe's own fields should update the matching schema
+  # here in the same change. Kind names match the `command` field a response already carries
+  # (`"command": "diagnose"` -> `bidi2pdf schema diagnose`), not the Ruby class names behind them.
+  module Schema # rubocop:disable Metrics/ModuleLength
+    ERROR = {
+      "type" => %w[object null],
+      "required" => %w[code message retryable],
+      "properties" => {
+        "code" => { "type" => "string" },
+        "message" => { "type" => "string" },
+        "retryable" => { "type" => "boolean" },
+        "hint" => { "type" => %w[string null] },
+        "details" => { "type" => "object" }
+      }
+    }.freeze
+
+    NAVIGATION = {
+      "type" => %w[object null],
+      "properties" => {
+        "requested_url" => { "type" => %w[string null] },
+        "final_url" => { "type" => %w[string null] },
+        "status" => { "type" => %w[integer null] }
+      }
+    }.freeze
+
+    CONSOLE = {
+      "type" => "array",
+      "items" => { "type" => "object", "properties" => { "level" => { "type" => "string" }, "text" => { "type" => "string" } } }
+    }.freeze
+
+    NETWORK_FAILURES = {
+      "type" => "array",
+      "items" => {
+        "type" => "object",
+        "properties" => {
+          "url" => { "type" => "string" },
+          "method" => { "type" => %w[string null] },
+          "status" => { "type" => %w[integer null] },
+          "state" => { "type" => "string" }
+        }
+      }
+    }.freeze
+
+    WARNINGS = { "type" => "array", "items" => { "type" => "string" } }.freeze
+
+    RENDER = {
+      "$schema" => "https://json-schema.org/draft/2020-12/schema",
+      "title" => "Bidi2pdf::Result (render)",
+      "description" => "--json output of `bidi2pdf render`, and the final \"result\" event of its --json-stream",
+      "type" => "object",
+      "required" => %w[schema_version ok command console network_failures warnings],
+      "properties" => {
+        "schema_version" => { "const" => 1 },
+        "ok" => { "type" => "boolean" },
+        "command" => { "const" => "render" },
+        "output" => { "type" => %w[string null] },
+        "bytes" => { "type" => %w[integer null] },
+        "sha256" => { "type" => %w[string null] },
+        "pages" => { "type" => %w[integer null], "description" => "null when the pdf-reader gem is unavailable" },
+        "duration_ms" => { "type" => %w[integer null] },
+        "navigation" => NAVIGATION,
+        "console" => CONSOLE,
+        "network_failures" => NETWORK_FAILURES,
+        "warnings" => WARNINGS,
+        "error" => ERROR
+      }
+    }.freeze
+
+    DIAGNOSE = {
+      "$schema" => "https://json-schema.org/draft/2020-12/schema",
+      "title" => "bidi2pdf diagnose result",
+      "description" => "--json output of `bidi2pdf diagnose`, and the final \"result\" event of its --json-stream. " \
+                        "page/fonts/print_media/paged_js are Bidi2pdf::Diagnose's own parsed script results, loosely " \
+                        "shaped here rather than over-specified.",
+      "type" => "object",
+      "required" => %w[schema_version ok command console network_failures warnings],
+      "properties" => {
+        "schema_version" => { "const" => 1 },
+        "ok" => { "type" => "boolean" },
+        "command" => { "const" => "diagnose" },
+        "page" => { "type" => %w[object null] },
+        "console" => CONSOLE,
+        "network_failures" => NETWORK_FAILURES,
+        "fonts" => { "type" => %w[object null] },
+        "print_media" => { "type" => %w[object null] },
+        "paged_js" => { "type" => %w[object null] },
+        "screenshot" => { "type" => %w[string null], "description" => "path written, when --screenshot was given" },
+        "pdf" => {
+          "type" => %w[object null],
+          "description" => "present when --pdf was given",
+          "properties" => {
+            "path" => { "type" => "string" },
+            "pages" => { "type" => %w[integer null] },
+            "not_blank" => { "type" => %w[boolean null] }
+          }
+        },
+        "warnings" => WARNINGS,
+        "error" => ERROR
+      }
+    }.freeze
+
+    RUN_STEP = {
+      "type" => "object",
+      "required" => %w[index type ok],
+      "properties" => {
+        "index" => { "type" => "integer" },
+        "type" => { "type" => "string" },
+        "ok" => { "type" => "boolean" },
+        "duration_ms" => { "type" => "integer" },
+        "details" => { "type" => "object" }
+      }
+    }.freeze
+
+    RUN = {
+      "$schema" => "https://json-schema.org/draft/2020-12/schema",
+      "title" => "bidi2pdf run result",
+      "description" => "--json output of `bidi2pdf run recipe.yml`, and the final \"result\" event of its --json-stream",
+      "type" => "object",
+      "required" => %w[schema_version ok command recipe actions assertions warnings],
+      "properties" => {
+        "schema_version" => { "const" => 1 },
+        "ok" => { "type" => "boolean" },
+        "command" => { "const" => "run" },
+        "recipe" => { "type" => "string", "description" => "the recipe file path given on the command line" },
+        "actions" => { "type" => "array", "items" => RUN_STEP },
+        "assertions" => { "type" => "array", "items" => RUN_STEP },
+        "assigned" => { "type" => "object", "description" => "values captured by evaluate ... assign:, keyed by name" },
+        "output" => {
+          "type" => %w[object null],
+          "description" => "null when the run failed",
+          "properties" => {
+            "pdf" => { "type" => %w[string null] },
+            "manifest" => { "type" => %w[string null] },
+            "screenshot" => { "type" => %w[string null] },
+            "bytes" => { "type" => %w[integer null] },
+            "sha256" => { "type" => %w[string null] },
+            "pages" => { "type" => %w[integer null] }
+          }
+        },
+        "duration_ms" => { "type" => %w[integer null] },
+        "warnings" => WARNINGS,
+        "error" => ERROR
+      }
+    }.freeze
+
+    MANIFEST = {
+      "$schema" => "https://json-schema.org/draft/2020-12/schema",
+      "title" => "Bidi2pdf render manifest",
+      "description" => "--manifest FILE output",
+      "type" => "object",
+      "required" => %w[schema_version bidi2pdf_version created_at input output navigation render],
+      "properties" => {
+        "schema_version" => { "const" => 1 },
+        "bidi2pdf_version" => { "type" => "string" },
+        "created_at" => { "type" => "string", "format" => "date-time" },
+        "input" => {
+          "type" => "object",
+          "required" => %w[type],
+          "properties" => { "type" => { "type" => "string", "enum" => %w[url html_file stdin] }, "url" => { "type" => %w[string null] } }
+        },
+        "output" => {
+          "type" => "object",
+          "properties" => {
+            "path" => { "type" => %w[string null] },
+            "pages" => { "type" => %w[integer null] },
+            "bytes" => { "type" => %w[integer null] },
+            "sha256" => { "type" => %w[string null] }
+          }
+        },
+        "browser" => { "type" => "object" },
+        "navigation" => NAVIGATION,
+        "render" => { "type" => "object", "properties" => { "duration_ms" => { "type" => %w[integer null] } } },
+        "console" => CONSOLE,
+        "network_failures" => NETWORK_FAILURES,
+        "warnings" => WARNINGS,
+        "headers" => { "type" => "object", "description" => "present only when custom headers were given; secret-bearing values are redacted" }
+      }
+    }.freeze
+
+    EVENT = {
+      "$schema" => "https://json-schema.org/draft/2020-12/schema",
+      "title" => "Bidi2pdf --json-stream event",
+      "description" => "one JSON object per stderr line while --json-stream is active. In structured mode (--json/" \
+                        "--output -), the last line is always {event: \"result\", result: <the matching command's " \
+                        "own schema - see \"result\"'s own oneOf>}. In human mode (--json-stream given alone), only " \
+                        "progress events are emitted - there is no synthetic final \"result\" event, since there is " \
+                        "no structured result being built; the human-readable log is the completion/failure signal.",
+      "type" => "object",
+      "required" => %w[schema_version t_ms event],
+      "properties" => {
+        "schema_version" => { "const" => 1 },
+        "t_ms" => { "type" => "integer", "description" => "milliseconds since the render started" },
+        "event" => { "type" => "string", "enum" => %w[navigate page_loaded network_idle console print screenshot result] },
+        "url" => { "type" => "string", "description" => "present on a navigate event" },
+        "level" => { "type" => "string", "description" => "present on a console event" },
+        "text" => { "type" => "string", "description" => "present on a console event" },
+        "result" => {
+          "description" => "present only on the final \"result\" event (structured mode only); shape depends on which " \
+                            "command produced this stream - each branch's own \"command\" value disambiguates",
+          "oneOf" => [RENDER, DIAGNOSE, RUN]
+        }
+      }
+    }.freeze
+
+    RECIPE_SOURCE = {
+      "description" => "exactly one of url, file, stdin",
+      "oneOf" => [
+        { "type" => "object", "required" => %w[url], "properties" => { "url" => { "type" => "string" } }, "additionalProperties" => false },
+        { "type" => "object", "required" => %w[file], "properties" => { "file" => { "type" => "string" } }, "additionalProperties" => false },
+        { "type" => "object", "required" => %w[stdin], "properties" => { "stdin" => { "const" => true } }, "additionalProperties" => false }
+      ]
+    }.freeze
+
+    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" => [
+        {
+          "type" => "object", "required" => %w[wait_for], "additionalProperties" => false,
+          "properties" => {
+            "wait_for" => {
+              "type" => "object",
+              "description" => "exactly one of selector, paged_js, script; timeout is always optional",
+              "oneOf" => [
+                { "type" => "object", "required" => %w[selector], "additionalProperties" => false,
+                  "properties" => { "selector" => { "type" => "string" }, "timeout" => { "type" => "number" } } },
+                { "type" => "object", "required" => %w[paged_js], "additionalProperties" => false,
+                  "properties" => { "paged_js" => { "type" => "boolean" }, "timeout" => { "type" => "number" } } },
+                { "type" => "object", "required" => %w[script], "additionalProperties" => false,
+                  "properties" => { "script" => { "type" => "string" }, "timeout" => { "type" => "number" } } }
+              ]
+            }
+          }
+        },
+        {
+          "type" => "object", "required" => %w[click], "additionalProperties" => false,
+          "properties" => { "click" => { "type" => "object", "required" => %w[selector], "additionalProperties" => false,
+                                         "properties" => { "selector" => { "type" => "string" } } } }
+        },
+        {
+          "type" => "object", "required" => %w[evaluate], "additionalProperties" => false,
+          "properties" => { "evaluate" => { "type" => "object", "required" => %w[script], "additionalProperties" => false,
+                                            "properties" => { "script" => { "type" => "string" }, "assign" => { "type" => "string" } } } }
+        },
+        {
+          "type" => "object", "required" => %w[inject_script], "additionalProperties" => false,
+          "properties" => { "inject_script" => { "type" => "object", "additionalProperties" => false,
+                                                 "properties" => { "url" => { "type" => "string" }, "content" => { "type" => "string" },
+                                                                   "id" => { "type" => "string" } } } }
+        },
+        {
+          "type" => "object", "required" => %w[inject_style], "additionalProperties" => false,
+          "properties" => { "inject_style" => { "type" => "object", "additionalProperties" => false,
+                                                "properties" => { "url" => { "type" => "string" }, "content" => { "type" => "string" },
+                                                                  "id" => { "type" => "string" } } } }
+        },
+        {
+          "type" => "object", "required" => %w[set_viewport], "additionalProperties" => false,
+          "properties" => { "set_viewport" => { "type" => "object", "required" => %w[width height], "additionalProperties" => false,
+                                                "properties" => { "width" => { "type" => "number" }, "height" => { "type" => "number" },
+                                                                  "device_pixel_ratio" => { "type" => "number" } } } }
+        },
+        {
+          "type" => "object", "required" => %w[wait_network_idle], "additionalProperties" => false,
+          "properties" => { "wait_network_idle" => { "type" => "object", "additionalProperties" => false,
+                                                     "properties" => { "timeout" => { "type" => "number" } } } }
+        }
+      ]
+    }.freeze
+
+    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" => [
+        {
+          "type" => "object", "required" => %w[selector_exists], "additionalProperties" => false,
+          "properties" => { "selector_exists" => { "type" => "object", "required" => %w[selector], "additionalProperties" => false,
+                                                   "properties" => { "selector" => { "type" => "string" } } } }
+        },
+        {
+          "type" => "object", "required" => %w[text_present], "additionalProperties" => false,
+          "properties" => { "text_present" => { "type" => "object", "required" => %w[text], "additionalProperties" => false,
+                                                "properties" => { "text" => { "type" => "string" } } } }
+        },
+        { "type" => "object", "required" => %w[no_console_errors], "additionalProperties" => false,
+          "properties" => { "no_console_errors" => { "const" => true } } },
+        { "type" => "object", "required" => %w[no_network_failures], "additionalProperties" => false,
+          "properties" => { "no_network_failures" => { "const" => true } } },
+        { "type" => "object", "required" => %w[fonts_loaded], "additionalProperties" => false,
+          "properties" => { "fonts_loaded" => { "const" => true } } },
+        {
+          "type" => "object", "required" => %w[page_count], "additionalProperties" => false,
+          "properties" => {
+            "page_count" => {
+              "oneOf" => [
+                { "type" => "integer" },
+                { "type" => "object", "properties" => { "min" => { "type" => "integer" }, "max" => { "type" => "integer" } },
+                  "additionalProperties" => false }
+              ]
+            }
+          }
+        },
+        {
+          "type" => "object", "required" => %w[pdf_text_present], "additionalProperties" => false,
+          "properties" => { "pdf_text_present" => { "type" => "object", "required" => %w[text], "additionalProperties" => false,
+                                                    "properties" => { "text" => { "type" => "string" } } } }
+        },
+        { "type" => "object", "required" => %w[pdf_not_blank], "additionalProperties" => false,
+          "properties" => { "pdf_not_blank" => { "const" => true } } }
+      ]
+    }.freeze
+
+    RECIPE_PRINT = {
+      "type" => "object",
+      "description" => "the same options `bidi2pdf render`'s own print flags map to; validated by " \
+                        "Bidi::Commands::PrintParametersValidator",
+      "properties" => {
+        "background" => { "type" => "boolean" },
+        "shrinkToFit" => { "type" => "boolean" },
+        "orientation" => { "type" => "string", "enum" => %w[portrait landscape] },
+        "scale" => { "type" => "number", "minimum" => 0.1, "maximum" => 2.0 },
+        "pageRanges" => { "type" => "array", "items" => { "type" => %w[integer string] } },
+        "margin" => {
+          "type" => "object",
+          "properties" => { "top" => { "type" => "number", "minimum" => 0 }, "bottom" => { "type" => "number", "minimum" => 0 },
+                            "left" => { "type" => "number", "minimum" => 0 }, "right" => { "type" => "number", "minimum" => 0 } }
+        },
+        "page" => {
+          "type" => "object",
+          "properties" => { "format" => { "type" => "string" }, "width" => { "type" => "number", "minimum" => 0.0352 },
+                            "height" => { "type" => "number", "minimum" => 0.0352 } }
+        }
+      }
+    }.freeze
+
+    RECIPE = {
+      "$schema" => "https://json-schema.org/draft/2020-12/schema",
+      "title" => "Bidi2pdf recipe",
+      "description" => "input to `bidi2pdf run recipe.yml` (YAML or JSON). This schema is meant to be sufficient on " \
+                        "its own to generate a recipe `--validate` will accept, with one exception JSON Schema cannot " \
+                        "express: a page_count/pdf_text_present/pdf_not_blank assertion also requires the pdf-reader " \
+                        "gem to be installed at validation time (a runtime environment fact, not a document-shape " \
+                        "one) - `--validate` still catches a violation, with error code PDF_INSPECTION_UNAVAILABLE.",
+      "type" => "object",
+      "required" => %w[version source output],
+      "additionalProperties" => false,
+      "properties" => {
+        "version" => { "const" => 1 },
+        "source" => RECIPE_SOURCE,
+        "browser" => { "type" => "object", "properties" => { "headless" => { "type" => "boolean" } } },
+        "headers" => { "type" => "object" },
+        "cookies" => { "type" => "object" },
+        "auth" => { "type" => "object", "properties" => { "username" => { "type" => "string" }, "password" => { "type" => "string" } } },
+        "actions" => { "type" => "array", "items" => RECIPE_ACTIONS },
+        "assert" => { "type" => "array", "items" => RECIPE_ASSERT },
+        "print" => RECIPE_PRINT,
+        "output" => {
+          "type" => "object",
+          "description" => "at least one of pdf, manifest, screenshot",
+          "anyOf" => [{ "required" => %w[pdf] }, { "required" => %w[manifest] }, { "required" => %w[screenshot] }],
+          "properties" => { "pdf" => { "type" => "string" }, "manifest" => { "type" => "string" }, "screenshot" => { "type" => "string" } }
+        }
+      }
+    }.freeze
+
+    ALL = { "render" => RENDER, "diagnose" => DIAGNOSE, "run" => RUN, "manifest" => MANIFEST, "recipe" => RECIPE, "event" => EVENT }.freeze
+
+    def self.for(kind)
+      ALL.fetch(kind.to_s) { raise ArgumentError, "Unknown schema '#{kind}' - known: #{ALL.keys.join(", ")}" }
+    end
+  end
+end

data/lib/bidi2pdf/session_runner.rb

@@ -60,6 +60,29 @@ module Bidi2pdf
       run_flow
     end
 
+    # Like #run, but stops after navigation (and the configured waits) instead of printing, and
+    # leaves the tab open for the caller to inspect - used by `bidi2pdf diagnose`, which has no PDF
+    # to produce. The caller is responsible for #close_all once done.
+    #
+    # @return [Bidi2pdf::Bidi::BrowserTab] the navigated tab.
+    def run_diagnose
+      @session.start
+      @session.client.on_close { Bidi2pdf.logger.info "WebSocket closed" }
+
+      setup_browser
+      navigate_and_wait
+
+      @tab
+    end
+
+    # Closes what #run_diagnose opened. #run's own run_flow already does this itself (in its
+    # ensure), so this is only ever needed after #run_diagnose.
+    def close_all
+      @tab&.close
+      @window&.close
+      @user_context&.close
+    end
+
     private
 
     def setup_browser
@@ -109,6 +132,25 @@ module Bidi2pdf
       )
     end
 
+    # Navigate + wait only, no log_network_traffic/print side effects - #run_flow above
+    # intentionally keeps its own inline sequence (where log_network_traffic sits between the two
+    # waits) untouched rather than sharing this, since that render-only file-writing side effect
+    # has no place in a diagnose flow.
+    def navigate_and_wait
+      @session.status
+      @session.user_contexts
+
+      if @url
+        @tab.navigate_to(@url)
+      else
+        Bidi2pdf.logger.info "Loading HTML file #{@inputfile}"
+        @tab.render_html_content(File.read(@inputfile))
+      end
+
+      @tab.wait_until_network_idle if @wait_network_idle
+      @tab.wait_until_page_loaded if @wait_window_loaded
+    end
+
     # rubocop: disable Metrics/AbcSize
     def run_flow
       @session.status