bidi2pdf 0.1.14 → 0.1.16

data/sig/bidi2pdf/bidi/client.rbs

@@ -40,14 +40,22 @@ module Bidi2pdf
 
       # Starts the WebSocket client and establishes a connection.
       #
-      # @return [WebSocket::Client::Simple] The WebSocket connection object.
+      # @return [BufferedWebSocketClient] The WebSocket connection object.
       def start: () -> untyped
 
-      # Checks if the WebSocket client has started.
+      # Checks if the WebSocket client has started. Unlike #open?, this never flips back to false on
+      # its own if the connection dies externally - it only reflects whether #start has run.
       #
       # @return [Boolean] True if the client has started, false otherwise.
       def started?: () -> untyped
 
+      # Checks if the underlying WebSocket connection is actually open right now - false before
+      # #start, after #close, or if the reader thread noticed the connection died on its own (a
+      # real liveness signal, not just an internal "did we ever start" flag).
+      #
+      # @return [Boolean] True if the underlying socket reports itself open.
+      def open?: () -> untyped
+
       # Waits until the WebSocket connection is open.
       #
       # @param [Integer] timeout The timeout duration in seconds.

data/sig/bidi2pdf/bidi/network_event.rbs

@@ -15,6 +15,8 @@ module Bidi2pdf
 
       @http_method: untyped
 
+      @navigation: untyped
+
       @end_timestamp: untyped
 
       @bytes_received: untyped
@@ -37,9 +39,17 @@ module Bidi2pdf
 
       attr_reader bytes_received: untyped
 
+      attr_reader navigation: untyped
+
       STATE_MAP: { "network.responseStarted" => "started", "network.responseCompleted" => "completed", "network.fetchError" => "error" }
 
-      def initialize: (id: untyped, url: untyped, timestamp: untyped, timing: untyped, state: untyped, ?http_status_code: untyped?, ?http_method: untyped?) -> void
+      # @param [String, nil] navigation The BiDi navigation ID this request belongs to - present on
+      #   the main-frame document request, letting a caller correlate a specific
+      #   browsingContext.navigate call to the network event carrying its actual HTTP status. A
+      #   sub-resource request (an image, a script, ...) has no real BiDi navigation ID and stays
+      #   nil here - #id already distinguishes one event from another in logs, so this field is
+      #   left alone rather than filled with a value the protocol never sent.
+      def initialize: (id: untyped, url: untyped, timestamp: untyped, timing: untyped, state: untyped, ?http_status_code: untyped?, ?http_method: untyped?, ?navigation: untyped?) -> void
 
       def update_state: (untyped new_state, ?timestamp: untyped?, ?timing: untyped?, ?http_status_code: untyped?, ?bytes_received: untyped?) -> untyped
 

data/sig/bidi2pdf/bidi/session.rbs

@@ -37,7 +37,7 @@ module Bidi2pdf
       SUBSCRIBE_EVENTS: ::Array["script"]
 
       # Default Chrome arguments for the session.
-      DEFAULT_CHROME_ARGS: ::Array["--allow-pre-commit-input" | "--disable-dev-shm-usage" | "--disable-gpu" | "--disable-popup-blocking" | "--disable-hang-monitor" | "--disable-background-networking" | "--disable-background-timer-throttling" | "--disable-client-side-phishing-detection" | "--disable-component-extensions-with-background-pages" | "--disable-crash-reporter" | "--disable-default-apps" | "--disable-infobars" | "--disable-ipc-flooding-protection" | "--disable-prompt-on-repost" | "--disable-renderer-backgrounding" | "--disable-search-engine-choice-screen" | "--disable-sync" | "--enable-automation" | "--export-tagged-pdf" | "--force-color-profile=srgb" | "--generate-pdf-document-outline" | "--metrics-recording-only" | "--no-first-run" | "--password-store=basic" | "--use-mock-keychain" | "--disable-backgrounding-occluded-windows" | "--disable-breakpad" | "--enable-features=PdfOopif" | "--disable-features=Translate,AcceptCHFrame,MediaRouter,OptimizationHints,ProcessPerSiteUpToMainFrameThreshold,IsolateSandboxedIframes" | "--disable-extensions about:blank"]
+      DEFAULT_CHROME_ARGS: ::Array["--allow-pre-commit-input" | "--disable-dev-shm-usage" | "--disable-gpu" | "--disable-popup-blocking" | "--disable-hang-monitor" | "--disable-background-networking" | "--disable-background-timer-throttling" | "--disable-client-side-phishing-detection" | "--disable-component-extensions-with-background-pages" | "--disable-crash-reporter" | "--disable-default-apps" | "--disable-infobars" | "--disable-ipc-flooding-protection" | "--disable-prompt-on-repost" | "--disable-renderer-backgrounding" | "--disable-search-engine-choice-screen" | "--disable-sync" | "--enable-automation" | "--export-tagged-pdf" | "--force-color-profile=srgb" | "--generate-pdf-document-outline" | "--metrics-recording-only" | "--no-first-run" | "--password-store=basic" | "--use-mock-keychain" | "--disable-backgrounding-occluded-windows" | "--disable-breakpad" | "--enable-features=PdfOopif" | "--disable-features=Translate,AcceptCHFrame,MediaRouter,OptimizationHints,ProcessPerSiteUpToMainFrameThreshold,IsolateSandboxedIframes" | "--disable-extensions"]
 
       # @return [URI] The URI of the session.
       attr_reader session_uri: untyped

