stationery 0.12.0 → 0.12.2

data/lib/stationery/skill/recipes/report.md.erb

@@ -6,6 +6,8 @@ the footer, a table that continues across pages and a chart. The examples in the
 `stationery examples accessible_report --source` (PDF/UA-1, a chart as a figure).
 
 ```ruby
+require "erb"                                          # ERB::Util.html_escape, for data written into SVG
+
 class ReportPdf < Stationery::Document
   ACCENT = "#0F766E"
   MUTED = "#6B7280"
@@ -63,14 +65,15 @@ class ReportPdf < Stationery::Document
     spacer 8
   end
 
-  # A bar chart as SVG, drawn from the data: there is no chart element.
+  # A bar chart as SVG, drawn from the data: there is no chart element. Text
+  # from the data is escaped, as "&" or "<" in it would break the XML.
   def chart
     top = @quarters.map(&:last).max
     bars = @quarters.each_with_index.map do |(label, value), i|
       height = (value / top * 150).round(1)
       x = 30 + (i * 110)
       %(<rect x="#{x}" y="#{170 - height}" width="70" height="#{height}" fill="currentColor"/>) +
-        %(<text x="#{x + 35}" y="190" font-size="12" text-anchor="middle">#{label}</text>) +
+        %(<text x="#{x + 35}" y="190" font-size="12" text-anchor="middle">#{ERB::Util.html_escape(label)}</text>) +
         %(<text x="#{x + 35}" y="#{164 - height}" font-size="11" text-anchor="middle">#{value}</text>)
     end
     %(<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 200">#{bars.join}</svg>)
@@ -91,13 +94,15 @@ end
   same page. `heading: 1..6` makes a heading in a tagged PDF; do not skip a level (1, then 3).
 - **Long tables** continue on the next page with `header: true` rows repeated; a row never splits
   unless it is taller than a page (or `split_rows: true`). Rows given as an Enumerator
-  (`Order.find_each.lazy.map { |o| [o.number, o.total] }`) to a table with a width for every
+  (`Order.preload(:customer).find_each.lazy.map { |o| [o.number, o.customer.name, o.total] }`,
+  preloading what each row reads) to a table with a width for every
   column (`widths: [80, 0.5, 90]`) are read as pages reach them, so the rows of about a page are
   held at a time, however many there are; such a table selects rows from its start only (`t.row(0)`, `t.rows(1..)`,
   `zebra`), and none of its cells may span rows. With a column without a width the rows are read
   when the table is built.
 - **Charts are SVG or `canvas`.** Build the SVG from the data as above (`currentColor` takes
-  `color:`, `<text>` is set in the document's fonts). An `svg` is drawn at its viewBox size in
+  `color:`, `<text>` is set in the document's fonts), and escape every string from the data with
+  `ERB::Util.html_escape`: an "&" or "<" in a label breaks the SVG or adds elements to it. An `svg` is drawn at its viewBox size in
   points, shrunk to the width there is; `width:` is points (`width: 1.0` is one point, not the
   whole width). Or draw the shapes on a canvas (its `text` takes a font object, so label a canvas
   chart with SVG or with `text` elements around it):

data/lib/stationery/testing/inspector.rb

@@ -10,8 +10,9 @@ require_relative "layout"
 module Stationery
   module Testing
     # Reads a rendered PDF back for assertions. The subject is a
-    # Stationery::Document, PDF bytes, a path (String or Pathname) or an IO.
-    # Needs the pdf-reader gem, loaded on first use.
+    # Stationery::Document, PDF bytes, a path (String or Pathname) or an IO;
+    # `password:` opens an encrypted one. Needs the pdf-reader gem, loaded on
+    # first use.
     class Inspector
       UTF16_BOM = "\xFE\xFF".b
       # id-aa-signatureTimeStampToken: a signature's RFC 3161 timestamp.
@@ -23,9 +24,11 @@ module Stationery
       COLOR_OPERATORS = { "g" => 1, "G" => 1, "rg" => 3, "RG" => 3, "k" => 4, "K" => 4 }.freeze
       NUMBER = /\A[-+]?(?:\d+\.?\d*|\.\d+)\z/
       LITERAL_STRING = /\((?:\\.|[^\\()])*\)/m
+      NEEDS_READER = 'Stationery::Testing needs pdf-reader: add gem "pdf-reader" to your test group'
 
-      def initialize(subject)
+      def initialize(subject, password: nil)
         @subject = subject
+        @password = password
       end
 
       def pdf
@@ -40,9 +43,9 @@ module Stationery
       def reader
         @reader ||= begin
           require "pdf/reader"
-          ::PDF::Reader.new(StringIO.new(pdf))
+          ::PDF::Reader.new(StringIO.new(pdf), **{ password: @password }.compact)
         rescue LoadError
-          raise Stationery::Error, 'Stationery::Testing needs pdf-reader: add gem "pdf-reader" to your test group'
+          raise Stationery::Error, NEEDS_READER
         end
       end
 

data/lib/stationery/testing/layout.rb

@@ -18,6 +18,9 @@ module Stationery
       # The Radio and Pushbutton flags of a button field's /Ff.
       RADIO = 1 << 15
       PUSHBUTTON = 1 << 16
+      ALIGNMENTS = %i[left center right].freeze
+      # The font size and colour operator of a /DA: "/F1 10 Tf 0.5 g".
+      DEFAULT_APPEARANCE = /([\d.]+) Tf\s+((?:-?[\d.]+\s+)+)(g|rg|k)\s*\z/
 
       def initialize(inspector)
         @inspector = inspector
@@ -98,10 +101,24 @@ module Stationery
           name = chain.filter_map { |field| field[:T] && decode(field[:T]) }.reverse.join(".")
           type = inherit(chain, :FT)
           { name:, type: field_type(type, inherit(chain, :Ff).to_i), value: value(inherit(chain, :V)),
-            **rect(widget, left, top), state: state(widget) }.compact
+            **rect(widget, left, top), state: state(widget), **style(chain) }.compact
         end
       end
 
+      # The alignment, size (:auto for 0) and colour a field's value is
+      # drawn in; nothing for a field without variable text.
+      def style(chain)
+        match = DEFAULT_APPEARANCE.match(inherit(chain, :DA).to_s) or return {}
+
+        size, values, operator = match.captures
+        values = values.split.map(&:to_f)
+        values *= 3 if operator == "g"
+        { align: ALIGNMENTS.fetch(inherit(chain, :Q).to_i, :left), font_size: size.to_f.zero? ? :auto : number(size),
+          color: Monochrome.hex(Color.new(operator == "k" ? :cmyk : :rgb, values)) }
+      end
+
+      def number(text) = text.include?(".") ? text.to_f : text.to_i
+
       def parents(widget)
         chain = [widget]
         chain << @objects.deref_hash(chain.last[:Parent]) while chain.last[:Parent] && chain.size < 32

data/lib/stationery/verify/allowlist.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    # The engine messages that are the check's environment and not the PDF:
+    # each names the engine, a pattern and why. Everything else an engine
+    # says fails the check. An entry is added only once the cause is found
+    # in the engine's source and the file; a file that lacks what a viewer
+    # needs is a bug in the gem, not an entry here.
+    module Allowlist
+      ENTRIES = [
+        { engine: "pdfjs", pattern: /\AWarning: _getAppearance: OffscreenCanvas is not supported/,
+          why: "Node has no OffscreenCanvas. pdf.js builds a text field's appearance again when the form sets " \
+               "/NeedAppearances, which Forms::AcroForm does for a form that is neither signed nor PDF/A or " \
+               "PDF/UA, and warns whenever it builds one without OffscreenCanvas. Every widget carries its /AP." },
+        { engine: "poppler", pattern: /\ANSS_Init failed: security library: bad database\.\z/,
+          why: "pdfsig opens an NSS certificate database to judge trust, and says so when the machine has none " \
+               "(~/.pki/nssdb). Whether the signature verifies does not need it." },
+        { engine: "mupdf", pattern: /\Awarning: ICC support is not available\z/,
+          why: "Debian's mutool (mupdf-tools, in the verify image) is built without colour management and says so " \
+               "before it opens any file, even one that is not a PDF." }
+      ].freeze
+
+      def self.allows?(entries, engine, message)
+        entries.any? { |entry| entry[:engine] == engine && entry[:pattern].match?(message) }
+      end
+    end
+  end
+end

data/lib/stationery/verify/command.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "tmpdir"
+
+module Stationery
+  module Verify
+    # Runs an engine's tool: an argument array, never through a shell, its
+    # output written to files as it runs (so a large one cannot block it),
+    # in `chdir` (the temporary directory unless asked: a tool that loads
+    # modules from where it runs must not load a checked file's neighbours),
+    # and its process group killed when it takes longer than `timeout`
+    # seconds (swift runs the compiled script as a child of its own).
+    module Command
+      POLL = 0.01 # seconds between looks at a running child
+
+      # `timeout` is the seconds the tool was given.
+      Result = Data.define(:stdout, :stderr, :status, :timed_out, :timeout) do
+        def success? = !timed_out && status&.success? == true
+        def exitstatus = status&.exitstatus
+      end
+
+      def self.run(*argv, env: {}, timeout: 60, chdir: Dir.tmpdir)
+        Tempfile.create("stationery-verify-out") do |out|
+          Tempfile.create("stationery-verify-err") do |err|
+            status, timed_out = spawn(argv, env:, timeout:, chdir:, out:, err:)
+            Result.new(stdout: read(out), stderr: read(err), status:, timed_out:, timeout:)
+          rescue SystemCallError => e # the program could not start: that tool's failure, not the run's
+            Result.new(stdout: "", stderr: "#{e.message}\n", status: nil, timed_out: false, timeout:)
+          end
+        end
+      end
+
+      def self.spawn(argv, env:, timeout:, chdir:, out:, err:)
+        # [program, argv0] never goes through a shell, whatever argv holds.
+        pid = Process.spawn(env, [argv.first, argv.first], *argv.drop(1), in: File::NULL, out:, err:, chdir:,
+                                                                          pgroup: true)
+        waited = wait(pid, timeout)
+      ensure
+        kill(pid) if pid && !waited
+      end
+
+      # What a tool wrote, as UTF-8 with anything that is not replaced.
+      def self.read(file) = File.read(file.path, encoding: Encoding::UTF_8).scrub
+
+      # The executable `name` on the PATH (or at `name`, a path from the
+      # working directory, answered absolute), or nil.
+      def self.which(name)
+        if name.include?(File::SEPARATOR)
+          path = File.expand_path(name)
+          return (path if File.file?(path) && File.executable?(path))
+        end
+
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).map { |dir| File.join(dir, name) }
+           .find { |path| File.file?(path) && File.executable?(path) }
+      end
+
+      def self.wait(pid, timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        loop do
+          _, status = Process.waitpid2(pid, Process::WNOHANG)
+          return [status, false] if status
+
+          break if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+          sleep POLL
+        end
+        [kill(pid), true]
+      end
+
+      # Kills the child's process group and answers the child's status.
+      def self.kill(pid)
+        Process.kill(:KILL, -pid)
+        Process.waitpid2(pid).last
+      rescue Errno::ESRCH, Errno::ECHILD
+        nil # it was gone already
+      end
+    end
+  end
+end

data/lib/stationery/verify/comparison.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    # Holds one engine's facts about a file (see Verify) against the
+    # Expectation and answers the problems, as lines a person reads. A fact
+    # the engine does not report (nil) is not held to anything; one it does
+    # report is held to the expectation.
+    #
+    # Text is "found", not "equal": both sides are normalized the same way
+    # (NFKC, no whitespace, no soft hyphens), then each of the expectation's
+    # lines for a page must appear in the engine's text for that page. Every
+    # error and warning is a problem unless the allowlist names it.
+    class Comparison
+      IGNORED = /[[:space:]\u00AD]/
+      # A list's marker: 1. 10) a. iv) or a bullet.
+      MARKER = /\A(?:\d{1,3}|[a-z]|[ivxlcdm]{1,6})[.)]\z|\A[\u2022\u25E6\u25AA\u2023\u2013\u2014*-]\z/i
+      MARKER_PREFIX = /\A(?:(?:\d{1,3}|[a-z]|[ivxlcdm]{1,6})[.)]|[\u2022\u25E6\u25AA\u2023\u2013\u2014*-])/i
+      SHOWN = 5 # text lines not found named on a page; the rest are counted
+      BARE_ORIGIN = %r{\A(https?://[^/?#]+)\z}i
+
+      def initialize(expectation, facts, engine:, allowlist: Allowlist::ENTRIES)
+        @expectation = expectation
+        @facts = facts
+        @engine = engine.to_s
+        @allowlist = allowlist
+      end
+
+      def problems
+        [*messages("errors", "error"), *messages("warnings", "warning"), *page_count, *pages, *fonts, *fields,
+         *listed("outline", @expectation.outline, ordered: true),
+         *listed("attachments", @expectation.attachments, ordered: false),
+         *signatures, *structure]
+      end
+
+      private
+
+      def messages(key, label)
+        Array(@facts[key]).uniq.reject { |message| Allowlist.allows?(@allowlist, @engine, message) }
+                          .map { |message| "#{label}: #{message}" }
+      end
+
+      def read_pages = Array(@facts["pages"])
+
+      def page_count
+        count = read_pages.size
+        expected = @expectation.pages.size
+        count == expected ? [] : ["#{count} pages, expected #{expected}"]
+      end
+
+      def pages
+        @expectation.pages.zip(read_pages).flat_map do |expected, read|
+          next [] unless read
+
+          [*text(expected, read["text"]), *painted(expected, read["painted"]), *links(expected, read["links"])]
+            .map { |problem| "page #{expected.number}: #{problem}" }
+        end
+      end
+
+      def text(expected, text)
+        return [] if text.nil?
+
+        found = normalize(text)
+        items = expected.lines.filter_map { |line| split_marker(line)[1] }
+        missing = expected.lines.reject { |line| found?(found, line, items) }
+        more = missing.size > SHOWN ? ["text not found: #{missing.size - SHOWN} more lines"] : []
+        missing.first(SHOWN).map { |line| "text not found: #{line.inspect}" } + more
+      end
+
+      # A line is found whole, or, when it starts with a list's marker, as
+      # the rest found whole with the marker right after it, or before it
+      # with nothing between them but other markers and other items of the
+      # page. The page draws a marker apart from its item (its own Lbl, its
+      # own colour) and an engine may read the markers as a column of their
+      # own (PDFKit on macOS 26: "1. 2. 3. First… Second… Third…").
+      def found?(found, line, items = [])
+        return true if whole?(found, normalize(line))
+
+        marker, rest = split_marker(line)
+        rest ? marked?(found, marker, rest, items) : false
+      end
+
+      # [marker, rest], normalized, for a line that starts with a marker.
+      def split_marker(line)
+        marker, rest = line.strip.split(/[[:space:]]+/, 2)
+        rest && marker.match?(MARKER) ? [normalize(marker), normalize(rest)] : []
+      end
+
+      def marked?(found, marker, rest, items)
+        offsets(found, rest).any? do |start|
+          found[start + rest.size, marker.size] == marker ||
+            offsets(found[0...start], marker).any? { |at| list?(found[(at + marker.size)...start], items) }
+        end
+      end
+
+      # Whether `gap` is made of markers and the items of the page's lists,
+      # every way of reading it tried (an item may start with something
+      # shaped like a marker: "3.5 mm screws"), each offset once.
+      def list?(gap, items, from = 0, seen = {})
+        return true if from == gap.size
+        return false if seen[from]
+
+        seen[from] = true
+        rest = gap[from..]
+        steps = [rest[MARKER_PREFIX], *items.select { |item| !item.empty? && rest.start_with?(item) }].compact
+        steps.any? { |step| list?(gap, items, from + step.size, seen) }
+      end
+
+      def offsets(text, part) = text.enum_for(:scan, part).map { Regexp.last_match.begin(0) }
+
+      # A line that ends in a hyphen is found without it too: an engine may
+      # join a word broken across lines (pdftotext does).
+      def whole?(found, line) = found.include?(line) || (line.end_with?("-") && found.include?(line.chomp("-")))
+
+      def normalize(text) = text.unicode_normalize(:nfkc).gsub(IGNORED, "")
+
+      def painted(expected, painted)
+        painted == false && expected.content ? ["painted blank, but it has content"] : []
+      end
+
+      def links(expected, links)
+        return [] if links.nil?
+
+        read = links.map { |link| target(link.transform_keys(&:to_sym)) }
+        count = read.size == expected.links.size ? [] : ["#{read.size} links, expected #{expected.links.size}"]
+        missing = expected.links.reject(&:empty?).reject do |link|
+          index = read.index(target(link))
+          read.delete_at(index) if index
+        end
+        count + missing.map { |link| "link not found: #{link.inspect}" }
+      end
+
+      # A web address with no path is the same with the "/" pdf.js adds.
+      def target(link) = link[:uri] ? { uri: link[:uri].sub(BARE_ORIGIN, '\\1/') } : link
+
+      def fonts
+        Array(@facts["fonts"]).flat_map do |font|
+          [("font #{font["name"]} is not embedded" if font["embedded"] == false),
+           ("font #{font["name"]} has no ToUnicode" if font["unicode"] == false)].compact
+        end
+      end
+
+      def fields
+        read = @facts["fields"]
+        return [] if read.nil?
+
+        @expectation.fields.flat_map do |field|
+          widgets = read.select { |widget| widget["name"] == field[:name] }
+          next ["field #{field[:name]} not found"] if widgets.empty?
+
+          [*value(field, widgets), *appearance(field, widgets)]
+        end
+      end
+
+      def appearance(field, widgets)
+        return [] unless field[:visible] && widgets.any? { |widget| widget["appearance"] == false }
+
+        ["field #{field[:name]} has no appearance"]
+      end
+
+      def value(field, widgets)
+        return [] unless field[:type] == :text && field[:value].is_a?(String)
+
+        values = widgets.filter_map { |widget| widget["value"] }
+        values.reject { it == field[:value] }.first(1).map do |value|
+          "field #{field[:name]} holds #{value.inspect}, expected #{field[:value].inspect}"
+        end
+      end
+
+      def listed(key, expected, ordered:)
+        read = @facts[key]
+        return [] if read.nil? || (ordered ? read == expected : read.sort == expected.sort)
+
+        ["#{key} #{read.inspect}, expected #{expected.inspect}"]
+      end
+
+      def signatures
+        read = @facts["signatures"]
+        return [] if read.nil?
+
+        expected = @expectation.signatures
+        count = read["count"] == expected ? [] : ["#{read["count"]} signatures, expected #{expected}"]
+        count + (read["valid"] == false ? ["a signature does not verify"] : [])
+      end
+
+      def structure
+        @facts["structure"] == false && @expectation.tagged ? ["no structure tree, but the file is tagged"] : []
+      end
+    end
+  end
+end

data/lib/stationery/verify/engine.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+require "tempfile"
+require "tmpdir"
+
+module Stationery
+  module Verify
+    # What every engine adapter answers: its `name`, the line that
+    # installs it, whether it is `available?`, its `version`, and
+    # `facts(paths, password:)`, one Hash of facts per path (see Verify).
+    class Engine
+      TIMEOUT = 60 # seconds for each file
+
+      def name = self.class::NAME
+      def install = self.class::INSTALL
+
+      private
+
+      def run(*argv, env: {}, timeout: TIMEOUT, **) = Command.run(*argv, env:, timeout:, **)
+
+      def failed(path, message) = { "file" => path, "pages" => [], "errors" => [message], "warnings" => [] }
+
+      # Why a tool failed, from its result: timed out, or its exit status
+      # and the last lines it wrote to stderr.
+      def failure(tool, result)
+        return "#{tool} timed out after #{result.timeout} s" if result.timed_out
+
+        ended = result.exitstatus ? "exited #{result.exitstatus}" : "did not finish"
+        ["#{tool} #{ended}", *result.stderr.lines.last(3).map(&:strip)].join(": ")
+      end
+
+      def lines(text) = text.to_s.lines.map(&:strip).reject(&:empty?)
+
+      # Whether a binary PGM (P5, 8-bit) has a pixel that is not white.
+      def painted?(pgm)
+        header = pgm.match(/\AP5\s+(\d+)\s+(\d+)\s+(\d+)\s/n) or return false
+        width = header[1].to_i
+        height = header[2].to_i
+        pixels = pgm.byteslice(header[0].bytesize, width * height).to_s
+        pixels.count("\xFF".b) != pixels.bytesize
+      end
+
+      # Runs a script that prints one JSON line of facts per path; a path
+      # the script did not answer for fails with why the script stopped.
+      def scripted(argv, paths, env:)
+        result = run(*argv, *paths, env:, timeout: (TIMEOUT * paths.size) + TIMEOUT)
+        answers = lines(result.stdout).select { |line| line.start_with?("{") }.filter_map { |line| parse(line) }
+        read = answers.to_h { |facts| [facts["file"], facts] }
+        paths.map { |path| read.fetch(path) { failed(path, failure(argv.first, result)) } }
+      end
+
+      # A line that is not JSON answers for no file, which then fails.
+      def parse(line)
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def password_env(password) = password ? { "STATIONERY_VERIFY_PASSWORD" => password } : {}
+    end
+  end
+end

data/lib/stationery/verify/engines/mupdf.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    module Engines
+      # MuPDF (`mutool draw`): each page drawn in grey and as text. What it
+      # writes on stderr fails the check. mutool takes a password on its
+      # command line only, where other local processes can read it.
+      class Mupdf < Engine
+        NAME = "mupdf"
+        INSTALL = "brew install mupdf, or apt-get install mupdf-tools"
+
+        def available? = !Command.which("mutool").nil?
+        def version = "mutool #{run("mutool", "-v").stderr[/\d+(\.\d+)+/]}"
+
+        def facts(paths, password: nil)
+          paths.map { |path| Dir.mktmpdir("stationery-verify") { |dir| read(path, password, dir) } }
+        end
+
+        private
+
+        def read(path, password, dir)
+          options = password ? ["-p", password] : []
+          draws = %w[pgm txt].map do |format|
+            run("mutool", "draw", "-q", *options, "-r", "36", "-F", format, "-o", File.join(dir, "p%d.#{format}"), path)
+          end
+          errors = draws.reject(&:success?).map { |draw| failure("mutool draw", draw) }
+          { "file" => path, "pages" => pages(dir), "errors" => errors,
+            "warnings" => draws.flat_map { |draw| lines(draw.stderr) }.uniq }
+        end
+
+        # The pages MuPDF drew, in order, each with its picture and its text.
+        def pages(dir)
+          pictures = Dir[File.join(dir, "p*.pgm")].sort_by { |file| file[/(\d+)\.pgm\z/, 1].to_i }
+          pictures.map.with_index(1) do |picture, number|
+            text = File.join(dir, "p#{number}.txt")
+            { "number" => number, "painted" => painted?(File.binread(picture)),
+              "text" => File.exist?(text) ? File.read(text, encoding: Encoding::UTF_8) : nil }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stationery/verify/engines/pdfium.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    module Engines
+      # PDFium, the engine of Chrome and Edge, through pypdfium2 and
+      # scripts/pdfium.py. STATIONERY_PYTHON names the Python that has it.
+      class Pdfium < Engine
+        NAME = "pdfium"
+        INSTALL = "pip install pypdfium2 (STATIONERY_PYTHON names the Python that has it)"
+        SCRIPT = File.expand_path("../scripts/pdfium.py", __dir__)
+        VERSION = "import pypdfium2.version as v; print(v.PYPDFIUM_INFO, v.PDFIUM_INFO)"
+
+        # -P everywhere: Python loads no module from beside the script or from
+        # the working directory, and still finds a pip install --user.
+        def available? = !Command.which(python).nil? && run(python, "-P", "-c", "import pypdfium2").success?
+
+        def version
+          versions = run(python, "-P", "-c", VERSION).stdout.split
+          "pypdfium2 #{versions[0]}, PDFium #{versions[1]}"
+        end
+
+        def facts(paths, password: nil) = scripted([python, "-P", SCRIPT], paths, env: password_env(password))
+
+        private
+
+        # Absolute: the tools run in the temporary directory.
+        def python
+          name = ENV.fetch("STATIONERY_PYTHON", "python3")
+          name.include?(File::SEPARATOR) ? File.expand_path(name) : name
+        end
+      end
+    end
+  end
+end

data/lib/stationery/verify/engines/pdfjs.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    module Engines
+      # pdf.js, the engine of Firefox, through Node, pdfjs-dist and
+      # scripts/pdfjs.mjs. STATIONERY_PDFJS names pdfjs-dist's directory;
+      # without it, the one Node resolves from the working directory, whose
+      # code then runs: set STATIONERY_PDFJS where that directory is not yours.
+      class Pdfjs < Engine
+        NAME = "pdfjs"
+        INSTALL = "npm i pdfjs-dist (STATIONERY_PDFJS names its directory)"
+        SCRIPT = File.expand_path("../scripts/pdfjs.mjs", __dir__)
+        RESOLVE = "console.log(require('path').dirname(require.resolve('pdfjs-dist/package.json')))"
+
+        def available? = !directory.nil?
+        def version = "pdfjs-dist #{JSON.parse(File.read(File.join(directory, "package.json")))["version"]}"
+
+        def facts(paths, password: nil)
+          scripted(["node", SCRIPT], paths, env: { "STATIONERY_PDFJS" => directory, **password_env(password) })
+        end
+
+        private
+
+        def directory
+          return @directory if defined?(@directory)
+
+          found = ENV["STATIONERY_PDFJS"] ? File.expand_path(ENV["STATIONERY_PDFJS"]) : resolved
+          @directory = found if found && File.file?(File.join(found, "legacy/build/pdf.mjs"))
+        end
+
+        def resolved
+          return unless Command.which("node")
+
+          result = run("node", "-e", RESOLVE, chdir: Dir.pwd)
+          result.stdout.strip if result.success?
+        end
+      end
+    end
+  end
+end

data/lib/stationery/verify/engines/pdfkit.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    module Engines
+      # PDFKit, the engine of Preview and Safari, through scripts/pdfkit.swift.
+      # macOS only; Swift comes with Xcode or its command line tools.
+      class Pdfkit < Engine
+        NAME = "pdfkit"
+        INSTALL = "macOS only: xcode-select --install"
+        SCRIPT = File.expand_path("../scripts/pdfkit.swift", __dir__)
+
+        def available? = RUBY_PLATFORM.include?("darwin") && !Command.which("swift").nil?
+        def version = "macOS #{run("sw_vers", "-productVersion").stdout.strip}"
+
+        def facts(paths, password: nil) = scripted(["swift", SCRIPT], paths, env: password_env(password))
+      end
+    end
+  end
+end