bidi2pdf 0.1.15 → 0.1.16

data/lib/bidi2pdf.rb

@@ -9,10 +9,11 @@ require_relative "bidi2pdf/bidi/session"
 require_relative "bidi2pdf/dsl"
 require_relative "bidi2pdf/notifications"
 require_relative "bidi2pdf/notifications/logging_subscriber"
+require_relative "bidi2pdf/notifications/json_subscriber"
 require_relative "bidi2pdf/session_warmer"
 require_relative "bidi2pdf/verbose_logger"
 
-module Bidi2pdf
+module Bidi2pdf # rubocop:disable Metrics/ModuleLength
   PAPER_FORMATS_CM = {
     letter: { width: 21.59, height: 27.94 },
     legal: { width: 21.59, height: 35.56 },
@@ -27,11 +28,32 @@ module Bidi2pdf
     a6: { width: 10.5, height: 14.8 }
   }.freeze
 
-  class Error < StandardError; end
+  # Base class for every error this gem raises. Carries the machine-readable surface used by
+  # --json/--json-stream/manifests/recipe results (see Bidi2pdf::ErrorCodes): #retryable? and
+  # #hint are overridden per subclass below where a useful default exists; #details is set at
+  # raise time for structured, serializable context (e.g. which selector, which assertion).
+  class Error < StandardError
+    attr_reader :details
 
-  class SessionNotStartedError < Error; end
+    def initialize(message = nil, details: {})
+      @details = details
+      super(message)
+    end
+
+    def retryable? = false
 
-  class WebsocketError < Error; end
+    def hint = nil
+  end
+
+  class SessionNotStartedError < Error
+    def retryable? = true
+
+    def hint = "Check Chrome/chromedriver are installed and reachable, or that --remote-browser-url points at a running instance"
+  end
+
+  class WebsocketError < Error
+    def retryable? = true
+  end
 
   class ClientError < WebsocketError; end
 
@@ -48,7 +70,11 @@ module Bidi2pdf
 
   class CmdResponseNotStoredError < ClientError; end
 
-  class CmdTimeoutError < ClientError; end
+  class CmdTimeoutError < ClientError
+    def retryable? = true
+
+    def hint = "Raise --default-timeout"
+  end
 
   class PrintError < Error; end
 
@@ -77,13 +103,69 @@ module Bidi2pdf
       @url = url
       super("Navigation to #{url} failed due to authentication error. #{message}")
     end
+
+    def hint = "Pass --auth user:pass, or check the credentials are still valid"
+  end
+
+  class NavigationTimeoutError < NavigationError
+    def retryable? = true
+
+    def hint = "Raise --default-timeout, or add --wait-network-idle if the page loads data after the load event"
+  end
+
+  class NavigationNotFoundError < NavigationError
+    def hint = "Check the URL is correct"
+  end
+
+  class NavigationDNSError < NavigationError
+    attr_reader :url
+
+    def initialize(url = nil, message = nil)
+      @url = url
+      super(url ? "Navigation to #{url} failed: DNS resolution error. #{message}" : message)
+    end
+
+    def retryable? = true
+
+    def hint = "Check the hostname is correct and reachable from this machine/container"
   end
 
-  class NavigationTimeoutError < NavigationError; end
+  # --- Errors introduced for the CLI/recipe surface.
+  # Same style as the errors above: a thin subclass per failure mode, message text carried at the
+  # raise site so it stays exactly as specific as the situation warrants.
+
+  class MissingInputError < Error; end
+
+  class MultipleInputSourcesError < Error; end
 
-  class NavigationNotFoundError < NavigationError; end
+  class EmptyInputError < Error; end
+
+  class InvalidConfigError < Error; end
+
+  class InvalidPrintOptionError < Error; end
+
+  class InvalidRecipeError < Error; end
+
+  class SelectorNotFoundError < Error; end
+
+  class PageNotAsExpectedError < Error; end
+
+  class OutputWriteError < Error; end
+
+  class PdfInspectionUnavailableError < Error
+    def hint = "Install the pdf-reader gem, or drop assertions/fields that need it"
+  end
 
-  class NavigationDNSError < NavigationError; end
+  # Loaded here, after the error classes above, since these reference them at load time.
+  require_relative "bidi2pdf/error_codes"
+  require_relative "bidi2pdf/exit_codes"
+  require_relative "bidi2pdf/result"
+  require_relative "bidi2pdf/pdf_inspection"
+  require_relative "bidi2pdf/result_collector"
+  require_relative "bidi2pdf/manifest"
+  require_relative "bidi2pdf/schema"
+  require_relative "bidi2pdf/diagnose"
+  require_relative "bidi2pdf/recipe"
 
   # Global configuration for Bidi2pdf
 

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