data/sig/bidi2pdf/chromedriver_manager.rbs

@@ -59,6 +59,10 @@ module Bidi2pdf
 
     def build_cmd: () -> untyped
 
+    # Chromedriver's own internal log verbosity is independent from this app's - defaults to
+    # mirroring Bidi2pdf.logger.level for backward compatibility, but Bidi2pdf.chromedriver_log_level
+    # lets a consumer quiet chromedriver's own (often much more verbose, e.g. full BiDi command/
+    # response dumps at its own INFO level) output without changing their app's own log level.
     def chromedriver_log_level: () -> untyped
 
     def user_data_dir_arg: () -> (untyped | ::String)

data/sig/bidi2pdf/cli/json_output.rbs

@@ -0,0 +1,19 @@
+module Bidi2pdf
+  class CLI < Thor
+    # Shared machinery for --json/--json-stream/--output - across render/diagnose/run: reserving
+    # stdout for exactly one machine-readable payload, and mapping a Result to a process exit
+    # status.
+    module JsonOutput
+      private
+
+      # Bidi2pdf.logger (and friends) default to $stdout (see lib/bidi2pdf.rb), so a
+      # --json/--output - render has to redirect them for its duration or every log line would
+      # land in the same stream as the JSON document / PDF bytes it is trying to keep pure.
+      # Logger#reopen swaps the destination in place, so nothing else holding a reference to
+      # these loggers needs to know.
+      def reserve_stdout_for_machine_output: () { () -> untyped } -> untyped
+
+      def exit_for_result: (untyped result) -> untyped
+    end
+  end
+end

data/sig/bidi2pdf/cli.rbs

@@ -1,21 +1,131 @@
 module Bidi2pdf
   # rubocop:disable Metrics/AbcSize
   class CLI < Thor
+    @run_launcher: untyped
+
+    @render_input_path: untyped
+
+    @stdin_content: untyped
+
+    @stdin_tempfile: untyped
+
     @launcher: untyped
 
+    include JsonOutput
+
     def self.exit_on_failure?: () -> true
 
-    def render: () -> untyped
+    def render: () -> (nil | untyped)
 
     def version: () -> untyped
 
+    def schema: (untyped kind) -> untyped
+
+    def diagnose: () -> untyped
+
+    # Named run_recipe, not run: Thor::Base reserves "run" as a method name (Thor::Base::
+    # ClassMethods#is_thor_reserved_word?) and refuses to define a command with that name. `map`
+    # below is what makes `bidi2pdf run recipe.yml` dispatch here.
+    def run_recipe: (untyped recipe_path) -> untyped
+
     def template: () -> untyped
 
     private
 
