bidi2pdf 0.1.14 → 0.1.16

data/sig/bidi2pdf/recipe/validator.rbs

@@ -0,0 +1,54 @@
+module Bidi2pdf
+  class Recipe
+    # Validates a loaded recipe against the schema `bidi2pdf schema recipe` publishes, before any
+    # browser is launched - `bidi2pdf run --validate` runs exactly this and nothing else. Every
+    # failure is Bidi2pdf::InvalidRecipeError (or Bidi2pdf::PdfInspectionUnavailableError for a
+    # PDF assertion without pdf-reader installed), details carrying a `path` an agent can act on
+    # directly.
+    class Validator
+      @recipe: untyped
+
+      def initialize: (untyped recipe) -> void
+
+      def validate!: () -> untyped
+
+      private
+
+      def check_version: () -> (nil | untyped)
+
+      def check_top_level_keys: () -> (nil | untyped)
+
+      def check_source: () -> untyped
+
+      def check_steps: (untyped section, untyped steps, untyped known) -> untyped
+
+      # Mirrors Schema::RECIPE_ACTIONS' own wait_for oneOf: exactly one of selector/paged_js/script.
+      # --validate runs this check itself rather than relying on Runner#wait_for_condition, whose
+      # own "needs one of" error only fires mid-run (after a browser is already launched) and does
+      # not catch "more than one given" at all - it just silently prefers paged_js, then selector.
+      def check_wait_for_conditions: () -> untyped
+
+      # Mirrors Schema::RECIPE_ASSERT's own const: true for the 4 presence-only assertions -
+      # Runner never reads the value beside them, so anything but `true` is misleading rather than
+      # merely unusual (see Recipe::PRESENCE_ONLY_ASSERTIONS' own comment).
+      def check_presence_assertions: () -> untyped
+
+      def check_pdf_assertions_need_pdf_inspection: () -> (nil | untyped)
+
+      def check_output: () -> (nil | untyped)
+
+      def check_print_options: () -> untyped
+
+      def symbolize: (untyped hash) -> untyped
+
+      # Runs last, deliberately: everything above gives a friendlier, more specific message for
+      # the case it already knows about (an unknown action name, a non-true presence assertion, a
+      # real PrintParametersValidator error, ...), so this only ever fires for a shape violation
+      # none of them catches - an extra/unrecognized key sitting alongside an otherwise-valid one
+      # (SchemaShape's own doc comment has the concrete examples this closes).
+      def check_shape: () -> (nil | untyped)
+
+      def fail!: (untyped reason, path: untyped) -> untyped
+    end
+  end
+end

data/sig/bidi2pdf/recipe.rbs

@@ -0,0 +1,72 @@
+module Bidi2pdf
+  # A recipe is a rendering contract: the waits and preparation a page needs before it is printed,
+  # and the properties the resulting PDF must have - not a general browser-automation script.
+  # `bidi2pdf run recipe.yml` is Loader -> (an invalid recipe stops here, no browser ever
+  # launches) -> Validator -> Runner.
+  class Recipe
+    @data: untyped
+
+    @path: untyped
+
+    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"]
+
+    PAGE_ASSERTIONS: ::Array["selector_exists" | "text_present" | "no_console_errors" | "no_network_failures" | "fonts_loaded"]
+
+    PDF_ASSERTIONS: ::Array["page_count" | "pdf_text_present" | "pdf_not_blank"]
+
+    KNOWN_ASSERTIONS: untyped
+
+    KNOWN_OUTPUTS: ::Array["pdf" | "manifest" | "screenshot"]
+
+    # These four assertions are pure presence checks - Runner never reads the value beside them
+    # (see #assertion_no_console_errors and friends), so a bare key is really what's being
+    # asserted. `false`/anything but `true` is therefore misleading, not merely unusual: schema
+    # recipe encodes this as `const: true` and Validator#check_presence_assertions enforces it too.
+    PRESENCE_ONLY_ASSERTIONS: ::Array["no_console_errors" | "no_network_failures" | "fonts_loaded" | "pdf_not_blank"]
+
+    attr_reader data: untyped
+
+    attr_reader path: untyped
+
+    def self.load: (untyped path) -> untyped
+
+    def initialize: (untyped data, ?path: untyped?) -> void
+
+    def validate!: () -> untyped
+
+    def actions: () -> untyped
+
+    def assertions: () -> untyped
+
+    def source: () -> untyped
+
+    def browser_options: () -> untyped
+
+    def headers: () -> untyped
+
+    def cookies: () -> untyped
+
+    def auth: () -> untyped
+
+    def print_options: () -> untyped
+
+    def output: () -> untyped
+
+    def needs_pdf?: () -> untyped
+
+    def self.step_name: (untyped step) -> untyped
+
+    def step_name: (untyped step) -> untyped
+
+    # The value beside a step's name - a Hash of options (`wait_for: {selector: ..., timeout:
+    # ...}`), a bare scalar (`page_count: 2`, `no_console_errors: true`), or nil.
+    def step_value: (untyped step) -> (untyped | nil)
+
+    # step_value coerced to a Hash of options - most actions/assertions take this shape; a bare
+    # scalar step (page_count: 2, no_console_errors: true) has no options of its own to offer here,
+    # so callers that need the scalar itself use #step_value directly.
+    def step_options: (untyped step) -> untyped
+  end
+end

