bidi2pdf 0.1.14 → 0.1.16

data/lib/bidi2pdf/recipe/runner.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+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
+      # 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
+        attr_reader :entries, :cause
+
+        def initialize(entries, cause)
+          @entries = entries
+          @cause = cause
+          super(cause.message)
+        end
+      end
+
+      attr_reader :state
+      attr_accessor :pdf_bytes
+
+      # @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:, tab:, collector:)
+        @recipe = recipe
+        @tab = tab
+        @collector = collector
+        @state = {}
+        @pdf_bytes = nil
+      end
+
+      # @return [Array<Hash>] one entry per action actually run
+      # @raise [StepFailure] on the first failing action
+      def run_actions
+        run_steps(@recipe.actions) { |name, step| dispatch_action(name, @recipe.step_options(step)) }
+      end
+
+      # @return [Array<Hash>] one entry per assertion actually run
+      # @raise [StepFailure] on the first failing assertion
+      def run_assertions
+        run_steps(@recipe.assertions) do |name, step|
+          ok, details = dispatch_assertion(name, step)
+          next { ok: ok, details: details } if ok
+
+          raise Bidi2pdf::PageNotAsExpectedError.new("Assertion '#{name}' failed", details: (details || {}).merge(assertion: name))
+        end
+      end
+
+      private
+
+      # rubocop:disable-next Metrics/AbcSize
+      def run_steps(steps)
+        entries = []
+
+        steps.each_with_index do |step, index|
+          name = @recipe.step_name(step)
+          start = now_ms
+
+          begin
+            outcome = yield(name, step)
+            entry = { index: index, type: name, ok: true, duration_ms: elapsed_ms(start) }
+            entry[:details] = outcome[:details] if outcome.is_a?(Hash) && outcome[:details]
+            entries << entry
+          rescue Bidi2pdf::Error => e
+            entries << { index: index, type: name, ok: false, duration_ms: elapsed_ms(start) }
+            raise StepFailure.new(entries, e)
+          end
+        end
+
+        entries
+      end
+
+      def now_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+
+      def elapsed_ms(start) = (now_ms - start).round
+
+      # --- actions ---
+
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity
+      def dispatch_action(name, opts)
+        case name
+        when "wait_for" then action_wait_for(opts)
+        when "click" then action_click(opts)
+        when "evaluate" then action_evaluate(opts)
+        when "inject_script" then @tab.inject_script(url: opts["url"], content: opts["content"], id: opts["id"])
+        when "inject_style" then @tab.inject_style(url: opts["url"], content: opts["content"], id: opts["id"])
+        when "set_viewport" then @tab.set_viewport(width: opts["width"], height: opts["height"], device_pixel_ratio: opts["device_pixel_ratio"])
+        when "wait_network_idle" then @tab.wait_until_network_idle(timeout: opts.fetch("timeout", 10))
+        end
+      end
+
+      def action_wait_for(opts)
+        timeout = opts.fetch("timeout", 10)
+        condition = wait_for_condition(opts)
+
+        script = <<~JS
+          new Promise((resolve, reject) => {
+            const deadline = Date.now() + #{(timeout.to_f * 1000).to_i};
+            const check = () => {
+              let ok;
+              try { ok = !!(#{condition}); } catch (e) { ok = false; }
+              if (ok) { resolve("done"); return; }
+              if (Date.now() >= deadline) { reject(new Error("wait_for timed out")); return; }
+              setTimeout(check, 100);
+            };
+            check();
+          });
+        JS
+
+        response = @tab.execute_script(script)
+        return if response.is_a?(Hash) && response["type"] == "success"
+
+        raise Bidi2pdf::SelectorNotFoundError.new("wait_for timed out after #{timeout}s", details: opts)
+      end
+
+      def wait_for_condition(opts)
+        return "document.querySelector('.pagedjs_page')" if opts["paged_js"]
+        return "document.querySelector(#{opts.fetch("selector").to_json})" if opts["selector"]
+        return opts.fetch("script") if opts["script"]
+
+        raise Bidi2pdf::InvalidRecipeError, "wait_for needs one of: selector, paged_js, script"
+      end
+
+      def action_click(opts)
+        selector = opts.fetch("selector") { raise Bidi2pdf::InvalidRecipeError, "click needs a selector" }
+
+        script = <<~JS
+          (function () {
+            const el = document.querySelector(#{selector.to_json});
+            if (!el) { return false; }
+            el.scrollIntoView({ block: "center" });
+            el.click();
+            return true;
+          })()
+        JS
+
+        response = @tab.execute_script(script)
+        return if response.is_a?(Hash) && response["type"] == "success" && response.dig("result", "value") == true
+
+        raise Bidi2pdf::SelectorNotFoundError.new("click: selector '#{selector}' not found", details: opts)
+      end
+
+      def action_evaluate(opts)
+        script = opts.fetch("script") { raise Bidi2pdf::InvalidRecipeError, "evaluate needs a script" }
+
+        response = @tab.execute_script(script)
+        raise Bidi2pdf::ScriptInjectionError.new("evaluate failed", details: opts) unless response.is_a?(Hash) && response["type"] == "success"
+
+        @state[opts["assign"]] = response.dig("result", "value") if opts["assign"]
+      end
+
+      # --- assertions: each returns [ok, details_or_nil] ---
+
+      # rubocop:disable-next Metrics/CyclomaticComplexity
+      def dispatch_assertion(name, step)
+        case name
+        when "selector_exists" then assertion_selector_exists(@recipe.step_options(step))
+        when "text_present" then assertion_text_present(@recipe.step_options(step))
+        when "no_console_errors" then assertion_no_console_errors
+        when "no_network_failures" then assertion_no_network_failures
+        when "fonts_loaded" then assertion_fonts_loaded
+        when "page_count" then assertion_page_count(@recipe.step_value(step))
+        when "pdf_text_present" then assertion_pdf_text_present(@recipe.step_options(step))
+        when "pdf_not_blank" then assertion_pdf_not_blank
+        end
+      end
+
+      def assertion_selector_exists(opts)
+        selector = opts.fetch("selector")
+        response = @tab.execute_script("!!document.querySelector(#{selector.to_json})")
+        [response.is_a?(Hash) && response.dig("result", "value") == true, { selector: selector }]
+      end
+
+      def assertion_text_present(opts)
+        text = opts.fetch("text")
+        response = @tab.execute_script("document.body.innerText")
+        body_text = response.is_a?(Hash) ? response.dig("result", "value").to_s : ""
+        [body_text.include?(text), { text: text }]
+      end
+
+      def assertion_no_console_errors
+        errors = @collector.console.select { |entry| entry[:level].to_s == "error" }
+        [errors.empty?, errors.empty? ? nil : { console_errors: errors }]
+      end
+
+      # 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
+        failures = @collector.network_failures
+        [failures.empty?, failures.empty? ? nil : { network_failures: failures }]
+      end
+
+      def assertion_fonts_loaded
+        response = @tab.execute_script(<<~JS)
+          document.fonts.ready.then(function () {
+            return document.fonts.ready ? !Array.from(document.fonts).some(function (f) { return f.status === "error"; }) : true;
+          })
+        JS
+        ok = response.is_a?(Hash) && response["type"] == "success" && response.dig("result", "value") != false
+        [ok, nil]
+      end
+
+      def assertion_page_count(expected)
+        actual = Bidi2pdf::PdfInspection.page_count(pdf_bytes)
+
+        ok = expected.is_a?(Hash) ? (expected["min"].nil? || actual.to_i >= expected["min"]) && (expected["max"].nil? || actual.to_i <= expected["max"]) : actual == expected
+
+        [ok, { expected: expected, actual: actual }]
+      end
+
+      def assertion_pdf_text_present(opts)
+        text = opts.fetch("text")
+        extracted = Bidi2pdf::PdfInspection.text(pdf_bytes).to_s
+        [extracted.include?(text), { text: text }]
+      end
+
+      def assertion_pdf_not_blank
+        page_count = Bidi2pdf::PdfInspection.page_count(pdf_bytes).to_i
+        text = Bidi2pdf::PdfInspection.text(pdf_bytes).to_s
+        [page_count.positive? && !text.strip.empty?, { page_count: page_count, text_present: !text.strip.empty? }]
+      end
+    end
+  end
+end

data/lib/bidi2pdf/recipe/schema_shape.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+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 # rubocop:disable Metrics/ModuleLength
+      TYPE_CHECKS = {
+        "object" => ->(v) { v.is_a?(Hash) },
+        "array" => ->(v) { v.is_a?(Array) },
+        "string" => ->(v) { v.is_a?(String) },
+        "integer" => ->(v) { v.is_a?(Integer) },
+        "number" => ->(v) { v.is_a?(Numeric) },
+        "boolean" => ->(v) { [true, false].include?(v) },
+        "null" => lambda(&:nil?)
+      }.freeze
+
+      CHECKS = %i[const_ok? enum_ok? type_ok? one_of_ok? any_of_ok? required_ok? additional_properties_ok? properties_ok? items_ok? bounds_ok?].freeze
+
+      module_function
+
+      # @return [Boolean] whether value satisfies schema
+      def matches?(schema, value)
+        CHECKS.all? { |check| public_send(check, schema, value) }
+      end
+
+      VIOLATION_CHECKS = %i[
+        oneof_violation anyof_violation required_violation additional_properties_violation const_violation enum_violation type_violation
+        bounds_violation nested_violation
+      ].freeze
+
+      # @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 first_violation(schema, value, path = [])
+        return nil if matches?(schema, value)
+
+        VIOLATION_CHECKS.each do |check|
+          found = public_send(check, schema, value, path)
+          return found if found
+        end
+
+        { path: display_path(path), reason: "does not match the schema" }
+      end
+
+      def const_ok?(schema, value)
+        !schema.key?("const") || schema["const"] == value
+      end
+
+      def enum_ok?(schema, value)
+        !schema.key?("enum") || schema["enum"].include?(value)
+      end
+
+      def type_ok?(schema, value)
+        types = Array(schema["type"])
+        return true if types.empty?
+
+        types.any? { |t| TYPE_CHECKS.fetch(t).call(value) }
+      end
+
+      def one_of_ok?(schema, value)
+        return true unless schema["oneOf"]
+
+        schema["oneOf"].one? { |branch| matches?(branch, value) }
+      end
+
+      def any_of_ok?(schema, value)
+        return true unless schema["anyOf"]
+
+        schema["anyOf"].any? { |branch| matches?(branch, value) }
+      end
+
+      def required_ok?(schema, value)
+        return true unless schema["required"] && value.is_a?(Hash)
+
+        schema["required"].all? { |key| value.key?(key) }
+      end
+
+      def additional_properties_ok?(schema, value)
+        return true unless schema["additionalProperties"] == false && value.is_a?(Hash)
+
+        (value.keys - (schema["properties"] || {}).keys).empty?
+      end
+
+      def properties_ok?(schema, value)
+        return true unless schema["properties"] && value.is_a?(Hash)
+
+        schema["properties"].all? { |key, sub_schema| !value.key?(key) || matches?(sub_schema, value[key]) }
+      end
+
+      def items_ok?(schema, value)
+        return true unless schema["items"] && value.is_a?(Array)
+
+        value.all? { |item| matches?(schema["items"], item) }
+      end
+
+      def bounds_ok?(schema, value)
+        return true unless value.is_a?(Numeric)
+
+        (!schema["minimum"] || value >= schema["minimum"]) && (!schema["maximum"] || value <= schema["maximum"])
+      end
+
+      def display_path(path)
+        path.each_with_object(+"") do |seg, str|
+          str << (if seg.start_with?("[")
+                    seg
+                  else
+                    (str.empty? ? seg : ".#{seg}")
+                  end)
+        end
+      end
+
+      # 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 oneof_violation(schema, value, path)
+        return nil unless schema["oneOf"]
+
+        matching = schema["oneOf"].select { |branch| matches?(branch, value) }
+        return nil if matching.size == 1
+
+        (matching.empty? && single_plausible_violation(schema, value, path)) ||
+          { path: display_path(path), reason: "must match exactly one of #{schema["oneOf"].size} known shapes (matched #{matching.size})" }
+      end
+
+      def single_plausible_violation(schema, value, path)
+        plausible = schema["oneOf"].select { |branch| required_ok?(branch, value) }
+        return nil unless plausible.size == 1
+
+        first_violation(plausible.first, value, path)
+      end
+
+      def anyof_violation(schema, value, path)
+        return nil unless schema["anyOf"]
+        return nil if schema["anyOf"].any? { |branch| matches?(branch, value) }
+
+        { path: display_path(path), reason: "must match at least one of #{schema["anyOf"].size} known shapes" }
+      end
+
+      def required_violation(schema, value, path)
+        return nil unless schema["required"] && value.is_a?(Hash)
+
+        missing = schema["required"] - value.keys
+        return nil if missing.empty?
+
+        { path: display_path(path), reason: "missing required key(s): #{missing.join(", ")}" }
+      end
+
+      def additional_properties_violation(schema, value, path)
+        return nil unless schema["additionalProperties"] == false && value.is_a?(Hash)
+
+        extra = value.keys - (schema["properties"] || {}).keys
+        return nil if extra.empty?
+
+        { path: display_path(path), reason: "unknown key(s): #{extra.join(", ")}" }
+      end
+
+      def const_violation(schema, value, path)
+        return nil unless schema.key?("const") && schema["const"] != value
+
+        { path: display_path(path), reason: "must equal #{schema["const"].inspect}" }
+      end
+
+      def enum_violation(schema, value, path)
+        return nil unless schema["enum"] && !schema["enum"].include?(value)
+
+        { path: display_path(path), reason: "must be one of #{schema["enum"].inspect}" }
+      end
+
+      def type_violation(schema, value, path)
+        return nil if type_ok?(schema, value)
+
+        { path: display_path(path), reason: "expected type #{Array(schema["type"]).join(" or ")}" }
+      end
+
+      def bounds_violation(schema, value, path)
+        return nil unless value.is_a?(Numeric)
+        return { path: display_path(path), reason: "must be >= #{schema["minimum"]}" } if schema["minimum"] && value < schema["minimum"]
+        return { path: display_path(path), reason: "must be <= #{schema["maximum"]}" } if schema["maximum"] && value > schema["maximum"]
+
+        nil
+      end
+
+      def nested_violation(schema, value, path)
+        properties_violation(schema, value, path) || items_violation(schema, value, path)
+      end
+
+      def properties_violation(schema, value, path)
+        return nil unless schema["properties"] && value.is_a?(Hash)
+
+        schema["properties"].each do |key, sub_schema|
+          next unless value.key?(key)
+
+          found = first_violation(sub_schema, value[key], path + [key])
+          return found if found
+        end
+
+        nil
+      end
+
+      def items_violation(schema, value, path)
+        return nil unless schema["items"] && value.is_a?(Array)
+
+        value.each_with_index do |item, index|
+          found = first_violation(schema["items"], item, path + ["[#{index}]"])
+          return found if found
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/bidi2pdf/recipe/validator.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+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
+      def initialize(recipe)
+        @recipe = recipe
+      end
+
+      def validate!
+        check_version
+        check_top_level_keys
+        check_source
+        check_steps("actions", @recipe.actions, Recipe::KNOWN_ACTIONS)
+        check_steps("assert", @recipe.assertions, Recipe::KNOWN_ASSERTIONS)
+        check_wait_for_conditions
+        check_presence_assertions
+        check_pdf_assertions_need_pdf_inspection
+        check_output
+        check_print_options
+        check_shape
+      end
+
+      private
+
+      def check_version
+        return if @recipe.data["version"] == 1
+
+        fail!("version must be 1", path: "version")
+      end
+
+      def check_top_level_keys
+        unknown = @recipe.data.keys.map(&:to_s) - Recipe::KNOWN_TOP_LEVEL_KEYS
+        return if unknown.empty?
+
+        fail!("Unknown top-level key '#{unknown.first}'. Known keys: #{Recipe::KNOWN_TOP_LEVEL_KEYS.join(", ")}", path: unknown.first)
+      end
+
+      def check_source
+        given = %w[url file stdin].select { |key| @recipe.source[key] }
+
+        fail!("source must specify exactly one of url, file, stdin", path: "source") unless given.size == 1
+      end
+
+      def check_steps(section, steps, known)
+        steps.each_with_index do |step, index|
+          name = @recipe.step_name(step)
+          next if known.include?(name)
+
+          fail!("Unknown #{section == "actions" ? "action" : "assertion"} '#{name}'. Known: #{known.join(", ")}", path: "#{section}[#{index}].#{name}")
+        end
+      end
+
+      # 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
+        @recipe.actions.each_with_index do |step, index|
+          next unless @recipe.step_name(step) == "wait_for"
+
+          given = %w[selector paged_js script] & @recipe.step_options(step).keys
+
+          next if given.size == 1
+
+          fail!("wait_for needs exactly one of selector, paged_js, script (got: #{given.empty? ? "none" : given.join(", ")})",
+                path: "actions[#{index}].wait_for")
+        end
+      end
+
+      # 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
+        @recipe.assertions.each_with_index do |step, index|
+          name = @recipe.step_name(step)
+          next unless Recipe::PRESENCE_ONLY_ASSERTIONS.include?(name)
+          next if @recipe.step_value(step) == true
+
+          fail!("#{name} must be true - a false or missing value is misleading; omit the assertion instead", path: "assert[#{index}].#{name}")
+        end
+      end
+
+      def check_pdf_assertions_need_pdf_inspection
+        return if Bidi2pdf::PdfInspection.available?
+
+        @recipe.assertions.each_with_index do |assertion, index|
+          name = @recipe.step_name(assertion)
+          next unless Recipe::PDF_ASSERTIONS.include?(name)
+
+          raise Bidi2pdf::PdfInspectionUnavailableError.new(
+            "assert[#{index}].#{name} requires the pdf-reader gem",
+            details: { path: "assert[#{index}].#{name}", reason: "requires the pdf-reader gem" }
+          )
+        end
+      end
+
+      def check_output
+        return if Recipe::KNOWN_OUTPUTS.intersect?(@recipe.output.keys.map(&:to_s))
+
+        fail!("output must specify at least one of #{Recipe::KNOWN_OUTPUTS.join(", ")}", path: "output")
+      end
+
+      def check_print_options
+        return if @recipe.print_options.empty?
+
+        Bidi2pdf::Bidi::Commands::PrintParametersValidator.validate!(symbolize(@recipe.print_options))
+      rescue ArgumentError => e
+        raise Bidi2pdf::InvalidPrintOptionError.new("Invalid print option: #{e.message}", details: { path: "print" })
+      end
+
+      def symbolize(hash)
+        hash.to_h { |key, value| [key.to_sym, value] }
+      end
+
+      # 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
+        violation = SchemaShape.first_violation(Bidi2pdf::Schema::RECIPE, @recipe.data)
+        return unless violation
+
+        fail!(violation[:reason], path: violation[:path])
+      end
+
+      def fail!(reason, path:)
+        raise Bidi2pdf::InvalidRecipeError.new(reason, details: { path: path, reason: reason })
+      end
+    end
+  end
+end

data/lib/bidi2pdf/recipe.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "recipe/schema_shape"
+require_relative "recipe/loader"
+require_relative "recipe/validator"
+require_relative "recipe/runner"
+
+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
+    KNOWN_TOP_LEVEL_KEYS = %w[version source browser headers cookies auth actions assert print output].freeze
+    KNOWN_ACTIONS = %w[wait_for click evaluate inject_script inject_style set_viewport wait_network_idle].freeze
+    PAGE_ASSERTIONS = %w[selector_exists text_present no_console_errors no_network_failures fonts_loaded].freeze
+    PDF_ASSERTIONS = %w[page_count pdf_text_present pdf_not_blank].freeze
+    KNOWN_ASSERTIONS = (PAGE_ASSERTIONS + PDF_ASSERTIONS).freeze
+    KNOWN_OUTPUTS = %w[pdf manifest screenshot].freeze
+    # 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 = %w[no_console_errors no_network_failures fonts_loaded pdf_not_blank].freeze
+
+    attr_reader :data, :path
+
+    def self.load(path)
+      new(Loader.load(path), path: path)
+    end
+
+    def initialize(data, path: nil)
+      @data = data
+      @path = path
+    end
+
+    def validate!
+      Validator.new(self).validate!
+    end
+
+    def actions = Array(@data["actions"])
+
+    def assertions = Array(@data["assert"])
+
+    def source = @data["source"] || {}
+
+    def browser_options = @data["browser"] || {}
+
+    def headers = @data["headers"] || {}
+
+    def cookies = @data["cookies"] || {}
+
+    def auth = @data["auth"]
+
+    def print_options = @data["print"] || {}
+
+    def output = @data["output"] || {}
+
+    def needs_pdf?
+      !!output["pdf"] || assertions.any? { |assertion| PDF_ASSERTIONS.include?(step_name(assertion)) }
+    end
+
+    def self.step_name(step)
+      step.is_a?(Hash) ? step.keys.first.to_s : step.to_s
+    end
+
+    def step_name(step) = self.class.step_name(step)
+
+    # 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(step)
+      step.is_a?(Hash) ? step.values.first : nil
+    end
+
+    # 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(step)
+      value = step_value(step)
+      value.is_a?(Hash) ? value : {}
+    end
+  end
+end