+    # rubocop:disable-next Metrics/CyclomaticComplexity
+    def perform_human_render: () -> untyped
+
+    def perform_structured_render: () -> untyped
+
+    def emit_structured_render_output: (untyped result, untyped collector) -> untyped
+
+    def perform_human_diagnose: () -> untyped
+
+    def perform_structured_diagnose: () -> untyped
+
+    def diagnose_payload: (untyped result, untyped diagnostics) -> { schema_version: 1, ok: untyped, command: "diagnose", page: untyped, console: untyped, network_failures: untyped, fonts: untyped, print_media: untyped, paged_js: untyped, screenshot: untyped, pdf: untyped, warnings: untyped, error: untyped }
+
+    def capture_diagnose_screenshot: (untyped tab) -> (nil | untyped)
+
+    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
+    def perform_structured_run: (untyped recipe_path) -> untyped
+
+    def load_and_validate_recipe: (untyped recipe_path) -> untyped
+
+    def recipe_requested_url: (untyped recipe) -> untyped
+
+    def with_recipe_tab: (untyped recipe) { (untyped) -> untyped } -> untyped
+
+    # A failing action/assertion raises Recipe::Runner::StepFailure (its own entries plus the real
+    # Bidi2pdf::Error as #cause). The block always receives the entries run so far - whether every
+    # step succeeded or the run stopped partway - before the cause is re-raised so
+    # ResultCollector's ordinary error handling takes over; without the block, a failure's partial
+    # entries would otherwise be lost along with the exception that discarded them.
+    def run_recipe_steps: (untyped runner, untyped method_name) { (untyped) -> untyped } -> untyped
+
+    def launcher_for_recipe: (untyped recipe) -> untyped
+
+    def recipe_input_path: (untyped recipe) -> (nil | untyped)
+
+    def print_for_recipe: (untyped tab, untyped recipe) -> untyped
+
+    def symbolize_print_options: (untyped opts) -> untyped
+
+    def write_recipe_screenshot: (untyped tab, untyped recipe) -> (nil | untyped)
+
+    def write_recipe_manifest: (untyped recipe, untyped result) -> untyped
+
+    def recipe_input_type: (untyped recipe) -> ("url" | "html_file" | "stdin")
+
+    def run_payload: (untyped recipe_path, untyped recipe, untyped result, untyped action_entries, untyped assertion_entries, untyped state) -> { schema_version: 1, ok: untyped, command: "run", recipe: untyped, actions: untyped, assertions: untyped, assigned: untyped, output: untyped, duration_ms: untyped, warnings: untyped, error: untyped }
+
+    def recipe_output_summary: (untyped recipe, untyped result) -> untyped
+
+    # --json and --output - both need exclusive use of stdout - rejected before anything else
+    # runs, so neither stream is touched. The rejection
+    # itself is reported on stderr, since stdout's meaning is exactly what is in dispute.
+    def reject_conflicting_output_streams!: () -> untyped
+
+    def json_mode?: () -> untyped
+
+    def json_stream?: () -> untyped
+
+    def stdin_mode?: () -> untyped
+
+    def stdout_output?: () -> untyped
+
+    def render_output_label: () -> ("-" | untyped)
+
+    def render_output_path: () -> (nil | untyped)
+
+    def requested_source_description: () -> untyped
+
+    def write_manifest: (untyped result) -> untyped
+
+    def input_type: () -> ("url" | "html_file" | "stdin")
+
     def load_config: () -> (nil | untyped)
 
-    def validate_required_options!: () -> (untyped | untyped | nil)
+    def input_sources_provided: () -> untyped
+
+    def validate_required_options!: () -> untyped
+
+    def render_input_path: () -> untyped
+
+    def stdin_content: () -> untyped
+
+    def write_stdin_tempfile: () -> untyped
+
+    def cleanup_stdin_tempfile: () -> (nil | untyped)
+
+    def version_info: () -> { schema_version: 1, ok: true, command: "version", bidi2pdf: untyped, ruby: untyped, pdf_reader: untyped }
+
+    def pdf_reader_version: () -> (nil | untyped)
 
     def validate_print_options: (untyped opts) -> untyped
 

data/sig/bidi2pdf/diagnose.rbs

