acroforge 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 700f9e41b86a58ef21a6f5d045907c1df97ae55c9d2728a465cd7b0f3ecf828e
-  data.tar.gz: 9859e634dbf6236e17ee1392ccf1239c8edf494be6072272218f6e2c58092c33
+  metadata.gz: c97cab951d5efe0d85539bcc55b368277b95bd1d6595141459be383a1a818c2e
+  data.tar.gz: 7156afa0720c474b3ee0b287cb994ccb3438c1f58cd10ff297673d19d6b34a30
 SHA512:
-  metadata.gz: 29c17e2e6958e5772cab51aa25a11187cc8d1f08cc9ccf7b2add174abacee05682b44f3f38f54dd50e6755084d5ccd5949407373da0d5d9a0e81de4257ed2348
-  data.tar.gz: eebeb0e39a636cba72f879cb6b4d31af3a670a01ae3692a86e47d5d248eb8a20ba656ded433f7c17f1fdf4b8d29041c4751bb2b78f2fff141c660798bbd1f805
+  metadata.gz: 35a79c84d8dd14affaa2e99a05c1b40fa7df8942e3e217adcaf05457de1e3303b49f7c9029e4768fa547ea83f41f96be7ece12cd889bc3efac37424a2d97ebbb
+  data.tar.gz: e0c282b00ddc2f38321a1e2979028886c614fbea59651081f2a9f2d581b2c07b5abb41374ba1a078df2fd7f382b81a7ccf774bd4b5e16aff089487410852020b

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # CHANGELOG
 
+## [0.2.0] - 2026-05-28
+
+### Changed (breaking)
+
+- **`_btn` suffix dropped from canonical keys.** Button/choice fields now use bare canonical keys (`gender`, `title`, `marital_status`) instead of `gender_btn` etc. Type detection for validation reads the PDF field type and the resolved options map, not a string token in the key. Existing payloads/schemas/mappings using `_btn` need their keys updated.
+- **`fill!` is now standalone.** It no longer requires `compile!` to have run, and it no longer falls back to the normalized PDF — it always fills the original `@template_path`. Stale normalized files can no longer silently take over a fill. To fill a renamed template, instantiate a new `Engine` over the normalized output.
+- **Bad radio values now raise instead of warn-and-skip.** When `fill!` cannot match a value to a radio button's allowed options, it raises `AcroForge::Error` instead of logging a warning and continuing.
+- **Engine introspection renamed:** `raw_fields` → `fields`, `raw_field_names` → `field_names`, `any_raw_fields?` → `any_fields?`.
+- **Schemas emitted by `Schema.infer` / `Schema.merge` no longer carry empty `variations: []`.** When a field has no spatial label worth recording (typically anything preserved verbatim), the key is omitted entirely. Existing schemas with `variations:` still load fine.
+- **Parenthetical content stripped** from both canonical keys and humanized variations. `Date of Birth (YYYY-MM-DD)` now produces `:date_of_birth` (not `:date_of_birth_yyyy_mm_dd`) and the variation `"Date of Birth"`.
+
+### Added
+
+- **`preserve:` constructor kwarg on `Engine`** — explicit allowlist of AcroForm field names `compile!` must never rename. Plumbed through `Schema.infer` and `Relabeler.propose`.
+- **Auto-preserve cascade in `compile!`** — fields are kept verbatim when they are (A) in `preserve:`, (B) a schema canonical key, or (C) look like a clean snake_case identifier (`looks_like_clean_identifier?`). Tier C is what makes `schema infer` on a clean PDF stop generating `mr` / `single` / section-header bleeds.
+- **Case-insensitive radio matching** in `fill!` — `"Mr"` resolves to `:mr` against `allowed_values` without forcing the caller to know the export-value casing.
+- **Automatic image stamping in `fill!`** — a payload value that targets a push-button image-upload field and points to a JPG/PNG file path is now drawn into the widget rectangle (scaled to fit) instead of being treated as text. `compile!` infers canonical keys for these slots from widget geometry: square-ish → `:passport_photo`, wide-and-thin → `:signature`, otherwise `:photo`.
+- **Image validation with new error classes** — stamped images must be JPG or PNG within `MAX_IMAGE_BYTES` (5 MB) and `MAX_IMAGE_DIMENSION` (4000 px per side); violations raise the new `AcroForge::ImageTooLargeError` or `AcroForge::UnsupportedImageFormatError` (both subclass `AcroForge::Error`). When ImageMagick (`convert`) is on `PATH`, oversized images are downsampled toward `TARGET_PPI` (200) and transparent PNG borders (e.g. around a signature) are trimmed before stamping.
+- **`simplecov`** in the dev/test group; coverage report under `coverage/`.
+
+### Fixed
+
+- Radio button widget appearance state (`/AS`) wasn't syncing when `fill!` operated standalone (no compile-time `:TU` options map). Radios now coerce values to a Symbol matched against `allowed_values`, so hexapdf syncs widget state correctly.
+- `Schema.infer_type` was missing matches on snake_case names (`account_no`, `date_signed`) because `_` is a word character — regex `\b` never fired. Underscores are now normalized to spaces before type detection.
+- `Schema.infer_type` now recognises `\bdob\b` as a date.
+- `Schema.merge` no longer reinstates the empty `variations: []` keys that `aggregate_proposals` strips.
+- `compile!` was reading `field[:Opt]` for choice fields via `is_a?(Array)`, but hexapdf 1.x returns `HexaPDF::PDFArray` (not `Array`). The check is now duck-typed via `respond_to?(:each)`, so choice-field options maps are populated correctly.
+- Spatial `:standard` scorer no longer claims a label sitting two rows above a field — tightened `dy_top` window and gave inline (label-left) matches a stronger preference over grid-locked (label-above) candidates. This recovers `first_name` on multi-column form layouts like Abokobi's.
+
 ## [0.1.0] - 2026-05-26
 
 ## Added