data/sig/bidi2pdf/result.rbs

@@ -0,0 +1,71 @@
+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
+    @command: untyped
+
+    @ok: untyped
+
+    @output: untyped
+
+    @bytes: untyped
+
+    @sha256: untyped
+
+    @pages: untyped
+
+    @duration_ms: untyped
+
+    @navigation: untyped
+
+    @console: untyped
+
+    @network_failures: untyped
+
+    @warnings: untyped
+
+    @error: untyped
+
+    @metadata: untyped
+
+    SCHEMA_VERSION: 1
+
+    attr_reader command: untyped
+
+    attr_reader output: untyped
+
+    attr_reader bytes: untyped
+
+    attr_reader sha256: untyped
+
+    attr_reader pages: untyped
+
+    attr_reader duration_ms: untyped
+
+    attr_reader navigation: untyped
+
+    attr_reader console: untyped
+
+    attr_reader network_failures: untyped
+
+    attr_reader warnings: untyped
+
+    attr_reader error: untyped
+
+    attr_reader metadata: untyped
+
+    # rubocop:disable-next Metrics/ParameterLists, Naming/MethodParameterName
+    def initialize: (command: untyped, ok: untyped, ?output: untyped?, ?bytes: untyped?, ?sha256: untyped?, ?pages: untyped?, ?duration_ms: untyped?, ?navigation: untyped?, ?console: untyped, ?network_failures: untyped, ?warnings: untyped, ?error: untyped?, ?metadata: ::Hash[untyped, untyped]) -> void
+
+    def self.success: (**untyped) -> untyped
+
+    def self.failure: (error: untyped, **untyped) -> untyped
+
+    def ok?: () -> untyped
+
+    def to_h: () -> untyped
+
+    def to_json: (*untyped) -> untyped
+  end
+end

data/sig/bidi2pdf/result_collector.rbs

@@ -0,0 +1,106 @@
+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
+    @requested_url: untyped
+
+    @command: untyped
+
+    @output: untyped
+
+    @console: untyped
+
+    @network_events: untyped
+
+    @pdf_bytes: untyped
+
+    # 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: untyped
+
+    @navigation_event: untyped
+
+    # #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: untyped
+
+    # #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 navigation_event: untyped
+
+    # #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 pdf_bytes: untyped
+
+    # #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 console: untyped
+
+    def initialize: (requested_url: untyped, command: untyped, ?output: untyped?) -> void
+
+    # 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: () { () -> untyped } -> untyped
+
+    def network_failures: () -> untyped
+
+    private
+
+    def now_ms: () -> untyped
+
+    def elapsed_ms: (untyped start) -> untyped
+
+    def subscribe: () -> untyped
+
+    def unsubscribe: () -> untyped
+
+    # 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: (untyped event) -> untyped
+
+    def on_console: (untyped event) -> untyped
+
+    def on_network_event: (untyped event) -> (nil | untyped)
+
+    def on_print: (untyped event) -> untyped
+
+    # rubocop:disable-next Naming/MethodParameterName
+    def build_result: (ok: untyped, duration_ms: untyped, ?error: untyped?) -> untyped
+
+    def navigation_info: () -> { requested_url: untyped, final_url: untyped, status: untyped }
+
+    # 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: () -> (nil | untyped)
+
+    def warnings: () -> (::Array[untyped] | ::Array["pages requires the pdf-reader gem"])
+  end
+end

data/sig/bidi2pdf/schema.rbs