@@ -0,0 +1,30 @@
+module Bidi2pdf
+  # Collects the render-focused diagnostics behind `bidi2pdf diagnose`: why does the PDF not look
+  # like the page, not what the page's content is. Everything here reuses
+  # BrowserTab#execute_script - no DOM dump, no headings/links/forms extraction; console and
+  # network data come from the caller's own
+  # ResultCollector, the same source `render` uses, not from here.
+  #
+  # Each script returns (or resolves to) a JSON string, extracted via #dig("result", "value") -
+  # BiDi's script.evaluate already awaits a returned Promise (awaitPromise: true, see
+  # Commands::ScriptEvaluate), so document.fonts.ready needs no wrap_in_promise: wrapper.
+  class Diagnose
+    @tab: untyped
+
+    PAGE_SCRIPT: "JSON.stringify({\n  title: document.title,\n  url: window.location.href,\n  lang: document.documentElement.lang || null\n})\n"
+
+    FONTS_SCRIPT: "document.fonts.ready.then(function () {\n  var loaded = [];\n  var failed = [];\n  document.fonts.forEach(function (face) {\n    var label = face.family + \" \" + face.weight + \" \" + face.style;\n    if (face.status === \"error\") { failed.push(label); } else { loaded.push(label); }\n  });\n  return JSON.stringify({ status: failed.length > 0 ? \"partial\" : \"loaded\", loaded: loaded, failed: failed });\n})\n"
+
+    PRINT_MEDIA_SCRIPT: "(function () {\n  var printSheets = [];\n  var pageRules = [];\n  var unreadable = [];\n\n  for (var i = 0; i < document.styleSheets.length; i++) {\n    var sheet = document.styleSheets[i];\n    try {\n      var rules = sheet.cssRules || sheet.rules;\n      for (var j = 0; j < rules.length; j++) {\n        var rule = rules[j];\n        if (rule.media && Array.prototype.includes.call(rule.media, \"print\")) {\n          printSheets.push(sheet.href || \"(inline)\");\n        }\n        if (typeof CSSRule !== \"undefined\" && rule.type === CSSRule.PAGE_RULE) {\n          pageRules.push(rule.cssText);\n        }\n      }\n    } catch (e) {\n      unreadable.push(sheet.href || \"(inline)\");\n    }\n  }\n\n  var fixedOrSticky = [];\n  var breakInsideAvoidCount = 0;\n  var elements = document.querySelectorAll(\"body *\");\n  for (var k = 0; k < elements.length; k++) {\n    var el = elements[k];\n    var computed = window.getComputedStyle(el);\n    if (computed.position === \"fixed\" || computed.position === \"sticky\") {\n      var classPart = typeof el.className === \"string\" && el.className.trim() ? \".\" + el.className.trim().split(/\\s+/).join(\".\") : \"\";\n      var selector = el.id ? \"#\" + el.id : el.tagName.toLowerCase() + classPart;\n      fixedOrSticky.push({ selector: selector, position: computed.position });\n    }\n    if (computed.breakInside === \"avoid\" || computed.pageBreakInside === \"avoid\") {\n      breakInsideAvoidCount++;\n    }\n  }\n\n  return JSON.stringify({\n    stylesheets_with_print_rules: Array.from(new Set(printSheets)),\n    page_rules: pageRules,\n    break_inside_avoid_count: breakInsideAvoidCount,\n    fixed_or_sticky_elements: fixedOrSticky,\n    unreadable_stylesheets: Array.from(new Set(unreadable))\n  });\n})()\n"
+
+    PAGED_JS_SCRIPT: "(function () {\n  var detected = !!(window.Paged || window.PagedPolyfill);\n  var pages = document.querySelectorAll(\".pagedjs_page\").length;\n  return JSON.stringify({ detected: detected, ready: pages > 0, pages: pages });\n})()\n"
+
+    def initialize: (tab: untyped) -> void
+
+    def call: () -> { page: untyped, fonts: untyped, print_media: untyped, paged_js: untyped }
+
+    private
+
+    def collect: (untyped script) -> untyped
+  end
+end

data/sig/bidi2pdf/error_codes.rbs