data/README.md

@@ -80,19 +80,29 @@ Exit codes: `0` success, `1` user error (bad args, missing file), `2` validation
 ```ruby
 require "acroforge"
 
-# Compile a PDF and inspect what the heuristic found.
+# Inspect the fields a PDF declares (no compilation needed).
+engine = AcroForge::Engine.new("form.pdf")
+engine.fields        # => [{ name: "full_name", type: :text, alternate_name: nil }, ...]
+engine.field_names   # => ["full_name", ...]
+engine.any_fields?   # => true
+
+# Fill an already-clean PDF — fill! is standalone, compile! is NOT required.
+engine.fill!({ full_name: "Alice", email: "alice@example.com" }, "filled.pdf")
+
+# Compile a messy PDF to clean its field names via the spatial heuristic.
 engine = AcroForge::Engine.new(
   "form.pdf",
-  schema: AcroForge::Schema.load("schema.yml"),   # or pass a Hash directly
-  overrides: {},                                  # optional per-PDF overrides
-  sections: ["Personal Details", "Loan Details"]  # optional section headers for scoping
+  schema:    AcroForge::Schema.load("schema.yml"),   # or pass a Hash directly
+  overrides: {},                                     # per-PDF target-key overrides
+  preserve:  %w[some_field_to_keep_verbatim],        # allowlist of names to never rename
+  sections:  ["Personal Details", "Loan Details"]    # optional section headers for scoping
 )
 result = engine.compile!
 # => { mapped: {...}, unmapped: [...], select_options: {...}, new_fields_detected: [...] }
+# Writes a `<form>_normalized.pdf` next to the source.
 
-# Fill a form with a payload.
-engine.validate_payload!(full_name: "Alice", email: "alice@example.com")
-engine.fill!({ full_name: "Alice", email: "alice@example.com" }, "filled.pdf")
+# To fill a compiled (normalized) template, point a new Engine at it:
+AcroForge::Engine.new("form_normalized.pdf").fill!(payload, "filled.pdf")
 
 # Generate a starter schema from a PDF.
 schema = AcroForge::Schema.infer("form.pdf")
@@ -107,9 +117,20 @@ AcroForge::Validator.valid?("alice@example.com", :email)  # => true
 AcroForge::Validator.valid?("not a date", :date)          # => false
 ```
 
