acroforge 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c97cab951d5efe0d85539bcc55b368277b95bd1d6595141459be383a1a818c2e
-  data.tar.gz: 7156afa0720c474b3ee0b287cb994ccb3438c1f58cd10ff297673d19d6b34a30
+  metadata.gz: 6fa6d2f65a5a566457acc4a635dcc0ade68017f5aac69f0ea6b1e48e092db8af
+  data.tar.gz: d38c53fd44947a5b690fe84fa0674b55260ce897ef94f6828abb6e135b50447c
 SHA512:
-  metadata.gz: 35a79c84d8dd14affaa2e99a05c1b40fa7df8942e3e217adcaf05457de1e3303b49f7c9029e4768fa547ea83f41f96be7ece12cd889bc3efac37424a2d97ebbb
-  data.tar.gz: e0c282b00ddc2f38321a1e2979028886c614fbea59651081f2a9f2d581b2c07b5abb41374ba1a078df2fd7f382b81a7ccf774bd4b5e16aff089487410852020b
+  metadata.gz: c73b051b74fff85ac980a1295359f118843f26d3708a75943e3dcde874f2306b90921dd1eeeb024b5ab515a103c14409f674d7a09a2cf7c8cb79532798499bb3
+  data.tar.gz: 8440de33e8f66f72ba88c98659fe4a3c527d2ab036820a280fbf65f112503a8eb8ff342b652971a4c5366558b873674e2c6679544b3ed58cf522ee3fc3939308

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # CHANGELOG
 
+## [0.3.0] - 2026-06-01
+
+### Added
+
+- **`acroforge fields <pdf>` CLI subcommand** — lists every AcroForm field's name, type, and alternate name as an aligned table, or as JSON with `--json`. Decoded options maps render inline (table) or as nested objects (JSON). A PDF without an AcroForm prints a notice and still exits `0`.
+- **Configurable normalized output path for `compile!`** — `Engine#compile!` now accepts a `normalized_out:` kwarg to write the normalized PDF to an exact path; omitting it keeps the existing constructor-derived `<base>_normalized.pdf` location, byte-for-byte. Passing `normalized_out:` equal to the template path overwrites it in place safely (staged through a temp file, then moved). The `acroforge compile` CLI now persists the normalized template by default — next to the input as `<base>_normalized.pdf` — and gains a `--out PATH` flag to send it to an explicit path plus an `--overwrite` flag to rewrite the input PDF in place (`--out` and `--overwrite` are mutually exclusive).
+
+### Changed
+
+- **`Engine#fields` decodes persisted options maps.** When `/TU` holds the JSON options map that `compile!` writes for button/choice fields, `:alternate_name` is now returned as a symbol-keyed Hash (e.g. `{ male: "0", female: "1" }`) instead of the raw JSON string. Plain-text tooltips and missing `/TU` entries are unaffected (still String / `nil`).
+- **Image stamping extracted to `AcroForge::ImageStamper`** (internal). `Engine#fill!` behavior, the `ImageTooLargeError` / `UnsupportedImageFormatError` classes, and the validation rules are unchanged; the `MAX_IMAGE_BYTES` / `MAX_IMAGE_DIMENSION` / `TARGET_PPI` constants now live on `ImageStamper` instead of `Engine`.
+
+### Fixed
+
+- **Choice fields now auto-map.** `compile!` built options maps for combo/list boxes from `/Opt` but never ran the spatial label lookup on them, so a garbage-named choice field always landed in `unmapped` and its options were discarded. Choice fields now get the same nearest-label resolution as text fields, and their options persist to `/TU` and `select_options`.
+
+### Internal
+
+- Synthetic fixture PDFs now carry `/AP` appearance streams on radio/checkbox widgets, so `compile!`'s options-map discovery runs against them in CI. New round-trip spec covers compile! → fields → fill! through the persisted `/TU` map.
+
 ## [0.2.0] - 2026-05-28
 
 ### Changed (breaking)

data/README.md