@@ -0,0 +1,21 @@
+module Bidi2pdf
+  # Maps an exception to the stable, machine-readable code used by --json/--json-stream/manifests
+  # and recipe results. Derived from the existing Bidi2pdf::Error hierarchy rather than duplicated
+  # beside it: a new failure mode gets a new subclass in lib/bidi2pdf.rb and a row here, never a
+  # bare string minted ad hoc.
+  #
+  # MAPPING is ordered most-specific-subclass first - #for walks it in order and returns the first
+  # match, so a subclass must appear before any of its ancestors.
+  module ErrorCodes
+    MAPPING: ::Hash[untyped, "MISSING_INPUT" | "MULTIPLE_INPUT_SOURCES" | "EMPTY_INPUT" | "INVALID_CONFIG" | "INVALID_PRINT_OPTION" | "INVALID_RECIPE" | "PDF_INSPECTION_UNAVAILABLE" | "BROWSER_LAUNCH_FAILED" | "COMMAND_TIMEOUT" | "BROWSER_DISCONNECTED" | "NAVIGATION_TIMEOUT" | "NAVIGATION_AUTH" | "NAVIGATION_NOT_FOUND" | "DNS_ERROR" | "NAVIGATION_FAILED" | "SELECTOR_NOT_FOUND" | "PAGE_NOT_AS_EXPECTED" | "SCRIPT_ERROR" | "STYLE_ERROR" | "PDF_GENERATION_FAILED" | "SCREENSHOT_FAILED" | "OUTPUT_WRITE_FAILED" | "INTERNAL_ERROR"]
+
+    DEFAULT_CODE: "INTERNAL_ERROR"
+
+    def self.for: (untyped exception) -> untyped
+
+    # Builds the {code:, message:, retryable:, hint:, details:} hash used as Result#error and in
+    # recipe action/assertion failures. Works for any StandardError, not only a Bidi2pdf::Error -
+    # an unexpected exception still gets INTERNAL_ERROR with retryable/hint defaulted safely.
+    def self.describe: (untyped exception, ?details: ::Hash[untyped, untyped]) -> { code: untyped, message: untyped, retryable: untyped, hint: untyped, details: untyped }
+  end
+end

data/sig/bidi2pdf/exit_codes.rbs

@@ -0,0 +1,21 @@
+module Bidi2pdf
+  # Maps an ErrorCodes string to the process exit status the CLI reports. Centralized here so
+  # render/diagnose/run share one table instead of each re-deciding what a given failure is worth.
+  module ExitCodes
+    SUCCESS: 0
+
+    CLI_ERROR: 2
+
+    BROWSER_ERROR: 3
+
+    PAGE_NOT_AS_EXPECTED: 4
+
+    OUTPUT_ERROR: 6
+
+    INTERNAL_ERROR: 70
+
+    CODE_TO_EXIT: { "MISSING_INPUT" => untyped, "MULTIPLE_INPUT_SOURCES" => untyped, "EMPTY_INPUT" => untyped, "INVALID_CONFIG" => untyped, "INVALID_PRINT_OPTION" => untyped, "INVALID_RECIPE" => untyped, "PDF_INSPECTION_UNAVAILABLE" => untyped, "BROWSER_LAUNCH_FAILED" => untyped, "BROWSER_DISCONNECTED" => untyped, "COMMAND_TIMEOUT" => untyped, "NAVIGATION_FAILED" => untyped, "NAVIGATION_TIMEOUT" => untyped, "NAVIGATION_AUTH" => untyped, "NAVIGATION_NOT_FOUND" => untyped, "DNS_ERROR" => untyped, "SELECTOR_NOT_FOUND" => untyped, "PAGE_NOT_AS_EXPECTED" => untyped, "SCRIPT_ERROR" => untyped, "STYLE_ERROR" => untyped, "PDF_GENERATION_FAILED" => untyped, "SCREENSHOT_FAILED" => untyped, "OUTPUT_WRITE_FAILED" => untyped, "INTERNAL_ERROR" => untyped }
+
+    def self.for: (untyped code) -> untyped
+  end
+end

data/sig/bidi2pdf/launcher.rbs

@@ -62,11 +62,20 @@ module Bidi2pdf
 
     @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 launch: () -> untyped
 
+    # Like #launch, but navigates only (see SessionRunner#run_diagnose) and leaves the tab open -
+    # used by `bidi2pdf diagnose`, which has no PDF to produce. #stop closes it, same as it stops
+    # everything else #launch/#diagnose started.
+    #
+    # @return [Bidi2pdf::Bidi::BrowserTab] the navigated tab.
+    def diagnose: () -> untyped
+
     def stop: () -> untyped
 
     private

data/sig/bidi2pdf/manifest.rbs