+### Preserve cascade
+
+`compile!` keeps an existing field name verbatim — skipping the spatial heuristic for that field — when any of these match:
+
+1. **Explicit:** the name is in the `preserve:` kwarg.
+2. **Schema:** the name is already a canonical key in the supplied `schema:`.
+3. **Heuristic:** the name looks like a clean snake_case identifier (no `pageN_fieldM` / `TextN` / `ImageN` markers).
+
+The cascade is what stops `Schema.infer` on a clean PDF from synthesising garbage keys derived from adjacent radio-option labels or section headers.
+
 ### Errors
 
 - `AcroForge::ValidationError`: raised by `Engine#validate_payload!` on type mismatch.
+- `AcroForge::Error`: raised by `Engine#fill!` when the PDF rejects a value (e.g. a radio value that doesn't match any allowed option).
 - `AcroForge::RelabelError`: raised by `Relabeler.apply!` on malformed mapping YAML, invalid key names, or missing AcroForm.
 
 ## Schema format
@@ -157,7 +178,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.1.0
+  acroforge_version: 0.2.0
   total_fields: 98
 
 page0_field6:

data/lib/acroforge/engine.rb

@@ -11,16 +11,27 @@ require_relative "constants"
 require_relative "labels"
 
 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
 
-    def initialize(template_path, schema: {}, overrides: {}, sections: [], normalized_dir: nil)
+    def initialize(template_path, schema: {}, overrides: {}, sections: [], preserve: [], normalized_dir: nil)
       @template_path = template_path
       @schema = schema
       @overrides = overrides
       @sections = sections
+      @preserve = Array(preserve).map(&:to_s)
 
       dir = normalized_dir || File.dirname(template_path)
       base = File.basename(template_path, ".*")
@@ -47,7 +58,7 @@ module AcroForge
       @source_form ||= source_doc.acro_form(create: false)
     end
 
-    def raw_fields
+    def fields
       return [] unless source_form
       extracted = []
       source_form.each_field do |field|
@@ -62,12 +73,12 @@ module AcroForge
       extracted
     end
 
-    def raw_field_names
-      raw_fields.map { |f| f[:name] }
+    def field_names
+      fields.map { |f| f[:name] }
     end
 
-    def any_raw_fields?
-      raw_fields.any?
+    def any_fields?
+      fields.any?
     end
 
     def fully_mapped?
@@ -108,9 +119,10 @@ module AcroForge
       index
     end
 
-    # ------------------------------------------
-    # PHASE 1: THE HIERARCHICAL COMPILER
-    # ------------------------------------------
+    # Phase one of the discover→fill pipeline: run the spatial heuristic over
+    # 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!
       puts ">> Compiling template: #{@template_path}"
       form = source_doc.acro_form(create: true)
@@ -161,10 +173,70 @@ module AcroForge
         is_btn = field.is_a?(HexaPDF::Type::AcroForm::ButtonField) || field.is_a?(HexaPDF::Type::AcroForm::ChoiceField)
         is_radio_group = is_btn && field.each_widget.count > 1
 
+        preserved_key = nil
+        preserved_source = nil
+        if @preserve.include?(original_field_name) || @preserve.include?(base_field_name)
+          preserved_key = base_field_name
+          preserved_source = :explicit
+        elsif @schema && !@schema.empty?
+          # Raw name first — sanitize_key over-corrects "social" → "sofficial".
+          if @schema.key?(base_field_name.to_sym)
+            preserved_key = base_field_name
+            preserved_source = :schema
+          elsif (canonical = sanitize_key(base_field_name)) && @schema.key?(canonical.to_sym)
+            preserved_key = canonical.to_s
+            preserved_source = :schema
+          end
+        end
+
+        # Heuristic fallback for Schema.infer, which compiles with no schema yet.
+        if preserved_key.nil? && looks_like_clean_identifier?(base_field_name)
+          preserved_key = base_field_name
+          preserved_source = :heuristic
+        end
+
+        if preserved_key
+          target_key = preserved_key.to_sym
+          @mapped_fields[original_field_name] = target_key
+
+          y_center = (widget[:Rect][1] + widget[:Rect][3]) / 2.0
+          active_section = get_active_section(section_map, page_index, y_center)
+
+          preserved_opts = preserved_options_map(field)
+          # Mirror what the renamed-field path does so validate_payload! and fill!'s :TU
+          # branch see the same option map for preserved buttons/choices.
+          if preserved_opts && !preserved_opts.empty?
+            @select_field_options[target_key.to_s] = preserved_opts
+            field[:TU] = preserved_opts.to_json
+          end
+
+          @field_proposals << {
+            pdf_field_name: original_field_name,
+            pdf_field_type: case field
+                            when HexaPDF::Type::AcroForm::TextField then :text
+                            when HexaPDF::Type::AcroForm::ButtonField then :button
+                            when HexaPDF::Type::AcroForm::ChoiceField then :choice
+                            else :other
+                            end,
+            canonical_key: target_key,
+            raw_label: preserved_key,
+            confidence: :preserved,
+            section: active_section,
+            page: page_index,
+            y: y_center,
+            x: (widget[:Rect][0] + widget[:Rect][2]) / 2.0,
+            options: preserved_opts
+          }
+
+          puts "   [Preserved] '#{original_field_name}' (#{preserved_source}) -> :#{target_key}"
+          next
+        end
+
         options_map = nil
 
         if is_radio_group
-          # THE FIX: Sort by Highest Y, then Leftmost X to guarantee finding the top-left box of multi-line groups
+          # A group's label sits by its top-left widget, so order by highest Y
+          # then leftmost X to find it — widget enumeration order is arbitrary.
           first_widget = field.each_widget.min_by { |w| [-w[:Rect][1], w[:Rect][0]] }
 
           raw_label = find_nearest_text(page_text_map[page_index], first_widget[:Rect], mode: :group_label)
@@ -220,10 +292,19 @@ module AcroForge
 
           ["no", "false", "off", "0", "unchecked"].each { |k| options_map[k] = "Off" }
 
+          # Image-upload (push-button) fields don't sit beside an inline
+          # label — their slot IS the label. Infer the canonical key from
+          # the widget geometry: square → passport_photo, wide-thin → signature.
+          if field.respond_to?(:push_button?) && field.push_button?
+            inferred = infer_image_field_key(widget[:Rect])
+            raw_label = inferred.to_s.tr("_", " ") if inferred
+          end
+
         elsif field.is_a?(HexaPDF::Type::AcroForm::ChoiceField)
           # Choice fields can expose values via /Opt entries.
           options_map = {}
-          if field[:Opt].is_a?(Array)
+          # `field[:Opt]` is a HexaPDF::PDFArray on hexapdf 1.x — not a plain Array.
+          if field[:Opt].respond_to?(:each)
             field[:Opt].each do |opt|
               if opt.is_a?(Array)
                 export_val = opt[0].to_s
@@ -264,8 +345,7 @@ module AcroForge
         override_entry = @overrides[original_field_name.to_s] || @overrides[original_field_name.to_sym]
         if override_entry
           semantic_name = override_entry[:key] || override_key_used
-          mapped_semantic = semantic_name.to_sym
-          target_key = (is_btn && !mapped_semantic.to_s.end_with?("_btn")) ? :"#{mapped_semantic}_btn" : mapped_semantic
+          target_key = semantic_name.to_sym
 
           # Ensure uniqueness when multiple fields map to the same semantic key
           original_target = target_key
@@ -319,7 +399,6 @@ module AcroForge
 
           target_key = active_section ? :"#{active_section}_#{base_key}" : base_key
           target_key = @overrides[raw_label].to_sym if @overrides[raw_label]
-          target_key = :"#{target_key}_btn" if is_btn && !target_key.to_s.end_with?("_btn")
 
           original_target = target_key
           counter = 1
@@ -397,19 +476,16 @@ module AcroForge
       }
     end
 