@@ -0,0 +1,45 @@
+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
+    ERROR: { "type" => ::Array["object" | "null"], "required" => ::Array["code" | "message" | "retryable"], "properties" => { "code" => { "type" => "string" }, "message" => { "type" => "string" }, "retryable" => { "type" => "boolean" }, "hint" => { "type" => ::Array["string" | "null"] }, "details" => { "type" => "object" } } }
+
+    NAVIGATION: { "type" => ::Array["object" | "null"], "properties" => { "requested_url" => { "type" => ::Array["string" | "null"] }, "final_url" => { "type" => ::Array["string" | "null"] }, "status" => { "type" => ::Array["integer" | "null"] } } }
+
+    CONSOLE: { "type" => "array", "items" => { "type" => "object", "properties" => { "level" => { "type" => "string" }, "text" => { "type" => "string" } } } }
+
+    NETWORK_FAILURES: { "type" => "array", "items" => { "type" => "object", "properties" => { "url" => { "type" => "string" }, "method" => { "type" => ::Array["string" | "null"] }, "status" => { "type" => ::Array["integer" | "null"] }, "state" => { "type" => "string" } } } }
+
+    WARNINGS: { "type" => "array", "items" => { "type" => "string" } }
+
+    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" => ::Array["schema_version" | "ok" | "command" | "console" | "network_failures" | "warnings"], "properties" => { "schema_version" => { "const" => 1 }, "ok" => { "type" => "boolean" }, "command" => { "const" => "render" }, "output" => { "type" => ::Array["string" | "null"] }, "bytes" => { "type" => ::Array["integer" | "null"] }, "sha256" => { "type" => ::Array["string" | "null"] }, "pages" => { "type" => ::Array["integer" | "null"], "description" => "null when the pdf-reader gem is unavailable" }, "duration_ms" => { "type" => ::Array["integer" | "null"] }, "navigation" => untyped, "console" => untyped, "network_failures" => untyped, "warnings" => untyped, "error" => untyped } }
+
+    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" => ::Array["schema_version" | "ok" | "command" | "console" | "network_failures" | "warnings"], "properties" => { "schema_version" => { "const" => 1 }, "ok" => { "type" => "boolean" }, "command" => { "const" => "diagnose" }, "page" => { "type" => ::Array["object" | "null"] }, "console" => untyped, "network_failures" => untyped, "fonts" => { "type" => ::Array["object" | "null"] }, "print_media" => { "type" => ::Array["object" | "null"] }, "paged_js" => { "type" => ::Array["object" | "null"] }, "screenshot" => { "type" => ::Array["string" | "null"], "description" => "path written, when --screenshot was given" }, "pdf" => { "type" => ::Array["object" | "null"], "description" => "present when --pdf was given", "properties" => { "path" => { "type" => "string" }, "pages" => { "type" => ::Array["integer" | "null"] }, "not_blank" => { "type" => ::Array["boolean" | "null"] } } }, "warnings" => untyped, "error" => untyped } }
+
+    RUN_STEP: { "type" => "object", "required" => ::Array["index" | "type" | "ok"], "properties" => { "index" => { "type" => "integer" }, "type" => { "type" => "string" }, "ok" => { "type" => "boolean" }, "duration_ms" => { "type" => "integer" }, "details" => { "type" => "object" } } }
+
+    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" => ::Array["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" => untyped }, "assertions" => { "type" => "array", "items" => untyped }, "assigned" => { "type" => "object", "description" => "values captured by evaluate ... assign:, keyed by name" }, "output" => { "type" => ::Array["object" | "null"], "description" => "null when the run failed", "properties" => { "pdf" => { "type" => ::Array["string" | "null"] }, "manifest" => { "type" => ::Array["string" | "null"] }, "screenshot" => { "type" => ::Array["string" | "null"] }, "bytes" => { "type" => ::Array["integer" | "null"] }, "sha256" => { "type" => ::Array["string" | "null"] }, "pages" => { "type" => ::Array["integer" | "null"] } } }, "duration_ms" => { "type" => ::Array["integer" | "null"] }, "warnings" => untyped, "error" => untyped } }
+
+    MANIFEST: { "$schema" => "https://json-schema.org/draft/2020-12/schema", "title" => "Bidi2pdf render manifest", "description" => "--manifest FILE output", "type" => "object", "required" => ::Array["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" => ::Array["type"], "properties" => { "type" => { "type" => "string", "enum" => ::Array["url" | "html_file" | "stdin"] }, "url" => { "type" => ::Array["string" | "null"] } } }, "output" => { "type" => "object", "properties" => { "path" => { "type" => ::Array["string" | "null"] }, "pages" => { "type" => ::Array["integer" | "null"] }, "bytes" => { "type" => ::Array["integer" | "null"] }, "sha256" => { "type" => ::Array["string" | "null"] } } }, "browser" => { "type" => "object" }, "navigation" => untyped, "render" => { "type" => "object", "properties" => { "duration_ms" => { "type" => ::Array["integer" | "null"] } } }, "console" => untyped, "network_failures" => untyped, "warnings" => untyped, "headers" => { "type" => "object", "description" => "present only when custom headers were given; secret-bearing values are redacted" } } }
+
+    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" => ::Array["schema_version" | "t_ms" | "event"], "properties" => { "schema_version" => { "const" => 1 }, "t_ms" => { "type" => "integer", "description" => "milliseconds since the render started" }, "event" => { "type" => "string", "enum" => ::Array["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" => ::Array[untyped] } } }
+
+    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_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 } } }] }
+
+    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" => ::Array["portrait" | "landscape"] }, "scale" => { "type" => "number", "minimum" => ::Float, "maximum" => ::Float }, "pageRanges" => { "type" => "array", "items" => { "type" => ::Array["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" => ::Float }, "height" => { "type" => "number", "minimum" => ::Float } } } } }
+
+    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" => ::Array["version" | "source" | "output"], "additionalProperties" => false, "properties" => { "version" => { "const" => 1 }, "source" => untyped, "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" => untyped }, "assert" => { "type" => "array", "items" => untyped }, "print" => untyped, "output" => { "type" => "object", "description" => "at least one of pdf, manifest, screenshot", "anyOf" => ::Array[{ "required" => ::Array["pdf"] } | { "required" => ::Array["manifest"] } | { "required" => ::Array["screenshot"] }], "properties" => { "pdf" => { "type" => "string" }, "manifest" => { "type" => "string" }, "screenshot" => { "type" => "string" } } } } }
+
+    ALL: { "render" => untyped, "diagnose" => untyped, "run" => untyped, "manifest" => untyped, "recipe" => untyped, "event" => untyped }
+
+    def self.for: (untyped kind) -> untyped
+  end
+end