@@ -0,0 +1,38 @@
+module Bidi2pdf
+  # Builds the render manifest (--manifest FILE) from a completed Bidi2pdf::Result plus the
+  # input/browser/header context around it. Redacts secret-
+  # bearing headers and never records cookie values at all.
+  class Manifest
+    @result: untyped
+
+    @input: untyped
+
+    @headers: untyped
+
+    @navigation_duration_ms: untyped
+
+    @browser: untyped
+
+    SCHEMA_VERSION: 1
+
+    REDACT_HEADER_NAMES: ::Array["authorization" | "proxy-authorization" | "cookie" | "set-cookie" | "x-api-key" | "api-key"]
+
+    SENSITIVE_SUBSTRINGS: ::Array["token" | "secret" | "password" | "authorization" | "api-key" | "apikey"]
+
+    def initialize: (result: untyped, input: untyped, ?headers: ::Hash[untyped, untyped], ?navigation_duration_ms: untyped?, ?browser: ::Hash[untyped, untyped]) -> void
+
+    def self.redact: (untyped headers) -> untyped
+
+    def self.sensitive?: (untyped key) -> untyped
+
+    def to_h: () -> untyped
+
+    def to_json: (*untyped) -> untyped
+
+    private
+
+    def output_section: () -> { path: untyped, pages: untyped, bytes: untyped, sha256: untyped }
+
+    def navigation_section: () -> untyped
+  end
+end

data/sig/bidi2pdf/notifications/json_subscriber.rbs

@@ -0,0 +1,45 @@
+module Bidi2pdf
+  module Notifications
+    # Emits one JSON object per line to an IO (stderr for --json-stream, docs/specs/llm-friendly-
+    # spec.md section 7) as a render progresses, by subscribing to the same Bidi2pdf::Notifications
+    # events Bidi2pdf::ResultCollector and LoggingSubscriber already use - no new instrumentation
+    # points needed. #emit_result writes the final "result" event once the caller has a Result.
+    class JsonSubscriber
+      @io: untyped
+
+      @start: untyped
+
+      @registered: untyped
+
+      SCHEMA_VERSION: 1
+
+      def initialize: (?io: untyped) -> void
+
+      def emit_result: (untyped result) -> untyped
+
+      def unsubscribe: () -> untyped
+
+      private
+
+      def now_ms: () -> untyped
+
+      def elapsed_ms: () -> untyped
+
+      def subscribe: () -> untyped
+
+      def on_navigate: (untyped event) -> untyped
+
+      def on_page_loaded: (untyped _event) -> untyped
+
+      def on_network_idle: (untyped _event) -> untyped
+
+      def on_console: (untyped event) -> untyped
+
+      def on_print: (untyped _event) -> untyped
+
+      def on_screenshot: (untyped _event) -> untyped
+
+      def write: (untyped fields) -> untyped
+    end
+  end
+end

data/sig/bidi2pdf/pdf_inspection.rbs

@@ -0,0 +1,33 @@
+module Bidi2pdf
+  # Lazy, optional wrapper around the pdf-reader gem. pdf-reader is deliberately NOT a bidi2pdf
+  # runtime dependency - render works fine without it,
+  # just with `pages` left nil and a warning, and a recipe assertion that needs it fails
+  # INVALID_RECIPE at validation time rather than crashing mid-render. The official Docker images
+  # (docker/Dockerfile, docker/Dockerfile.slim) install it, so a render inside one of them - the
+  # environment an agent or CI job actually uses - always has page counts and PDF assertions
+  # available without anyone opting in by hand.
+  module PdfInspection
+    self.@available: untyped
+
+    def self.available?: () -> untyped
+
+    # @param bytes [String, nil] raw PDF bytes.
+    # @return [Integer, nil] page count, or nil when pdf-reader is unavailable, bytes is nil,
+    #   or the PDF is malformed.
+    def self.page_count: (untyped bytes) -> untyped
+
+    # @param bytes [String, nil] raw PDF bytes.
+    # @return [String, nil] extracted text across all pages, joined with newlines.
+    def self.text: (untyped bytes) -> untyped
+
+    # Clears the memoized availability check - test-only, so a spec can exercise both branches
+    # of #available? regardless of load order elsewhere in the process.
+    def self.reset_for_testing!: () -> (untyped | nil)
+
+    private
+
+    def self.load_pdf_reader: () -> untyped
+
+    def self.reader_for: (untyped bytes) -> untyped
+  end
+end

data/sig/bidi2pdf/recipe/loader.rbs