-    # ------------------------------------------
-    # PHASE 2: THE CRASH-PROOF INJECTOR
-    # ------------------------------------------
+    # Phase two: inject a payload into a name-addressable form and write
+    # output_path. Standalone — it does not depend on compile! having run.
     def fill!(payload, output_path, image_overlays = {})
-      puts ">> Injecting data into: #{@normalized_path}"
-
-      unless File.exist?(@normalized_path)
-        raise "Normalized template missing. Please run compile! first."
-      end
+      # Always the original template — a stale normalized PDF would silently fill the wrong document.
+      # To fill a normalized PDF, instantiate a new Engine pointing at it.
+      puts ">> Injecting data into: #{@template_path}"
 
       validate_payload!(payload)
 
-      normalized_doc = HexaPDF::Document.open(@normalized_path)
+      normalized_doc = HexaPDF::Document.open(@template_path)
       form = normalized_doc.acro_form
 
       @filled_fields = {}
@@ -429,6 +505,13 @@ module AcroForge
 
         if doc_field
           begin
+            if image_upload?(doc_field) && image_path?(value)
+              stamp_image_on_widget(normalized_doc, doc_field, value)
+              @filled_fields[key] = value
+              puts "   [Stamped] :#{key} <- #{value}"
+              next
+            end
+
             if doc_field.is_a?(HexaPDF::Type::AcroForm::ButtonField) ||
                 doc_field.is_a?(HexaPDF::Type::AcroForm::ChoiceField)
               resolved_from_map = false