data/sig/bidi2pdf/session_runner.rbs

@@ -67,6 +67,17 @@ module Bidi2pdf
 
     def run: () -> untyped
 
+    # 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: () -> untyped
+
+    # 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: () -> untyped
+
     private
 
     def setup_browser: () -> untyped
@@ -77,6 +88,12 @@ module Bidi2pdf
 
     def add_basic_auth: () -> (nil | untyped)
 
+    # 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: () -> untyped
+
     # rubocop: disable Metrics/AbcSize
     def run_flow: () -> untyped
 

data/sig/bidi2pdf/session_warmer.rbs

@@ -0,0 +1,221 @@
+module Bidi2pdf
+  # Keeps a small number of Chrome sessions pre-warmed (chromedriver started, WebSocket connected,
+  # browser ready) so a render can skip that startup latency on the request path. Isolation matches
+  # today's one-Chrome-per-render model exactly: every checked-out slot is used for exactly one
+  # +with_tab+ block and then retired (never returned to the cache) - only a fresh replacement is
+  # warmed in its place, off the request path. Checkout never waits for a warm slot: one is used if
+  # it is ready, otherwise a slot is created synchronously on the spot, i.e. today's exact behavior
+  # for that one render - including its failure mode: if that cold start fails, the error propagates
+  # out of +with_tab+ exactly as it would without the warmer.
+  #
+  # @example Rails initializer
+  #   Bidi2pdf::SessionWarmer.configure do |c|
+  #     c.size = 2
+  #     c.headless = true
+  #   end
+  #
+  # @example Per-request usage
+  #   Bidi2pdf::SessionWarmer.with_tab do |tab|
+  #     tab.navigate_to(url)
+  #     tab.print("invoice.pdf")
+  #   end
+  class SessionWarmer
+    self.@config: untyped
+
+    # Cleared first: if the constructor below raises, a stale, already-shut-down instance must
+    # not stay registered (it would keep serving cold slots but never warm again).
+    self.@instance: untyped
+
+    @config: untyped
+
+    @slot_factory: untyped
+
+    @mutex: untyped
+
+    @available: untyped
+
+    @replenish_threads: untyped
+
+    @warming: untyped
+
+    @shutdown: untyped
+
+    @reaper_wakeup: untyped
+
+    @reaper: untyped
+
+    # Configuration for the session warmer.
+    class Configuration
+      @size: untyped
+
+      @headless: untyped
+
+      @chrome_args: untyped
+
+      @remote_browser_url: untyped
+
+      @slot_factory: untyped
+
+      @max_idle_age: untyped
+
+      # @return [Integer] Number of Chrome slots to keep pre-warmed.
+      attr_accessor size: untyped
+
+      # @return [Boolean] Whether to run Chrome in headless mode.
+      attr_accessor headless: untyped
+
+      # @return [Array<String>] Chrome launch arguments.
+      attr_accessor chrome_args: untyped
+
+      # @return [String, nil] A remote chromedriver session URL (e.g. a `remote-chrome` sidecar). When
+      #   set, a slot connects directly to it instead of spawning a local ChromedriverManager -
+      #   mirrors Launcher#session's own local/remote branch.
+      attr_accessor remote_browser_url: untyped
+
+      # @return [#call, nil] Optional factory callable that returns a slot hash - injectable for tests.
+      #   A custom factory owns the cleanup of anything it half-built before raising: the warmer can
+      #   only retire a slot it was actually handed.
+      attr_accessor slot_factory: untyped
+
+      # @return [Numeric, nil] Seconds a warm slot may sit unused before it is retired and replaced.
+      #   A warm slot is an open, unauthenticated automation endpoint (chromedriver's port, Chrome's
+      #   debugging port) for as long as it idles, so that window is bounded by default. A slot older
+      #   than this is never handed out, and a background reaper recycles idle ones within roughly
+      #   1.25x this value even when no render ever comes. +nil+ disables the limit.
+      attr_accessor max_idle_age: untyped
+
+      DEFAULT_MAX_IDLE_AGE: 300
+
+      def initialize: () -> void
+
+      # @raise [ArgumentError] if a setting can't be honored - checked once, at construction.
+      def validate!: () -> untyped
+
+      private
+
+      def validate_size!: () -> (nil | untyped)
+
+      def validate_max_idle_age!: () -> (nil | untyped)
+    end
+
+    # Configures the warmer and eagerly (re)creates the singleton, warming config.size slots right
+    # here - at boot/configuration time, off the request path - instead of lazily on whichever
+    # request happens to trigger the first #with_tab (which would otherwise pay for every
+    # configured slot, serially, on that one unlucky request).
+    def self.configure: () ?{ (untyped) -> untyped } -> untyped
+
+    # Returns the warmer's configuration, initializing defaults if needed.
+    def self.config: () -> untyped
+
+    # Returns a callable that creates one real, fully-warmed Chrome slot from +config+. If building
+    # fails part-way (chromedriver up, but the session or its browser never came ready), whatever
+    # already exists is retired before the error propagates - no caller ever gets a reference to a
+    # half-built slot, so nobody else could clean it up.
+    def self.default_slot_factory: (untyped config) -> untyped
+
+    # Closes a slot's session and stops its chromedriver (nil for a remote slot, or for a part that
+    # was never created). Each step is independent: a failure in one is logged, never raised, and
+    # never skips the other.
+    def self.retire_slot: (session: untyped, manager: untyped) -> untyped
+
+    def self.safe_close: (untyped label) { () -> untyped } -> untyped
+
+    # Returns the shared singleton warmer instance, creating it (and pre-warming it) on first call.
+    def self.instance: () -> untyped
+
+    # Checks out a slot, yields a fresh tab for one render, then retires the slot.
+    def self.with_tab: () { (?) -> untyped } -> untyped
+
+    # Retires every currently-warm spare and resets the singleton.
+    def self.shutdown: () -> untyped
+
+    private
+
+    # Records each part in +parts+ the moment it exists, so #default_slot_factory's rescue can
+    # retire exactly what was created so far. Mirrors Launcher#session's local/remote branch.
+    def self.build_slot: (untyped config, untyped parts) -> { session: untyped, browser: untyped, manager: untyped }
+
+    def self.connect_remote: (untyped config, untyped parts) -> untyped
+
+    def self.start_local: (untyped config, untyped parts) -> untyped
+
+    public
+
+    def initialize: (untyped config, ?slot_factory: untyped?) -> void
+
+    # Checks out a slot, creates an isolated UserContext/Window/Tab for one render, yields the tab,
+    # then unconditionally closes those resources and retires the underlying slot.
+    def with_tab: () { (untyped) -> untyped } -> untyped
+
+    # Retires every currently-warm spare and waits for any in-flight background replenishment to
+    # finish (each of those, seeing @shutdown, retires its own result instead of stashing it - see
+    # #stash_or_retire). A subsequent #with_tab still works - it just falls back to a synchronous
+    # slot, since checkout never depends on a warm one being there.
+    def shutdown: () -> untyped
+
+    private
+
+    # Fail-fast on purpose (a Chrome that can't start at boot should be loud), but not leaky: if slot
+    # N fails, no instance is returned to own slots 1..N-1, so they are retired here first.
+    def prewarm: () -> untyped
+
+    def create_slot: () -> untyped
+
+    # Session#started? is just an internal flag set once at startup - it never flips back if Chrome,
+    # ChromeDriver, or the WebSocket dies externally while a slot sits idle in the cache. The
+    # client's own #open? is kept live by the reader thread noticing a real socket error, so
+    # checking it too catches that case - cheap (no network round trip), though still a heuristic,
+    # not a full liveness guarantee (a stuck-but-not-yet-disconnected socket still reads healthy).
+    def healthy?: (untyped slot) -> untyped
+
+    def now: () -> untyped
+
+    # Marks the moment a slot entered the cache - idle age counts from here, not from when its
+    # Chrome started, since it is the unattended waiting that max_idle_age bounds.
+    def stamp: (untyped slot) -> untyped
+
+    def expired?: (untyped slot) -> untyped
+
+    # Checkout alone can't bound idle time: with no traffic nothing would ever look at a spare. This
+    # thread does, four times per max_idle_age, so an unused slot is recycled within ~1.25x of it.
+    # Thread::Queue#pop(timeout:) doubles as an interruptible sleep - #shutdown pushes :stop.
+    def reap_loop: () -> untyped
+
+    def recycle_expired: () -> untyped
+
+    # A warm hit takes the spare and triggers a background replacement; a miss (empty cache, or a
+    # spare that died while idle) falls straight through to a synchronous slot - it never waits, so
+    # an under-provisioned warmer is never worse than not having one. A cold start that fails raises,
+    # as it would without the warmer.
+    #
+    # Oldest spare first (shift, not pop), so no slot lingers at the bottom of the cache while newer
+    # ones are used; and one past max_idle_age is never handed out, even if the reaper hasn't got to
+    # it yet - it is retired like a dead spare and this render cold-starts instead.
+    def checkout: () -> untyped
+
+    def cold_checkout: (untyped dead_slot) -> untyped
+
+    # Tops the cache up towards config.size, counting warmers already in flight. Deficit-based on
+    # purpose, not "replace what this checkout popped": that rule could never recover from a single
+    # failed warm (nothing stashed -> every later checkout a miss -> never replenished again), while
+    # replenishing unconditionally let @available grow without bound under a burst of misses.
+    # available + warming never exceeds config.size, and a failed warm frees its reservation, so the
+    # next checkout simply tries again.
+    #
+    # Threads are created and registered inside the same critical section, so #shutdown's snapshot
+    # can't miss one that has started but isn't listed yet (#warm_one needs this mutex to finish,
+    # so it just waits for it).
+    def replenish_async: () -> untyped
+
+    def warm_one: () -> untyped
+
+    # A replacement warmed after #shutdown has nothing to stash into - retire it immediately rather
+    # than leaking a live Chrome process that nothing will ever check out. Either way this warmer's
+    # reservation is released here, in the same critical section as the stash.
+    def stash_or_retire: (untyped slot) -> untyped
+
+    def retire: (untyped slot) -> untyped
+
+    def safe_close: (untyped label) { (?) -> untyped } -> untyped
+  end
+end

data/sig/bidi2pdf/test_helpers/testcontainers/chromedriver_test_helper.rbs

@@ -41,5 +41,5 @@ class Object
 
   def test_of_kind_present?: (untyped type) -> untyped
 
-  def start_chromedriver_container: (build_dir: untyped, mounts: untyped, shared_network: untyped) -> untyped
+  def start_chromedriver_container: (build_dir: untyped, mounts: untyped, shared_network: untyped, ?chromedriver_log_level: ::String) -> untyped
 end

data/sig/bidi2pdf/version.rbs

@@ -1,3 +1,3 @@
 module Bidi2pdf
-  VERSION: "0.1.14"
+  VERSION: "0.1.16"
 end