@@ -0,0 +1,20 @@
+module Bidi2pdf
+  class Recipe
+    # Reads a recipe file (YAML, or JSON when the extension is .json) into a plain Hash. Never
+    # launches a browser - a malformed file fails right here.
+    #
+    # Security: YAML is parsed with Psych.safe_load and no extra options. Its defaults already
+    # refuse both custom type tags (no arbitrary Ruby object instantiation) and aliases - the
+    # latter matters concretely: a small file using nested YAML anchors/aliases ("billion laughs")
+    # can expand to millions of elements in memory; confirmed live, a 273-byte such file produced
+    # 10 million array elements in under 2ms. Neither aliases nor a Date/Time value are used by any
+    # field a recipe defines, so neither is turned back on "just in case" - only what the format
+    # actually needs is permitted. MAX_BYTES bounds the file itself before it is even parsed.
+    module Loader
+      MAX_BYTES: 1048576
+
+      # rubocop:disable-next Metrics/AbcSize
+      def self.load: (untyped path) -> untyped
+    end
+  end
+end

data/sig/bidi2pdf/recipe/runner.rbs

@@ -0,0 +1,92 @@
+module Bidi2pdf
+  class Recipe
+    # Runs a validated recipe's actions and assertions against a navigated tab. A thin dispatch
+    # over BrowserTab's own methods, not a parallel action/assertion class hierarchy - a step
+    # that needs something BrowserTab cannot do belongs there, not here.
+    class Runner
+      @recipe: untyped
+
+      @tab: untyped
+
+      @collector: untyped
+
+      @state: untyped
+
+      @pdf_bytes: untyped
+
+      # Raised on the first failing action/assertion; #entries carries every step run so far
+      # (successes and the failure itself), for the caller to report in the recipe result.
+      class StepFailure < StandardError
+        @entries: untyped
+
+        @cause: untyped
+
+        attr_reader entries: untyped
+
+        attr_reader cause: untyped
+
+        def initialize: (untyped entries, untyped cause) -> void
+      end
+
+      attr_reader state: untyped
+
+      attr_accessor pdf_bytes: untyped
+
+      # @param recipe [Bidi2pdf::Recipe]
+      # @param tab [Bidi2pdf::Bidi::BrowserTab] a navigated tab (e.g. from Launcher#diagnose)
+      # @param collector [Bidi2pdf::ResultCollector] source of #console/#network_failures -
+      #   exposed live, so assertions can read them mid-run (see ResultCollector's own docs)
+      def initialize: (recipe: untyped, tab: untyped, collector: untyped) -> void
+
+      # @return [Array<Hash>] one entry per action actually run
+      # @raise [StepFailure] on the first failing action
+      def run_actions: () -> untyped
+
+      # @return [Array<Hash>] one entry per assertion actually run
+      # @raise [StepFailure] on the first failing assertion
+      def run_assertions: () -> untyped
+
+      private
+
+      # rubocop:disable-next Metrics/AbcSize
+      def run_steps: (untyped steps) { (untyped, untyped) -> untyped } -> untyped
+
+      def now_ms: () -> untyped
+
+      def elapsed_ms: (untyped start) -> untyped
+
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity
+      def dispatch_action: (untyped name, untyped opts) -> untyped
+
+      def action_wait_for: (untyped opts) -> (nil | untyped)
+
+      def wait_for_condition: (untyped opts) -> ("document.querySelector('.pagedjs_page')" | ::String | untyped)
+
+      def action_click: (untyped opts) -> (nil | untyped)
+
+      def action_evaluate: (untyped opts) -> untyped
+
+      # rubocop:disable-next Metrics/CyclomaticComplexity
+      def dispatch_assertion: (untyped name, untyped step) -> untyped
+
+      def assertion_selector_exists: (untyped opts) -> ::Array[untyped | { selector: untyped }]
+
+      def assertion_text_present: (untyped opts) -> ::Array[untyped | { text: untyped }]
+
+      def assertion_no_console_errors: () -> ::Array[untyped]
+
+      # Filtering by resource type (a `types:` option) is not implemented: Bidi2pdf::Bidi::
+      # NetworkEvent carries an HTTP method, not a resource type, so there is nothing to filter
+      # by yet. Every captured failure counts.
+      def assertion_no_network_failures: () -> ::Array[untyped]
+
+      def assertion_fonts_loaded: () -> ::Array[untyped | nil]
+
+      def assertion_page_count: (untyped expected) -> ::Array[untyped | { expected: untyped, actual: untyped }]
+
+      def assertion_pdf_text_present: (untyped opts) -> ::Array[untyped | { text: untyped }]
+
+      def assertion_pdf_not_blank: () -> ::Array[untyped | { page_count: untyped, text_present: untyped }]
+    end
+  end
+end