@@ -464,7 +547,15 @@ module AcroForge
                 normalized_val = value.to_s.downcase.strip
                 on_state_sym = button_on_states(doc_field).first || :Yes
 
-                if ["true", "yes", "on", "1"].include?(normalized_val)
+                # Radios first — their "0"/"1" export values would otherwise
+                # be swallowed by the checkbox truthy/falsy branches below.
+                if doc_field.respond_to?(:radio_button?) && doc_field.radio_button?
+                  # Case-insensitive match against allowed_values so "Mr" finds :mr.
+                  # Symbol assignment triggers hexapdf to sync each widget's :AS.
+                  allowed = doc_field.allowed_values || []
+                  target = allowed.find { |v| v.to_s.casecmp(value.to_s).zero? } || value.to_sym
+                  doc_field.field_value = target
+                elsif ["true", "yes", "on", "1"].include?(normalized_val)
                   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)
@@ -487,7 +578,7 @@ module AcroForge
             @filled_fields[key] = value
             puts "   [Filled] :#{key} = #{value}"
           rescue HexaPDF::Error => e
-            puts "   [Warning] Rejected :#{key} - PDF formatting conflict (#{e.message.split(" (HexaPDF").first})"
+            raise AcroForge::Error, "Field :#{key} rejected by PDF: #{e.message.split(" (HexaPDF").first}"
           end
         else
           @missing_fields << key
@@ -526,8 +617,218 @@ module AcroForge
       :low
     end
 
+    # Lets Schema.infer classify radios/choices as :select instead of :boolean.
+    # Returns an empty hash (never nil) so callers can `.any?` / `.empty?` uniformly.
+    def preserved_options_map(field)
+      if field.is_a?(HexaPDF::Type::AcroForm::ButtonField) && field.radio_button?
+        vals = field.allowed_values
+        return {} unless vals && !vals.empty?
+        vals.each_with_object({}) { |v, h| h[v.to_s] = v.to_s }
+      elsif field.is_a?(HexaPDF::Type::AcroForm::ChoiceField)
+        items = field.option_items
+        return {} unless items && !items.empty?
+        items.each_with_object({}) { |v, h| h[v.to_s] = v.to_s }
+      else
+        {}
+      end
+    end
+
+    def image_upload?(field)
+      field.is_a?(HexaPDF::Type::AcroForm::ButtonField) &&
+        field.respond_to?(:push_button?) && field.push_button?
+    end
+
+    def image_path?(value)
+      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}"
+    end
+
+    # Heuristic key for push-button image fields based on widget aspect ratio.
+    # Vendor forms reserve square-ish boxes for headshots and wide-thin strips
+    # for signatures; the slot's geometry is a more reliable signal than any
+    # nearby text because the labels are usually far from the box.
+    def infer_image_field_key(rect)
+      width = rect[2] - rect[0]
+      height = rect[3] - rect[1]
+      return nil if width <= 0 || height <= 0
+      aspect_ratio = width.to_f / height
+      if aspect_ratio > 3.0
+        :signature
+      elsif aspect_ratio.between?(0.5, 2.0) && [width, height].min >= 30
+        :passport_photo
+      else
+        :photo
+      end
+    end
+
+    def looks_like_clean_identifier?(name)
+      return false unless name.is_a?(String) && !name.empty?
+      return false unless name.match?(/\A[a-z][a-z0-9_]*\z/)
+      return false if name.match?(/\A(?:page|text|field|image)\d/)
+      return false if name.match?(/_(?:field|text|image)\d/)
+      true
+    end
+
     def sanitize_key(string)
-      key = string.to_s.downcase
+      cleaned = AcroForge::Labels.strip_parenthetical(string)
+
+      key = cleaned.downcase
         .gsub(/['’*]/, "")
         .gsub(/[^a-z0-9]+/, "_").squeeze("_")
         .sub(/_$/, "")
@@ -735,24 +1036,25 @@ module AcroForge
       payload.each do |key, value|
         next if value.nil? || value.to_s.empty?
 
-        # Strip suffixes like _1 or _btn to find the base canonical key for schema lookup
+        # Strip the _N collision suffix that compile! appends when multiple
+        # fields share a name. The bare key drives schema and override lookup.
         key_str = key.to_s
-        base_key = key_str.sub(/_btn(?:_\d+)?\z/, "").sub(/_\d+\z/, "").to_sym
+        base_key = key_str.sub(/_\d+\z/, "").to_sym
 
-        # Try to resolve override info. @overrides may be keyed by
-        # original PDF field names (strings like "page0_field6") so allow lookup
-        # by semantic base_key (matching value[:key]) or by string key.
         override_info = @overrides[base_key] || @overrides[base_key.to_s] || @overrides.values.find { |v| v.is_a?(Hash) && v[:key].to_sym == base_key }
 
         type_info = @schema[base_key]
 
-        # If it's a button field, it's a select type by nature
-        type = if key_str.include?("_btn")
-          :select
-        elsif override_info
+        # Treat fields with a known options set as :select regardless of how
+        # the schema labels them — that's how button/choice fields are
+        # validated against their allowed values.
+        pdf_options_for_type = @select_field_options[key.to_s]&.keys || []
+        type = if override_info
           override_info[:type]
         elsif type_info
           type_info.is_a?(Hash) ? type_info[:type] : :string
+        elsif !pdf_options_for_type.empty?
+          :select
         else
           infer_type(key)
         end
@@ -789,9 +1091,11 @@ module AcroForge
       end
     end
 
-    # ------------------------------------------
-    # THE UNIVERSAL DYNAMIC HEURISTIC (WEIGHTS FIXED)
-    # ------------------------------------------
+    # Scores every text chunk against the field's rectangle and returns the
+    # best-matching label. `mode` selects which spatial relationship to reward
+    # (inline label, grid header, radio option). The magic offsets below are
+    # hand-tuned weights, not physical distances — they bias one relationship
+    # over another when several candidates sit close to the field.
     def find_nearest_text(text_chunks, field_rect, mode: :standard)
       f_x_min, f_y_min, f_x_max, f_y_max = field_rect
       f_y_center = (f_y_min + f_y_max) / 2.0
@@ -836,14 +1140,17 @@ module AcroForge
           end
 
         when :standard
-          is_grid_locked = dy_top > -5 && dy_top < 30 && t_x_center >= (f_x_min - 20) && t_x_center <= (f_x_max + 20)
+          # Tighter dy_top so labels two rows up don't claim an unrelated field.
+          is_grid_locked = dy_top > -5 && dy_top < 12 && t_x_center >= (f_x_min - 20) && t_x_center <= (f_x_max + 20)
           is_inline = dy_center < 10 && dx_left > -10 && dx_left < 200
 
-          if is_grid_locked
-            score = dy_top.abs - 2000
+          # Inline beats grid-locked when both apply: a label sitting on the same
+          # row as its field is a stronger signal than one sitting above it.
+          if is_inline
+            score = dx_left.abs - 3000
             score -= 200 if has_colon_or_q
-          elsif is_inline
-            score = dx_left.abs - 1000
+          elsif is_grid_locked
+            score = dy_top.abs - 2000
             score -= 200 if has_colon_or_q
           elsif dy_center < 15 && dx_left > -10 && dx_left < 150
             score = dx_left.abs

data/lib/acroforge/labels.rb

@@ -22,10 +22,20 @@ module AcroForge
       of at by in on to up from with as vs
     ].to_set
 
+    # Parenthetical content in form labels is UI hints, not field identity.
+    def strip_parenthetical(text)
+      text.to_s.gsub(/\s*\(.*?\)\s*/, " ").gsub(/\s+/, " ").strip
+    end
+
     def humanize(label)
       return label unless label.is_a?(String) && !label.empty?
 
-      result = fix_typos(label)
+      result = strip_parenthetical(label)
+      # Treat `_` as a word separator so snake_case names from preserved
+      # fields title-case correctly. Real PDF labels almost never contain
+      # underscores; snake_case keys passed through here always do.
+      result = result.tr("_", " ")
+      result = fix_typos(result)
       result = title_case(result)
       result.gsub(/\s+/, " ").strip
     end

data/lib/acroforge/relabeler.rb

@@ -94,14 +94,14 @@ module AcroForge
     # we use its proposals directly (no second compile). This lets callers
     # like the CLI's `bootstrap` subcommand share one compile pass with
     # Schema.infer instead of running the engine twice.
-    def propose(pdf_path, out:, schema: {}, mode: :merge, engine: nil)
+    def propose(pdf_path, out:, schema: {}, preserve: [], mode: :merge, engine: nil)
       existing = (mode == :merge && File.exist?(out)) ? YAML.load_file(out) : nil
 
       proposals = if engine
         engine.field_proposals
       else
         Dir.mktmpdir do |tmp|
-          e = AcroForge::Engine.new(pdf_path, schema: schema, normalized_dir: tmp)
+          e = AcroForge::Engine.new(pdf_path, schema: schema, preserve: preserve, normalized_dir: tmp)
           e.compile!
           e.field_proposals
         end
@@ -147,16 +147,21 @@ module AcroForge
     end
 
     def infer_type(proposal)
+      # Mirrors AcroForge::Schema#infer_type. Kept separate so Relabeler
+      # doesn't have to load the whole Schema module path during mapping
+      # propose. Keep these two in sync when you tweak either.
       case proposal[:pdf_field_type]
       when :button
         ((proposal[:options]&.size || 0) > 1) ? :select : :boolean
       when :choice
         :select
       else
-        label = proposal[:raw_label].to_s.downcase
+        # Normalize underscores to spaces so `\b`-anchored regexes match
+        # against snake_case names like `account_no`, `date_signed`.
+        label = proposal[:raw_label].to_s.downcase.tr("_", " ")
         case label
         when /amount|salary|income|balance|fee|tier3/ then :money
-        when /\bdate\b|birth|expiry|employed/ then :date
+        when /\bdate\b|\bdob\b|birth|expiry|employed/ then :date
         when /email/ then :email
         when /years|tenor|number of|\bno\.?\b/ then :number
         else :string

data/lib/acroforge/schema.rb

@@ -12,7 +12,9 @@ module AcroForge
     def load(path)
       raw = case File.extname(path).downcase
       when ".yml", ".yaml"
-        YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: true)
+        # safe_load_file was added in Psych 4 (Ruby 3.1+); safe_load(File.read)
+        # keeps the gem usable on Ruby 2.7 as the gemspec advertises.
+        YAML.safe_load(File.read(path), permitted_classes: [Symbol], aliases: true) # standard:disable Style/YAMLFileRead
       when ".json"
         JSON.parse(File.read(path), symbolize_names: false)
       else
@@ -98,24 +100,26 @@ module AcroForge
     # we use its proposals directly. This lets callers (notably the CLI's
     # `bootstrap` subcommand) avoid a redundant second compile when they
     # also want to call Relabeler.propose on the same PDF.
-    def infer(pdf_path, sections: [], engine: nil)
+    def infer(pdf_path, sections: [], preserve: [], engine: nil)
       return aggregate_proposals(engine.field_proposals) if engine
 
       require "tmpdir"
       Dir.mktmpdir do |tmp|
-        e = AcroForge::Engine.new(pdf_path, sections: sections, normalized_dir: tmp)
+        e = AcroForge::Engine.new(pdf_path, sections: sections, preserve: preserve, normalized_dir: tmp)
         e.compile!
         aggregate_proposals(e.field_proposals)
       end
     end
 
     def aggregate_proposals(proposals)
-      proposals.each_with_object({}) do |p, schema|
+      result = proposals.each_with_object({}) do |p, schema|
         next if p[:canonical_key].nil?
 
         key = p[:canonical_key].to_sym
         schema[key] ||= {type: infer_type(p), variations: []}
-        if p[:raw_label]
+
+        # Preserved fields' raw_label echoes the key — adding it as a variation is noise.
+        if p[:raw_label] && p[:confidence] != :preserved
           cleaned = humanize_label(p[:raw_label])
           schema[key][:variations] << cleaned unless schema[key][:variations].include?(cleaned)
         end
@@ -124,6 +128,9 @@ module AcroForge
           schema[key][:options] = p[:options].keys.map(&:to_sym).uniq
         end
       end
+
+      result.each_value { |entry| entry.delete(:variations) if entry[:variations].empty? }
+      result
     end
 
     # Thin delegator. The real implementation lives in AcroForge::Labels so
@@ -141,10 +148,11 @@ module AcroForge
       when :choice
         :select
       else
-        label = proposal[:raw_label].to_s.downcase
+        # `_` is a word char, so `\b` regexes need underscores converted to spaces.
+        label = proposal[:raw_label].to_s.downcase.tr("_", " ")
         case label
         when /amount|salary|income|balance|fee|tier3/ then :money
-        when /\bdate\b|birth|expiry|employed/ then :date
+        when /\bdate\b|\bdob\b|birth|expiry|employed/ then :date
         when /email/ then :email
         when /years|tenor|number of|\bno\.?\b/ then :number
         else :string
@@ -187,6 +195,12 @@ module AcroForge
         end
       end
 
+      # Mirrors aggregate_proposals — keeps merged schemas free of hollow `variations: []`.
+      result.each_value do |entry|
+        next unless entry.is_a?(Hash) && entry[:variations].is_a?(Array) && entry[:variations].empty?
+        entry.delete(:variations)
+      end
+
       result
     end
 

data/lib/acroforge/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acroforge
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Maxwell Nana Forson
@@ -75,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.12
 specification_version: 4
 summary: PDF AcroForm engine with heuristic-assisted field relabeling.
 test_files: []