@@ -56,17 +56,19 @@ $ acroforge bootstrap broken_form.pdf
 ## CLI
 
 ```text
+acroforge fields <pdf>           [--json]
 acroforge schema infer <pdf>     [--out schema.yml] [--sections a,b,c]
 acroforge relabel propose <pdf>  [--out mapping.yml] [--schema schema.yml] [--merge|--overwrite]
 acroforge relabel apply <pdf> <mapping.yml>
-acroforge compile <pdf>          [--schema schema.yml]
+acroforge compile <pdf>          [--schema schema.yml] [--out normalized.pdf | --overwrite]
 acroforge bootstrap <pdf>        [--schema-out s.yml] [--mapping-out m.yml]
 acroforge version
 acroforge help
 ```
 
 | Subcommand        | What it does                                                                                                                                                                                                   |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fields`          | Lists every AcroForm field — name, type, alternate name — as a table, or as JSON with `--json`. Read-only; the quickest way to see what's inside a PDF.                                                        |
 | `schema infer`    | Runs the heuristic on a PDF and writes a starter schema (canonical key → type + variations). Advisory; you review and edit.                                                                                    |
 | `relabel propose` | Writes a YAML mapping file proposing a semantic name for every AcroForm field. Sorted by page → top-to-bottom → left-to-right. Default mode `--merge` preserves any `key`/`type` values you've already edited. |
 | `relabel apply`   | Reads a corrected mapping file and rewrites `field[:T]` / `field[:TU]` in the source PDF in place. Auto-disambiguates collisions (`full_name`, `full_name_1`, ...).                                            |
@@ -178,7 +180,7 @@ AcroForge also accepts a legacy "shorthand" form where the value is just an arra
 _meta:
   source_pdf: broken_form.pdf
   generated_at: 2026-05-26T14:32:11Z
-  acroforge_version: 0.2.0
+  acroforge_version: 0.3.0
   total_fields: 98
 
 page0_field6:

data/lib/acroforge/cli.rb

@@ -2,6 +2,7 @@
 
 require "optparse"
 require "yaml"
+require "json"
 require_relative "../acroforge"
 
 module AcroForge
@@ -11,7 +12,7 @@ module AcroForge
     EXIT_VALIDATION_ERROR = 2
     EXIT_INTERNAL_ERROR = 3
 
-    SUBCOMMANDS = %w[schema relabel compile bootstrap annotate prepare version help].freeze
+    SUBCOMMANDS = %w[fields schema relabel compile bootstrap annotate prepare version help].freeze
 
     module_function
 
@@ -48,11 +49,12 @@ module AcroForge
         acroforge: PDF AcroForm engine + relabeler
 
         Usage:
+          acroforge fields <pdf>           [--json]
           acroforge schema infer <pdf>     [--out schema.yml] [--sections a,b,c] [-v]
           acroforge schema merge <mapping.yml> [--schema schema.yml] [--out schema.yml]
           acroforge relabel propose <pdf>  [--out mapping.yml] [--schema schema.yml] [--merge|--overwrite] [-v]
           acroforge relabel apply <pdf> <mapping.yml> [--annotate[=PATH]] [-v]
-          acroforge compile <pdf>          [--schema schema.yml]
+          acroforge compile <pdf>          [--schema schema.yml] [--out normalized.pdf | --overwrite]
           acroforge bootstrap <pdf>        [--schema-out s.yml] [--mapping-out m.yml] [-v]
           acroforge annotate <pdf>         [--mapping mapping.yml] [--out annotated.pdf]
           acroforge prepare <pdf>          [--out prepared.pdf] [--schema schema.yml]
@@ -101,6 +103,42 @@ module AcroForge
       puts "Applied to #{pdf}: #{parts.join(", ")}."
     end
 
+    def cmd_fields(argv)
+      json = false
+      OptionParser.new { |o| o.on("--json") { json = true } }.parse!(argv)
+      pdf = argv.shift
+      raise ArgumentError, "usage: acroforge fields <pdf> [--json]" unless pdf
+      raise Errno::ENOENT, pdf unless File.exist?(pdf)
+
+      fields = AcroForge::Engine.new(pdf).fields
+
+      if json
+        puts JSON.pretty_generate(fields)
+      elsif fields.empty?
+        puts "No AcroForm fields found in #{pdf}."
+      else
+        print_fields_table(fields)
+      end
+      EXIT_OK
+    end
+
+    def print_fields_table(fields)
+      headers = ["NAME", "TYPE", "ALTERNATE NAME"]
+      rows = fields.map { |f| [f[:name].to_s, f[:type].to_s, format_alternate_name(f[:alternate_name])] }
+      widths = headers.each_with_index.map { |h, i| ([h] + rows.map { |r| r[i] }).map(&:length).max }
+      ([headers] + rows).each do |row|
+        puts row.each_with_index.map { |cell, i| cell.ljust(widths[i]) }.join("  ").rstrip
+      end
+    end
+
+    def format_alternate_name(alt)
+      case alt
+      when nil then "—"
+      when Hash then "{#{alt.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")}}"
+      else alt.to_s
+      end
+    end
+
     def cmd_schema(argv)
       action = argv.shift
       case action
@@ -233,20 +271,26 @@ module AcroForge
 
     def cmd_compile(argv)
       schema_path = nil
+      out = nil
+      overwrite = false
       OptionParser.new do |opts|
         opts.on("--schema PATH") { |v| schema_path = v }
+        opts.on("--out PATH", "Write the normalized PDF to PATH") { |v| out = v }
+        opts.on("--overwrite", "Write the normalized PDF back over the input PDF in place") { overwrite = true }
       end.parse!(argv)
       pdf = argv.shift
       raise ArgumentError, "missing <pdf> argument" if pdf.nil?
+      raise ArgumentError, "--out and --overwrite are mutually exclusive" if out && overwrite
       raise Errno::ENOENT, pdf unless File.exist?(pdf)
 
       schema = schema_path ? AcroForge::Schema.load(schema_path) : {}
-      require "tmpdir"
-      Dir.mktmpdir do |tmp|
-        engine = AcroForge::Engine.new(pdf, schema: schema, normalized_dir: tmp)
-        result = engine.compile!
-        puts "Mapped: #{result[:mapped].size}, Unmapped: #{result[:unmapped].size}"
-      end
+      out ||= pdf if overwrite
+
+      engine = AcroForge::Engine.new(pdf, schema: schema, normalized_dir: out ? File.dirname(out) : nil)
+      result = engine.compile!(normalized_out: out)
+      puts "Mapped: #{result[:mapped].size}, Unmapped: #{result[:unmapped].size}"
+      where = overwrite ? "#{engine.normalized_path} (in place)" : engine.normalized_path
+      puts "Wrote #{where}: normalized template."
       EXIT_OK
     end
 
@@ -335,7 +379,7 @@ module AcroForge
       require "tmpdir"
       Dir.mktmpdir do |tmp|
         engine = AcroForge::Engine.new(pdf, normalized_dir: tmp)
-        silenced(verbose: verbose) { engine.compile! }
+        silenced(verbose: verbose) { engine.compile!(announce_output: false) }
 
         schema = AcroForge::Schema.infer(pdf, engine: engine)
         AcroForge::Schema.dump(schema, schema_out)

data/lib/acroforge/engine.rb

@@ -9,19 +9,10 @@ require_relative "all_text_processor"
 require_relative "validator"
 require_relative "constants"
 require_relative "labels"
+require_relative "image_stamper"
 
 module AcroForge
-  ImageTooLargeError = Class.new(Error)
-  UnsupportedImageFormatError = Class.new(Error)
-
   class Engine
-    # Caps a phone-camera passport photo from bloating the output PDF.
-    MAX_IMAGE_BYTES = 5 * 1024 * 1024
-    MAX_IMAGE_DIMENSION = 4000
-    # Auto-downsample images whose pixel resolution far exceeds this PPI
-    # at the widget's rendered size. Requires ImageMagick on PATH.
-    TARGET_PPI = 200
-
     attr_reader :template_path, :schema, :overrides, :sections, :normalized_path,
       :mapped_fields, :unmapped_fields, :filled_fields, :missing_fields,
       :select_field_options, :new_fields_detected
@@ -68,7 +59,7 @@ module AcroForge
         elsif field.is_a?(HexaPDF::Type::AcroForm::ChoiceField) then :choice
         else :other
         end
-        extracted << {name: field.full_field_name, type: type, alternate_name: field[:TU]}
+        extracted << {name: field.full_field_name, type: type, alternate_name: decode_alternate_name(field[:TU])}
       end
       extracted
     end
@@ -123,7 +114,8 @@ module AcroForge
     # every field, rename each to its proposed semantic key in place, and
     # persist the result to @normalized_path. The returned hash is what the
     # Relabeler and Schema.infer consume.
-    def compile!
+    def compile!(normalized_out: nil, announce_output: true)
+      @normalized_path = normalized_out if normalized_out
       puts ">> Compiling template: #{@template_path}"
       form = source_doc.acro_form(create: true)
 
@@ -320,6 +312,9 @@ module AcroForge
               end
             end
           end
+
+          raw_label = find_nearest_text(page_text_map[page_index], widget[:Rect], mode: :standard)
+          raw_label = AcroForge::Labels.humanize(raw_label)
         else
           field_rect = widget[:Rect]
           raw_label = find_nearest_text(page_text_map[page_index], field_rect, mode: :standard)
@@ -464,9 +459,9 @@ module AcroForge
         end
       end
 
-      source_doc.write(@normalized_path, optimize: true)
+      write_normalized!
       puts ">> Compilation Complete. #{mapped_count} fields mapped."
-      puts ">> Clean template saved to: #{@normalized_path}\n\n"
+      puts ">> Clean template saved to: #{@normalized_path}\n\n" if announce_output
 
       {
         mapped: @mapped_fields,
@@ -506,7 +501,7 @@ module AcroForge
         if doc_field
           begin
             if image_upload?(doc_field) && image_path?(value)
-              stamp_image_on_widget(normalized_doc, doc_field, value)
+              image_stamper.stamp!(normalized_doc, doc_field, value)
               @filled_fields[key] = value
               puts "   [Stamped] :#{key} <- #{value}"
               next
@@ -559,7 +554,7 @@ module AcroForge
                   doc_field.field_value = on_state_sym.to_s
                   doc_field.each_widget { |w| w[:AS] = on_state_sym }
                 elsif ["false", "no", "off", "0"].include?(normalized_val)
-                  doc_field.field_value = "Off"
+                  doc_field.field_value = :Off
                   doc_field.each_widget { |w| w[:AS] = :Off }
                 else
                   doc_field.field_value = value.to_s
@@ -610,6 +605,36 @@ module AcroForge
 
     private
 
+    # Writing back over the template HexaPDF still holds open can corrupt or
+    # truncate it (the writer reads lazily-loaded objects from that same handle).
+    # When the target is the source, stage to a sibling temp file and atomically
+    # move it into place once the write has fully completed.
+    def write_normalized!
+      same_file = File.expand_path(@normalized_path) == File.expand_path(@template_path)
+      unless same_file
+        source_doc.write(@normalized_path, optimize: true)
+        return
+      end
+
+      require "tmpdir"
+      require "fileutils"
+      tmp = File.join(File.dirname(@normalized_path), ".#{File.basename(@normalized_path)}.#{Process.pid}.tmp")
+      source_doc.write(tmp, optimize: true)
+      FileUtils.mv(tmp, @normalized_path)
+    ensure
+      FileUtils.rm_f(tmp) if tmp && File.exist?(tmp)
+    end
+
+    # compile! repurposes /TU to persist button/choice option maps as JSON
+    # (see fill!'s decode). Surface those as hashes; real tooltips stay strings.
+    def decode_alternate_name(value)
+      return value unless value.is_a?(String) && value.lstrip.start_with?("{")
+      parsed = JSON.parse(value, symbolize_names: true)
+      parsed.is_a?(Hash) ? parsed : value
+    rescue JSON::ParserError
+      value
+    end
+
     def confidence_for(raw_label, target_key)
       return :none if raw_label.nil? || raw_label.strip.empty?
       return :high if target_key && @schema.key?(target_key.to_s.to_sym)
@@ -642,161 +667,8 @@ module AcroForge
       value.is_a?(String) && File.file?(value)
     end
 
-    def stamp_image_on_widget(doc, field, path)
-      format, image_width, image_height = validate_image!(path)
-      widget = field.each_widget.first
-      return unless widget && widget[:Rect]
-
-      page = doc.pages.find { |candidate_page| candidate_page[:Annots]&.include?(widget) }
-      return unless page
-
-      # Widget Rect is absolute page coords; canvas API is MediaBox-relative.
-      media_box_x, media_box_y = page.box.value[0], page.box.value[1]
-      rect_x_min, rect_y_min, rect_x_max, rect_y_max = widget[:Rect]
-      slot_width = rect_x_max - rect_x_min
-      slot_height = rect_y_max - rect_y_min
-      slot_canvas_x = rect_x_min - media_box_x
-      slot_canvas_y = rect_y_min - media_box_y
-
-      stamp_path = prepare_image_for_slot(path, format, image_width, image_height,
-        slot_width, slot_height) || path
-      if stamp_path != path
-        _, image_width, image_height = image_dimensions(stamp_path)
-      end
-
-      draw_width, draw_height = fit_inside(image_width, image_height, slot_width, slot_height)
-      draw_x = slot_canvas_x + (slot_width - draw_width) / 2.0
-      draw_y = slot_canvas_y + (slot_height - draw_height) / 2.0
-
-      canvas = page.canvas(type: :overlay)
-      canvas.fill_color(255, 255, 255)
-      canvas.rectangle(slot_canvas_x, slot_canvas_y, slot_width, slot_height).fill
-      canvas.image(stamp_path, at: [draw_x, draw_y], width: draw_width, height: draw_height)
-
-      # Bake into the page so the widget's empty appearance doesn't repaint over the image.
-      page[:Annots].delete(widget)
-    end
-
-    def fit_inside(image_width, image_height, slot_width, slot_height)
-      scale = [slot_width.to_f / image_width, slot_height.to_f / image_height].min
-      [image_width * scale, image_height * scale]
-    end
-
-    # Trim removes the transparent border around a signature; downsample
-    # caps source resolution at TARGET_PPI for the widget's longer side.
-    def prepare_image_for_slot(path, format, image_width, image_height,
-      slot_width_pt, slot_height_pt)
-      return nil unless imagemagick_available?
-      slot_max_pt = [slot_width_pt, slot_height_pt].max
-      target_max_px = (slot_max_pt * TARGET_PPI / 72.0).ceil
-      needs_resize = image_width > target_max_px * 2 || image_height > target_max_px * 2
-      needs_trim = format == :png && png_with_alpha?(path)
-      return nil unless needs_resize || needs_trim
-
-      ext = (format == :png) ? ".png" : ".jpg"
-      require "securerandom"
-      require "tmpdir"
-      output_path = File.join(Dir.tmpdir,
-        "acroforge_stamp_#{Process.pid}_#{SecureRandom.hex(4)}#{ext}")
-      # `format:path` locks the coder, closing the CVE-2016-3714 (ImageTragick) class of attack.
-      args = ["convert", "#{format}:#{path}"]
-      args.push("-trim", "+repage") if needs_trim
-      args.push("-resize", "#{target_max_px}x#{target_max_px}>") if needs_resize
-      args.push(output_path)
-      success = system(*args, out: File::NULL, err: File::NULL)
-      (success && File.exist?(output_path)) ? output_path : nil
-    end
-
-    # PNG color type 4 = greyscale+alpha, 6 = RGBA — only these are trim-worthy.
-    def png_with_alpha?(path)
-      File.open(path, "rb") do |io|
-        return false unless io.read(8) == "\x89PNG\r\n\x1A\n".b
-        return false if io.read(8).nil?
-        return false if io.read(8).nil?
-        return false if io.read(1).nil?
-        color_type_byte = io.read(1)
-        return false if color_type_byte.nil?
-        color_type = color_type_byte.unpack1("C")
-        color_type == 4 || color_type == 6
-      end
-    end
-
-    def imagemagick_available?
-      return @imagemagick_available if defined?(@imagemagick_available)
-      @imagemagick_available = system("which", "convert", out: File::NULL, err: File::NULL)
-    end
-
-    # Trust boundary in front of ImageMagick: any malformed-input path
-    # raises a single error class so worker retry policies can key on it.
-    def validate_image!(path)
-      size = File.size(path)
-      if size > MAX_IMAGE_BYTES
-        raise ImageTooLargeError, "#{path}: #{size} bytes exceeds #{MAX_IMAGE_BYTES} byte cap"
-      end
-      format, width, height = image_dimensions(path)
-      if width > MAX_IMAGE_DIMENSION || height > MAX_IMAGE_DIMENSION
-        raise ImageTooLargeError,
-          "#{path}: #{width}x#{height}px exceeds #{MAX_IMAGE_DIMENSION}px per side"
-      end
-      [format, width, height]
-    end
-
-    def image_dimensions(path)
-      File.open(path, "rb") do |io|
-        head = read_exact(io, 8, path)
-        io.rewind
-        if head.start_with?("\x89PNG\r\n\x1A\n".b)
-          width, height = read_png_dimensions(io, path)
-          [:png, width, height]
-        elsif head[0, 2] == "\xFF\xD8".b
-          width, height = read_jpeg_dimensions(io, path)
-          [:jpg, width, height]
-        else
-          raise_unsupported(path)
-        end
-      end
-    end
-
-    def read_png_dimensions(io, path)
-      read_exact(io, 16, path) # 8-byte signature + 4 length + "IHDR"
-      width = read_exact(io, 4, path).unpack1("N")
-      height = read_exact(io, 4, path).unpack1("N")
-      [width, height]
-    end
-
-    def read_jpeg_dimensions(io, path)
-      read_exact(io, 2, path) # SOI
-      loop do
-        marker_byte = read_exact(io, 1, path).getbyte(0)
-        raise_unsupported(path) unless marker_byte == 0xFF
-        # Runs of 0xFF are valid JPEG fill bytes between markers.
-        marker_code = read_exact(io, 1, path).getbyte(0)
-        marker_code = read_exact(io, 1, path).getbyte(0) while marker_code == 0xFF
-        raise_unsupported(path, "no SOF marker found") if marker_code == 0xD9 || marker_code == 0x00
-        # 0xD0..0xD7 and 0x01 are standalone markers — no length follows.
-        next if (0xD0..0xD7).cover?(marker_code) || marker_code == 0x01
-        segment_length = read_exact(io, 2, path).unpack1("n")
-        raise_unsupported(path, "negative segment length") if segment_length < 2
-        is_sof_marker = (0xC0..0xCF).cover?(marker_code) && ![0xC4, 0xC8, 0xCC].include?(marker_code)
-        if is_sof_marker
-          read_exact(io, 1, path) # precision
-          height = read_exact(io, 2, path).unpack1("n")
-          width = read_exact(io, 2, path).unpack1("n")
-          return [width, height]
-        else
-          read_exact(io, segment_length - 2, path)
-        end
-      end
-    end
-
-    def read_exact(io, byte_count, path)
-      buf = io.read(byte_count)
-      raise_unsupported(path, "truncated header") if buf.nil? || buf.bytesize < byte_count
-      buf
-    end
-
-    def raise_unsupported(path, reason = "only JPG and PNG are supported")
-      raise UnsupportedImageFormatError, "#{path}: #{reason}"
+    def image_stamper
+      @image_stamper ||= ImageStamper.new
     end
 
     # Heuristic key for push-button image fields based on widget aspect ratio.

data/lib/acroforge/image_stamper.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module AcroForge
+  ImageTooLargeError = Class.new(Error)
+  UnsupportedImageFormatError = Class.new(Error)
+
+  # Stamps JPG/PNG files into AcroForm widget rectangles.
+  class ImageStamper
+    # Caps a phone-camera passport photo from bloating the output PDF.
+    MAX_IMAGE_BYTES = 5 * 1024 * 1024
+    MAX_IMAGE_DIMENSION = 4000
+    # Auto-downsample images whose pixel resolution far exceeds this PPI
+    # at the widget's rendered size. Requires ImageMagick on PATH.
+    TARGET_PPI = 200
+
+    def stamp!(doc, field, path)
+      format, image_width, image_height = validate_image!(path)
+      widget = field.each_widget.first
+      return unless widget && widget[:Rect]
+
+      page = doc.pages.find { |candidate_page| candidate_page[:Annots]&.include?(widget) }
+      return unless page
+
+      # Widget Rect is absolute page coords; canvas API is MediaBox-relative.
+      media_box_x, media_box_y = page.box.value[0], page.box.value[1]
+      rect_x_min, rect_y_min, rect_x_max, rect_y_max = widget[:Rect]
+      slot_width = rect_x_max - rect_x_min
+      slot_height = rect_y_max - rect_y_min
+      slot_canvas_x = rect_x_min - media_box_x
+      slot_canvas_y = rect_y_min - media_box_y
+
+      stamp_path = prepare_image_for_slot(path, format, image_width, image_height,
+        slot_width, slot_height) || path
+      if stamp_path != path
+        _, image_width, image_height = image_dimensions(stamp_path)
+      end
+
+      draw_width, draw_height = fit_inside(image_width, image_height, slot_width, slot_height)
+      draw_x = slot_canvas_x + (slot_width - draw_width) / 2.0
+      draw_y = slot_canvas_y + (slot_height - draw_height) / 2.0
+
+      canvas = page.canvas(type: :overlay)
+      canvas.fill_color(255, 255, 255)
+      canvas.rectangle(slot_canvas_x, slot_canvas_y, slot_width, slot_height).fill
+      canvas.image(stamp_path, at: [draw_x, draw_y], width: draw_width, height: draw_height)
+
+      # Bake into the page so the widget's empty appearance doesn't repaint over the image.
+      page[:Annots].delete(widget)
+    end
+
+    # Trust boundary in front of ImageMagick: any malformed-input path
+    # raises a single error class so worker retry policies can key on it.
+    def validate_image!(path)
+      size = File.size(path)
+      if size > MAX_IMAGE_BYTES
+        raise ImageTooLargeError, "#{path}: #{size} bytes exceeds #{MAX_IMAGE_BYTES} byte cap"
+      end
+      format, width, height = image_dimensions(path)
+      if width > MAX_IMAGE_DIMENSION || height > MAX_IMAGE_DIMENSION
+        raise ImageTooLargeError,
+          "#{path}: #{width}x#{height}px exceeds #{MAX_IMAGE_DIMENSION}px per side"
+      end
+      [format, width, height]
+    end
+
+    private
+
+    def fit_inside(image_width, image_height, slot_width, slot_height)
+      scale = [slot_width.to_f / image_width, slot_height.to_f / image_height].min
+      [image_width * scale, image_height * scale]
+    end
+
+    # Trim removes the transparent border around a signature; downsample
+    # caps source resolution at TARGET_PPI for the widget's longer side.
+    def prepare_image_for_slot(path, format, image_width, image_height,
+      slot_width_pt, slot_height_pt)
+      return nil unless imagemagick_available?
+      slot_max_pt = [slot_width_pt, slot_height_pt].max
+      target_max_px = (slot_max_pt * TARGET_PPI / 72.0).ceil
+      needs_resize = image_width > target_max_px * 2 || image_height > target_max_px * 2
+      needs_trim = format == :png && png_with_alpha?(path)
+      return nil unless needs_resize || needs_trim
+
+      ext = (format == :png) ? ".png" : ".jpg"
+      require "securerandom"
+      require "tmpdir"
+      output_path = File.join(Dir.tmpdir,
+        "acroforge_stamp_#{Process.pid}_#{SecureRandom.hex(4)}#{ext}")
+      # `format:path` locks the coder, closing the CVE-2016-3714 (ImageTragick) class of attack.
+      args = ["convert", "#{format}:#{path}"]
+      args.push("-trim", "+repage") if needs_trim
+      args.push("-resize", "#{target_max_px}x#{target_max_px}>") if needs_resize
+      args.push(output_path)
+      success = system(*args, out: File::NULL, err: File::NULL)
+      (success && File.exist?(output_path)) ? output_path : nil
+    end
+
+    # PNG color type 4 = greyscale+alpha, 6 = RGBA — only these are trim-worthy.
+    def png_with_alpha?(path)
+      File.open(path, "rb") do |io|
+        return false unless io.read(8) == "\x89PNG\r\n\x1A\n".b
+        return false if io.read(8).nil?
+        return false if io.read(8).nil?
+        return false if io.read(1).nil?
+        color_type_byte = io.read(1)
+        return false if color_type_byte.nil?
+        color_type = color_type_byte.unpack1("C")
+        color_type == 4 || color_type == 6
+      end
+    end
+
+    def imagemagick_available?
+      return @imagemagick_available if defined?(@imagemagick_available)
+      @imagemagick_available = system("which", "convert", out: File::NULL, err: File::NULL)
+    end
+
+    def image_dimensions(path)
+      File.open(path, "rb") do |io|
+        head = read_exact(io, 8, path)
+        io.rewind
+        if head.start_with?("\x89PNG\r\n\x1A\n".b)
+          width, height = read_png_dimensions(io, path)
+          [:png, width, height]
+        elsif head[0, 2] == "\xFF\xD8".b
+          width, height = read_jpeg_dimensions(io, path)
+          [:jpg, width, height]
+        else
+          raise_unsupported(path)
+        end
+      end
+    end
+
+    def read_png_dimensions(io, path)
+      read_exact(io, 16, path) # 8-byte signature + 4 length + "IHDR"
+      width = read_exact(io, 4, path).unpack1("N")
+      height = read_exact(io, 4, path).unpack1("N")
+      [width, height]
+    end
+
+    def read_jpeg_dimensions(io, path)
+      read_exact(io, 2, path) # SOI
+      loop do
+        marker_byte = read_exact(io, 1, path).getbyte(0)
+        raise_unsupported(path) unless marker_byte == 0xFF
+        # Runs of 0xFF are valid JPEG fill bytes between markers.
+        marker_code = read_exact(io, 1, path).getbyte(0)
+        marker_code = read_exact(io, 1, path).getbyte(0) while marker_code == 0xFF
+        raise_unsupported(path, "no SOF marker found") if marker_code == 0xD9 || marker_code == 0x00
+        # 0xD0..0xD7 and 0x01 are standalone markers — no length follows.
+        next if (0xD0..0xD7).cover?(marker_code) || marker_code == 0x01
+        segment_length = read_exact(io, 2, path).unpack1("n")
+        raise_unsupported(path, "negative segment length") if segment_length < 2
+        is_sof_marker = (0xC0..0xCF).cover?(marker_code) && ![0xC4, 0xC8, 0xCC].include?(marker_code)
+        if is_sof_marker
+          read_exact(io, 1, path) # precision
+          height = read_exact(io, 2, path).unpack1("n")
+          width = read_exact(io, 2, path).unpack1("n")
+          return [width, height]
+        else
+          read_exact(io, segment_length - 2, path)
+        end
+      end
+    end
+
+    def read_exact(io, byte_count, path)
+      buf = io.read(byte_count)
+      raise_unsupported(path, "truncated header") if buf.nil? || buf.bytesize < byte_count
+      buf
+    end
+
+    def raise_unsupported(path, reason = "only JPG and PNG are supported")
+      raise UnsupportedImageFormatError, "#{path}: #{reason}"
+    end
+  end
+end

data/lib/acroforge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AcroForge
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/acroforge.rb

@@ -10,6 +10,7 @@ end
 require_relative "acroforge/all_text_processor"
 require_relative "acroforge/labels"
 require_relative "acroforge/validator"
+require_relative "acroforge/image_stamper"
 require_relative "acroforge/engine"
 require_relative "acroforge/schema"
 require_relative "acroforge/relabeler"

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: acroforge
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Maxwell Nana Forson
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hexapdf
@@ -44,6 +45,7 @@ files:
 - lib/acroforge/cli.rb
 - lib/acroforge/constants.rb
 - lib/acroforge/engine.rb
+- lib/acroforge/image_stamper.rb
 - lib/acroforge/labels.rb
 - lib/acroforge/preparer.rb
 - lib/acroforge/relabeler.rb
@@ -61,6 +63,7 @@ metadata:
   changelog_uri: https://github.com/Lzcorp-Solutions/acroforge/blob/main/CHANGELOG.md
   documentation_uri: https://lzcorp-solutions.github.io/acroforge/
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -75,7 +78,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.12
+rubygems_version: 3.1.6
+signing_key:
 specification_version: 4
 summary: PDF AcroForm engine with heuristic-assisted field relabeling.
 test_files: []