data/sig/bidi2pdf/recipe/schema_shape.rbs

@@ -0,0 +1,85 @@
+module Bidi2pdf
+  class Recipe
+    # Structural validation against Schema::RECIPE itself, not a hand-duplicated parallel list of
+    # rules. Validator's other #check_* methods each enforce one *semantic* rule (an action name
+    # is known, a source key is truthy, a presence assertion is `true`) with a friendly, specific
+    # message - none of them enforce the schema's own `additionalProperties: false` at every
+    # level, so an extra, unrecognized key sitting alongside an otherwise-valid one used to pass
+    # silently even though `bidi2pdf schema recipe` would reject it (`{url: "...", stdin: false}`,
+    # `{wait_for: {...}, extra: 1}` - two action names in one step, `wait_for: {selector: "#x",
+    # bogus: "y"}`). #check_shape (see Validator) closes that whole class of gap generically by
+    # walking the schema the CLI already publishes, instead of re-describing "what's allowed" a
+    # second time in Ruby - the schema is the one place that description can't drift from itself.
+    #
+    # Deliberately not a general JSON Schema engine and not a gem dependency: only the keywords
+    # Schema::RECIPE actually uses (type, const, enum, required, additionalProperties, properties,
+    # oneOf, anyOf, items, minimum, maximum). Extend the keyword list only if a future schema
+    # branch genuinely needs one this doesn't cover yet.
+    module SchemaShape
+      TYPE_CHECKS: { "object" => untyped, "array" => untyped, "string" => untyped, "integer" => untyped, "number" => untyped, "boolean" => untyped, "null" => untyped }
+
+      CHECKS: ::Array[:const_ok? | :enum_ok? | :type_ok? | :one_of_ok? | :any_of_ok? | :required_ok? | :additional_properties_ok? | :properties_ok? | :items_ok? | :bounds_ok?]
+
+      # @return [Boolean] whether value satisfies schema
+      def self?.matches?: (untyped schema, untyped value) -> untyped
+
+      VIOLATION_CHECKS: ::Array[:oneof_violation | :anyof_violation | :required_violation | :additional_properties_violation | :const_violation | :enum_violation | :type_violation | :bounds_violation | :nested_violation]
+
+      # @return [Hash, nil] {path:, reason:} for the first violation a depth-first walk finds, or
+      #   nil if value already satisfies schema. Not necessarily *the* most relevant violation
+      #   when several exist at once - good enough to point an agent at the right neighborhood,
+      #   not a substitute for reading `bidi2pdf schema recipe` for the exact shape.
+      def self?.first_violation: (untyped schema, untyped value, ?untyped path) -> (nil | untyped | { path: untyped, reason: "does not match the schema" })
+
+      def self?.const_ok?: (untyped schema, untyped value) -> untyped
+
+      def self?.enum_ok?: (untyped schema, untyped value) -> untyped
+
+      def self?.type_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.one_of_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.any_of_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.required_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.additional_properties_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.properties_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.items_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.bounds_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.display_path: (untyped path) -> untyped
+
+      # When zero branches match but exactly one is "plausible" (its own required key(s) are
+      # present, ignoring additionalProperties), recurse into that one branch for a specific
+      # reason/path instead of a bare "matched 0 of N" - this is what turns "actions[0] doesn't
+      # match any known action" into "actions[0].wait_for: unknown key(s): bogus".
+      def self?.oneof_violation: (untyped schema, untyped value, untyped path) -> (nil | untyped)
+
+      def self?.single_plausible_violation: (untyped schema, untyped value, untyped path) -> (nil | untyped)
+
+      def self?.anyof_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.required_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.additional_properties_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.const_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.enum_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.type_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.bounds_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.nested_violation: (untyped schema, untyped value, untyped path) -> untyped
+
+      def self?.properties_violation: (untyped schema, untyped value, untyped path) -> (nil | untyped)
+
+      def self?.items_violation: (untyped schema, untyped value, untyped path) -> (nil | untyped)
+    end
+  end
+end