acrofill 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 633b173570db39e5b16714fd23e558a6832ed36f38a549802eb9dcda64967854
-  data.tar.gz: 26d94b282728f297c7c61d51ed817749d8435ecdd6dd4962a11942ac0af30fe9
+  metadata.gz: 2004f19b67792da81c96fb674f6659f9a8da74929334c73a7a46705337cf3545
+  data.tar.gz: 427e766a9775dfdbc5d6651c993418b0bf6d29694bc9462cae69aa719e242532
 SHA512:
-  metadata.gz: c5aad0c14c51e0d9e28a2c4c09b03d840b01c91ef83908ea0d31674f12ff0e4da8c33e7918600ba8ef409313a4faf0e8cfad30b325b3e23fa5c2786643fcdc97
-  data.tar.gz: 18be3697b53f7fe00d6d815a8cd7e0755ca3eef63eccc02e4f9dba181c4a14df648b05289e10ba9bf92b4e0ff62032ff9b1f42a6464a4ed3b75cd2c09b693261
+  metadata.gz: c8b11295461d44e3ce2fe61ecd3b066f70fe60f69fd84ad9d38b7606eae4cc08d059ffd921e65cc75cc768b454af37e822d9f7b823d03ba6e768200aa0e3457e
+  data.tar.gz: fc4eae29263ce69cd1ac90c015b02f2b321fe6e8e3df8c5091b6888024fcc084a54919b158edfd5a7209ab426b697e37da908409a48ca81dfa9b5b00b477b9c1

data/CHANGELOG.md

@@ -7,6 +7,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-07-27
+
+### Fixed
+
+- A `/Rect` or `/BBox` whose corners are not four finite numbers, or whose
+  width or height overflows, is now refused as unusable geometry (no
+  appearance, `/AP` dropped) rather than laid out against. Subtracting two
+  infinite corners produced a NaN extent that every `<= 0` guard silently
+  passed, so the widget either raised `ArgumentError` out of
+  `Acrofill.fill_form` or was drawn into a box that serialized to
+  `[0 0 0 0]` — blank, while `/V` already held the new value.
+- A non-finite `/Matrix` on an appearance stream is treated as the identity,
+  the way a missing or otherwise malformed one already was. Flattening a
+  widget whose form XObject carried one raised `ArgumentError`.
+- A non-finite point size in a `/DA` string degrades to "fit the box", the
+  way a `/DA` with no size already does, rather than raising. A finite but
+  enormous one no longer overflows while being scaled down to fit.
+- `Acrofill.new(path, flatten: true)` now applies that option to every
+  `#fill_form` call, matching the `PdfForms.new` shape it mirrors. Options
+  given to the constructor were accepted and discarded, so the drop-in path
+  shipped interactive documents where flattened ones were asked for.
+- `Template#fill_form` refuses a destination equal to its own source instead
+  of overwriting the template in place. The argument order is the reverse of
+  `Filler#fill_form`, and since `Template` never re-reads the file the
+  corruption stayed invisible for the life of the process.
+- A widget whose `/Rect` is inherited from its parent field is now stamped
+  when flattening. The value was filled, then dropped from the output.
+- Fields sharing one fully-qualified name but not one `/FT` are each filled
+  through their own type's path. A checkbox sharing a name with a text field
+  had its `/AP` state dictionary overwritten with a text appearance.
+- Checkbox values are matched case-insensitively, so `"off"`, `"No"` and `0`
+  uncheck rather than falling through and ticking the box. A state the
+  template itself names still wins.
+- Field names that are neither UTF-16BE nor UTF-8 are decoded rather than
+  scrubbed. Every accented byte became U+FFFD, renaming the field to
+  something no caller could pass back in.
+- Glyph widths are measured in the font's own code space, so a `/Encoding`
+  that moves a glyph onto a code below 32 measures that glyph instead of
+  charging the average width. Multiline wrapping likewise runs before
+  encoding, so a font that moves the space glyph off code 32 still wraps.
+- Font names are no longer read as width classes by substring alone:
+  `MonotypeCorsiva` is proportional, `Blackadder-ITC` is not bold, while
+  `Arial-Black` and `CourierNewPSMT` still classify as before.
+- `/DA` colour operands on opposite sides of the `Tf` triple are no longer
+  joined, which could fuse tokens that were never adjacent into a valid
+  looking operator and repaint the value.
+- A negative `/DA` size is treated as "fit the box", like zero, instead of
+  rendering at the 2pt floor on single-line fields but 12pt on multiline.
+- Flattening drops an annotation reference that resolves to nothing (it
+  serialized as a bare `null` in `/Annots`), honours an indirect `/Subtype`,
+  refuses a degenerate `/Rect` that would produce a singular matrix, and
+  survives a `/Matrix` whose finite entries multiply out of range.
+- A `/DR` font entry that is not a font dictionary no longer reaches the
+  generated appearance's `/Resources`, where it left `/Tf` pointing at a
+  non-font object.
+- A page's `/Resources` reached through `/Parent` is copied before the stamp
+  `/XObject` is added, so pages sharing that node are left alone.
+- `File.binwrite` failures surface as `Acrofill::Error`, the error the public
+  API documents, rather than a bare `Errno`.
+
+### Changed
+
+- `Acrofill::Metrics` exposes `.remap_for` (the `/Differences` code table)
+  and `Metrics::Font#width_of`; `Acrofill::Document` exposes
+  `#normalized_box`. These replace private copies that `Fonts`, `Appearance`
+  and `Flattener` each carried.
+- `Metrics.string_width` takes a 256-entry code-space table (from the new
+  `Metrics.build_font`) rather than a `/Widths`-shaped one indexed from code
+  32. Passing a `BaseFont` name still works.
+- The release workflow runs the specs and RuboCop before publishing; a tag
+  push matched no trigger in the CI workflow, so the gem could be pushed
+  with no test run behind it.
+
 ## [0.4.0] - 2026-07-27
 
 ### Added
@@ -167,7 +240,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `PdfForms`-compatible entry points (`Acrofill.new`, `fill_form`, `fields`,
   `field_names`).
 
-[Unreleased]: https://github.com/stiig/acrofill/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/stiig/acrofill/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/stiig/acrofill/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/stiig/acrofill/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/stiig/acrofill/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/stiig/acrofill/compare/v0.1.2...v0.2.0

data/lib/acrofill/appearance.rb

@@ -7,11 +7,16 @@ module Acrofill
     PADDING = 2.0
     # pdftk offsets the first multiline row by 1pt from the box top.
     TOP_OFFSET = 1.0
+    DEFAULT_SIZE = 12.0
+    MIN_SIZE = 2.0
+    MAX_SIZE = 144.0
 
     # The drawable area of one widget: its size and the field's /Q.
     Box = Struct.new(:width, :height, :align)
     # Colour-setting operators allowed in a /DA string, and their operand counts.
     COLOR_OP_ARITY = { 'g' => 1, 'rg' => 3, 'k' => 4 }.freeze
+    # A plain PDF real; exponent notation is not valid PDF number syntax.
+    NUMERIC_OPERAND = /\A-?\d*\.?\d+\z/
 
     def initialize(doc, acroform)
       @doc = doc
@@ -22,7 +27,7 @@ module Acrofill
     # Returns a Reference to the new appearance XObject, or nil when the
     # widget geometry is unusable.
     def build(field_node, widget, value, multiline: false, comb: nil)
-      rect = normalized_rect(widget[:Rect] || @doc.inherited_value(field_node, :Rect))
+      rect = @doc.normalized_box(widget[:Rect] || @doc.inherited_value(field_node, :Rect))
       return nil unless rect
 
       box = Box.new(rect[2] - rect[0], rect[3] - rect[1], alignment(field_node))
@@ -45,23 +50,39 @@ module Acrofill
     # The operators drawing +value+, and the point size they were laid out
     # at — auto-sizing and shrink-to-fit both adjust the /DA size.
     def draw(value, font, size, box, multiline:, comb:)
+      # Multiline wraps the raw value, so it encodes paragraph by paragraph.
       if multiline
-        size = (size <= 0 ? 12.0 : size).clamp(2.0, 144.0)
-        [size, multiline_body(value, font, size, box)]
-      elsif comb
-        size = auto_size(size, box.height).clamp(2.0, 144.0)
-        [size, comb_body(font.encode(printable_text(value)), font, size, box, comb)]
+        pt = legal_size(size <= 0 ? DEFAULT_SIZE : size)
+        return [pt, multiline_body(value, font, pt, box)]
+      end
+
+      text = font.encode(printable_text(value))
+      if comb
+        pt = legal_size(auto_size(size, box.height))
+        [pt, comb_body(text, font, pt, box, comb)]
       else
-        text = font.encode(printable_text(value))
-        size = shrink_to_fit(text, font, auto_size(size, box.height), box.width)
-        [size, "#{fmt(line_x(text, font, size, box))} #{fmt(baseline(box.height, font, size))} Td\n" \
-               "(#{escape_literal(text)}) Tj\n"]
+        pt = legal_size(shrink_to_fit(text, font, auto_size(size, box.height), box.width))
+        [pt, single_line_body(text, font, pt, box)]
       end
     end
 
+    # The bounds every layout branch applies to the size it settled on.
+    def legal_size(size)
+      size.clamp(MIN_SIZE, MAX_SIZE)
+    end
+
+    def single_line_body(text, font, size, box)
+      "#{fmt(line_x(text, font, size, box))} #{fmt(baseline(box.height, font, size))} Td\n" \
+        "(#{escape_literal(text)}) Tj\n"
+    end
+
     # A /DA size of 0 means "fit the box"; acrofill caps that at 12pt.
+    # Multiline uses a flat 12pt instead, which is deliberate. A negative
+    # size is as meaningless as a zero one and takes the same path — the
+    # multiline branch already treats the two alike, and disagreeing here
+    # made one flag bit decide between a 12pt and a 2pt rendering.
     def auto_size(size, height)
-      size.zero? ? [height * 0.66, 12.0].min : size
+      size.positive? ? size : [height * 0.66, DEFAULT_SIZE].min
     end
 
     def content(font_name, size, color_ops, body)
@@ -101,11 +122,12 @@ module Acrofill
       align.is_a?(Integer) ? align : 0
     end
 
+    # +text+ is already in the font's own codes. Left alignment needs no
+    # measurement, so it does not pay for one.
     def line_x(text, font, size, box)
-      text_width = Metrics.string_width(text, font.widths, size)
       case box.align
-      when 1 then [(box.width - text_width) / 2.0, PADDING].max
-      when 2 then [box.width - PADDING - text_width, PADDING].max
+      when 1 then [(box.width - font.width_of(text, size)) / 2.0, PADDING].max
+      when 2 then [box.width - PADDING - font.width_of(text, size), PADDING].max
       else PADDING
       end
     end
@@ -123,7 +145,7 @@ module Acrofill
               end
       ty = fmt(baseline(box.height, font, size))
       chars.each_with_index.map do |char, index|
-        x = ((first + index + 0.5) * cell) - (Metrics.string_width(char, font.widths, size) / 2.0)
+        x = ((first + index + 0.5) * cell) - (font.width_of(char, size) / 2.0)
         "1 0 0 1 #{fmt(x)} #{ty} Tm\n(#{escape_literal(char)}) Tj\n"
       end.join
     end
@@ -132,59 +154,58 @@ module Acrofill
     # that would fall below the box are clipped by the BBox.
     def multiline_body(value, font, size, box)
       max_width = box.width - (2 * PADDING)
+      # Wrapping runs on the Windows-1252 text, not on the font's codes: a
+      # /Encoding that moves the space glyph off code 32 would otherwise
+      # leave String#split no word boundary to find, and the whole value
+      # would be emitted as one unwrapped line running past the box.
       lines = value.to_s.split(/\r\n|[\r\n]/).flat_map do |paragraph|
-        wrap_line(font.encode(printable_text(paragraph)), font, size, max_width)
+        wrap_line(printable_text(paragraph), font, size, max_width)
       end
 
       # pdftk spaces rows by the font's FontBBox extent and drops the first
-      # baseline by that extent from the top of the box.
+      # baseline by that extent from the top of the box. A first row below
+      # the box floor is clipped away by the BBox, which would leave the
+      # widget blank while /V already holds the new value.
       leading = font.line_height(size)
-      first_y = box.height - font.top(size) + TOP_OFFSET
+      first_y = [box.height - font.top(size) + TOP_OFFSET, 0.0].max
       body = "#{fmt(leading)} TL\n"
       previous_x = 0.0
       lines.each_with_index do |line, index|
-        x = line_x(line, font, size, box)
+        encoded = font.encode(line)
+        x = line_x(encoded, font, size, box)
         body << "#{fmt(x - previous_x)} #{index.zero? ? fmt(first_y) : '0'} Td\n"
-        body << "(#{escape_literal(line)}) Tj\nT*\n"
+        body << "(#{escape_literal(encoded)}) Tj\nT*\n"
         previous_x = x
       end
       body
     end
 
-    # Greedy wrap. Line and space widths are accumulated incrementally so
-    # the cost is O(total characters), not O(words * line-length).
+    # Greedy wrap over unencoded text. The running width is accumulated
+    # incrementally and each line is appended to in place, so the cost is
+    # O(total characters), not O(words * line-length).
     def wrap_line(text, font, size, max_width)
-      space = Metrics.string_width(' ', font.widths, size)
-      lines = ['']
-      so_far = [0.0]
+      space = measure(' ', font, size)
+      lines = [+'']
+      width = 0.0
       text.split.each do |word|
-        word_width = Metrics.string_width(word, font.widths, size)
+        word_width = measure(word, font, size)
         if lines.last.empty?
-          lines[-1] = word
-          so_far[-1] = word_width
-        elsif so_far.last + space + word_width <= max_width
-          lines[-1] = "#{lines.last} #{word}"
-          so_far[-1] += space + word_width
+          lines[-1] = +word
+          width = word_width
+        elsif width + space + word_width <= max_width
+          lines.last << ' ' << word
+          width += space + word_width
         else
-          lines << word
-          so_far << word_width
+          lines << +word
+          width = word_width
         end
       end
       lines
     end
 
-    # Array entries may legally be indirect objects, so each corner is
-    # dereferenced; a rect that is not four numbers is unusable.
-    def normalized_rect(rect)
-      rect = @doc.deref(rect)
-      return nil unless rect.is_a?(Array) && rect.size == 4
-
-      nums = rect.map { |n| @doc.deref(n) }
-      return nil unless nums.all?(Numeric)
-
-      xs = [nums[0].to_f, nums[2].to_f].sort
-      ys = [nums[1].to_f, nums[3].to_f].sort
-      [xs[0], ys[0], xs[1], ys[1]]
+    # Width of unencoded text in the codes the font actually draws it with.
+    def measure(text, font, size)
+      font.width_of(font.encode(text), size)
     end
 
     # /DA is e.g. "/Helv 8 Tf 0 g": font + size around Tf, plus a colour.
@@ -201,9 +222,21 @@ module Acrofill
       return ['Helv', 0.0, '0 g'] unless tf && tf >= 2
 
       font = sanitize_font(tokens[tf - 2].to_s.delete_prefix('/'))
-      size = tokens[tf - 1].to_f
-      color = safe_color_ops(tokens[0...(tf - 2)] + tokens[(tf + 1)..])
-      [font, size, color]
+      # The two sides of the removed "font size Tf" triple are scanned
+      # separately: concatenating them first makes tokens that were never
+      # adjacent in the /DA look like a well-formed operator, so
+      # "0.2 0.4 /Helv 12 Tf 0.6 rg" would emit "0.2 0.4 0.6 rg" and draw
+      # the value in a colour the template never asked for.
+      color = safe_color_ops(tokens[0...(tf - 2)], tokens[(tf + 1)..])
+      [font, size_of(tokens[tf - 1]), color]
+    end
+
+    # The /DA point size, which is template data: a non-finite one would
+    # poison every measurement it feeds, so it degrades to 0 — the same
+    # "fit the box" request a /DA that omits a size makes.
+    def size_of(token)
+      size = token.to_f
+      size.finite? ? size : 0.0
     end
 
     # Only a name made of PDF-regular characters may be written as /Name.
@@ -213,28 +246,38 @@ module Acrofill
 
     # Keep only well-formed colour-setting operators (g / rg / k) with the
     # right count of numeric operands immediately before them; drop anything
-    # else the /DA might carry.
-    def safe_color_ops(tokens)
-      ops = []
-      tokens.each_with_index do |tok, i|
+    # else the /DA might carry. Each segment is scanned on its own, so
+    # adjacency means adjacency in the original string.
+    def safe_color_ops(*segments)
+      ops = segments.flat_map { |tokens| color_ops_in(tokens || []) }
+      ops.empty? ? '0 g' : ops.join(' ')
+    end
+
+    def color_ops_in(tokens)
+      tokens.each_with_index.filter_map do |tok, i|
         arity = COLOR_OP_ARITY[tok]
-        next unless arity
+        # `i >= arity` keeps the fixed-length slice below in bounds: a
+        # negative start would wrap around to the end of the array.
+        next unless arity && i >= arity
 
-        operands = tokens[[i - arity, 0].max...i]
-        next unless operands.size == arity && operands.all? { |o| o =~ /\A-?\d*\.?\d+\z/ }
+        operands = tokens[i - arity, arity]
+        next unless operands.all? { |o| NUMERIC_OPERAND.match?(o) }
 
-        ops << "#{operands.join(' ')} #{tok}"
+        "#{operands.join(' ')} #{tok}"
       end
-      ops.empty? ? '0 g' : ops.join(' ')
     end
 
     # Fixed sizes that overflow the box are scaled down so the whole value
     # stays visible (Acrobat-style best-fit; pdftk would clip instead).
     def shrink_to_fit(text, font, size, width)
       max_width = width - (2 * PADDING)
-      text_width = Metrics.string_width(text, font.widths, size)
-      size *= max_width / text_width if text_width > max_width && text_width.positive?
-      size.clamp(2.0, 144.0)
+      text_width = font.width_of(text, size)
+      return size unless text_width > max_width && text_width.positive?
+
+      # The ratio is applied to +size+, never `size * max_width` first: a
+      # large /DA size makes that product overflow to Infinity, and
+      # Infinity / Infinity is a NaN that no later clamp can recover from.
+      size * (max_width / text_width)
     end
 
     def printable_text(value)

data/lib/acrofill/document.rb

@@ -136,6 +136,27 @@ module Acrofill
       end
     end
 
+    # A /Rect or /BBox as [llx, lly, urx, ury]: the value and each corner may
+    # be indirect, and the corners may be given in either order. Returns nil
+    # when it is not four finite numbers — a non-finite corner would subtract
+    # into a NaN width or height, which every later comparison silently
+    # passes and every later clamp raises on.
+    def normalized_box(raw)
+      box = deref(raw)
+      return nil unless box.is_a?(Array) && box.size == 4
+
+      corners = box.map { |value| deref(value) }
+      return nil unless corners.all? { |corner| corner.is_a?(Numeric) && corner.to_f.finite? }
+
+      xs = [corners[0].to_f, corners[2].to_f].sort
+      ys = [corners[1].to_f, corners[3].to_f].sort
+      # Corners far enough apart still overflow when subtracted, and the
+      # width and height every caller derives have to be usable too.
+      return nil unless (xs[1] - xs[0]).finite? && (ys[1] - ys[0]).finite?
+
+      [xs[0], ys[0], xs[1], ys[1]]
+    end
+
     # Resolves an attribute inheritable through the /Parent chain
     # (field attributes like /FT, /DA, /Q or page attributes).
     def inherited_value(node, key)

data/lib/acrofill/filler.rb

@@ -9,7 +9,12 @@ module Acrofill
   # accepted and ignored — acrofill needs no FDF and is always UTF-aware.
   class Filler
     # Accepts and ignores a pdftk path argument for drop-in compatibility.
-    def initialize(*); end
+    # Options given here are defaults for every #fill_form call, the way
+    # PdfForms.new(path, flatten: true) behaves — accepting them and then
+    # ignoring them would silently ship unflattened documents.
+    def initialize(_pdftk_path = nil, options = {}, **kwargs)
+      @options = (options.is_a?(Hash) ? options : {}).merge(kwargs)
+    end
 
     def fill_form(template, destination, data = {}, options = {})
       apply(Document.new(template), destination, data, options)
@@ -32,20 +37,37 @@ module Acrofill
     # leaking a raw Encoding error from deep inside the appearance code.
     def apply(doc, destination, data, options)
       form = Form.new(doc)
-      data.each do |name, value|
+      (data || {}).each do |name, value|
         form.fill(normalize(name), normalize(value))
       end
-      form.flatten! if options[:flatten] || options['flatten']
-      File.binwrite(destination, Writer.new(doc).render)
+      form.flatten! if flatten?(options)
+      write(destination, Writer.new(doc).render)
       destination
     end
 
     private
 
+    def flatten?(options)
+      [options, @options].any? do |opts|
+        opts.is_a?(Hash) && (opts[:flatten] || opts['flatten'])
+      end
+    end
+
+    # The write is part of the public API's error contract, so a bad path
+    # surfaces as Acrofill::Error like every parse failure does, rather than
+    # as a bare Errno the caller's rescue does not name.
+    def write(destination, bytes)
+      File.binwrite(destination, bytes)
+    rescue SystemCallError, IOError, TypeError => e
+      raise Error, "could not write #{destination.inspect} (#{e.class}: #{e.message})"
+    end
+
     def normalize(value)
       return '' if value.nil?
 
       value.to_s.encode('UTF-8', invalid: :replace, undef: :replace).scrub
+    rescue EncodingError => e
+      raise Error, "could not normalize value (#{e.class}: #{e.message})"
     end
   end
 end

data/lib/acrofill/flattener.rb

@@ -31,22 +31,27 @@ module Acrofill
     def flatten_page(page)
       annot_refs = @doc.deref(page[:Annots])
       annot_refs = [] unless annot_refs.is_a?(Array)
-      annots = annot_refs.map { |a| [a, @doc.deref(a)] }
-      widgets, others = annots.partition { |_ref, dict| dict.is_a?(Hash) && dict[:Subtype] == :Widget }
+      # A reference that does not resolve to a dictionary is dropped rather
+      # than carried over: it has no object to renumber, so the Writer would
+      # serialize it as a bare `null` inside /Annots, which is not a legal
+      # annotation array.
+      annots = annot_refs.filter_map do |ref|
+        dict = @doc.deref(ref)
+        [ref, dict] if dict.is_a?(Hash)
+      end
+      widgets, others = annots.partition { |_ref, dict| @doc.deref(dict[:Subtype]) == :Widget }
       return if widgets.empty?
 
-      stamps = []
-      widgets.each do |_ref, widget|
-        stamp = stamp_operations(page, widget)
-        stamps << stamp if stamp
-      end
+      @pending = {}
+      stamps = widgets.filter_map { |_ref, widget| stamp_operations(widget) }
+      install_xobjects(page, @pending) unless @pending.empty?
 
       unless stamps.empty?
-        wrap = ->(bytes) { @doc.add(StreamObject.new({}, bytes.b)) }
         derefed = @doc.deref(page[:Contents])
         contents = (derefed.is_a?(Array) ? derefed : [page[:Contents]]).compact
-        contents = contents.map { |stream| @doc.ref_for(stream) }
-        page[:Contents] = [wrap.call("q\n"), *contents, wrap.call("\nQ\n#{stamps.join("\n")}\n")]
+                                                                       .map { |stream| @doc.ref_for(stream) }
+        page[:Contents] = [content_stream("q\n"), *contents,
+                           content_stream("\nQ\n#{stamps.join("\n")}\n")]
       end
 
       remaining = others.map(&:first)
@@ -57,12 +62,16 @@ module Acrofill
       end
     end
 
+    def content_stream(bytes)
+      @doc.add(StreamObject.new({}, bytes.b))
+    end
+
     # Returns content-stream operations placing the widget's normal
     # appearance onto the page, or nil when there is nothing to draw.
     # Implements the appearance-box algorithm of PDF 32000 §12.5.5: the
     # form's /Matrix is applied to its BBox, and the resulting extent is
     # mapped onto the annotation rectangle.
-    def stamp_operations(page, widget)
+    def stamp_operations(widget)
       # Flattening produces the document as it is displayed, so a widget the
       # viewer would not show is dropped rather than burned in: /F Hidden,
       # and NoView, which means "not on screen" (PDF 32000 §12.5.3). pdftk
@@ -72,11 +81,15 @@ module Acrofill
 
       ap_ref = normal_appearance(widget)
       xobject = @doc.deref(ap_ref)
-      dict = xobject.is_a?(StreamObject) ? xobject.dict : xobject&.hash
-      return nil unless dict.is_a?(Hash)
-
-      bbox = normalize_box(@doc.deref(dict[:BBox]))
-      rect = normalize_box(@doc.deref(widget[:Rect]))
+      dict = appearance_dict(xobject)
+      return nil unless dict
+
+      bbox = @doc.normalized_box(dict[:BBox])
+      # /Rect is inheritable through the /Parent chain, and Appearance#build
+      # honours that when it draws the value. Reading only widget[:Rect] here
+      # would stamp nothing for a kid widget whose rectangle lives on the
+      # parent field — filling the value and then silently dropping it.
+      rect = @doc.normalized_box(@doc.inherited_value(widget, :Rect))
       return nil unless bbox && rect
 
       # Appearance streams are form XObjects, but /Type and /Subtype are
@@ -88,14 +101,31 @@ module Acrofill
       bx0, by0, bx1, by1 = transformed_bbox(bbox, @doc.deref(dict[:Matrix]))
       bw = bx1 - bx0
       bh = by1 - by0
-      return nil if bw <= 0 || bh <= 0
+      # A degenerate annotation rectangle scales to a singular matrix, which
+      # PDF 32000 §8.3.3 forbids; Appearance#build rejects the same geometry.
+      return nil unless positive_extent?(bw, bh) && positive_extent?(urx - llx, ury - lly)
 
       sx = (urx - llx) / bw
       sy = (ury - lly) / bh
-      name = register_xobject(page, ap_ref)
       matrix = [sx, 0, 0, sy, llx - (bx0 * sx), lly - (by0 * sy)]
-      ops = matrix.map { |n| Serializer.format_number(n.to_f) }
-      "q #{ops.join(' ')} cm /#{name} Do Q"
+      return nil unless matrix.all? { |n| n.to_f.finite? }
+
+      name = register_xobject(ap_ref)
+      "q #{matrix.map { |n| Serializer.format_number(n.to_f) }.join(' ')} cm /#{name} Do Q"
+    end
+
+    # The dictionary of an appearance XObject, or nil. A /AP /N that derefs
+    # to something other than a stream has no dictionary — asking a plain
+    # Hash or Array for #hash would return Object#hash, an Integer.
+    def appearance_dict(xobject)
+      case xobject
+      when StreamObject then xobject.dict
+      when PDF::Reader::Stream then xobject.hash
+      end
+    end
+
+    def positive_extent?(width, height)
+      width.finite? && height.finite? && width.positive? && height.positive?
     end
 
     # Bounding box of the (already normalized) BBox corners after the
@@ -103,8 +133,10 @@ module Acrofill
     def transformed_bbox(bbox, matrix)
       x0, y0, x1, y1 = bbox
       matrix = matrix.map { |m| @doc.deref(m) } if matrix.is_a?(Array)
+      # A non-finite entry is as malformed as a missing one: it multiplies
+      # into the NaN that Array#min then raises on.
       return [x0, y0, x1, y1] unless matrix.is_a?(Array) && matrix.size == 6 &&
-                                     matrix.all?(Numeric)
+                                     matrix.all? { |m| m.is_a?(Numeric) && m.to_f.finite? }
 
       a, b, c, d, e, f = matrix.map(&:to_f)
       xs = []
@@ -113,6 +145,11 @@ module Acrofill
         xs << ((a * x) + (c * y) + e)
         ys << ((b * x) + (d * y) + f)
       end
+      # Finite entries still multiply and add into a NaN (Infinity plus its
+      # negation), which Array#min raises on rather than returning; a
+      # transform that overflows is as unusable as a malformed one.
+      return [x0, y0, x1, y1] unless xs.all?(&:finite?) && ys.all?(&:finite?)
+
       [xs.min, ys.min, xs.max, ys.max]
     end
 
@@ -132,35 +169,27 @@ module Acrofill
       normal
     end
 
-    # Derefs each element (array entries may legally be indirect objects)
-    # and returns [llx, lly, urx, ury], or nil when the box is not four
-    # numbers.
-    def normalize_box(box)
-      return nil unless box.is_a?(Array) && box.size == 4
-
-      nums = box.map { |n| @doc.deref(n) }
-      return nil unless nums.all?(Numeric)
-
-      xs = [nums[0].to_f, nums[2].to_f].sort
-      ys = [nums[1].to_f, nums[3].to_f].sort
-      [xs[0], ys[0], xs[1], ys[1]]
+    # Names the stamp and records it; the page's /Resources are rewritten
+    # once per page by #install_xobjects rather than once per widget.
+    def register_xobject(ap_ref)
+      @stamp_counter += 1
+      name = :"AcrofillAP#{@stamp_counter}"
+      @pending[name] = @doc.ref_for(ap_ref)
+      name
     end
 
     # A page's /Resources (and its /XObject subdictionary) are template
     # data: anything that is not a dictionary is replaced rather than
-    # indexed, which would raise TypeError on an Array or a stream.
-    def register_xobject(page, ap_ref)
+    # indexed, which would raise TypeError on an Array or a stream. Both are
+    # copied before mutation, since a /Resources reached through /Parent is
+    # shared with every other page under that node.
+    def install_xobjects(page, pending)
       resources = @doc.deref(page[:Resources]) || @doc.deref(@doc.inherited_value(page, :Resources))
       resources = resources.is_a?(Hash) ? resources.dup : {}
       xobjects = @doc.deref(resources[:XObject])
       xobjects = xobjects.is_a?(Hash) ? xobjects.dup : {}
-
-      @stamp_counter += 1
-      name = :"AcrofillAP#{@stamp_counter}"
-      xobjects[name] = @doc.ref_for(ap_ref)
-      resources[:XObject] = xobjects
+      resources[:XObject] = xobjects.merge(pending)
       page[:Resources] = resources
-      name
     end
   end
 end

data/lib/acrofill/fonts.rb

@@ -30,7 +30,6 @@ module Acrofill
     # not consult /MissingWidth (verified — setting it changes nothing).
     OUT_OF_RANGE_WIDTH = 0
     SUBSET_PREFIX = /\A[A-Z]{6}\+/
-    IDENTITY = Array.new(256) { |code| code }.freeze
 
     def initialize(doc, acroform)
       @doc = doc
@@ -42,7 +41,7 @@ module Acrofill
     # Metrics::Font for the font a /DA string names.
     def metrics(resource_name)
       key = resource_name.to_sym
-      @metrics[key] ||= build(@doc.deref(entry(key)))
+      @metrics[key] ||= build(@doc.deref(dr_fonts[key]))
     end
 
     # Indirect reference to that font, for the appearance /Resources. Fonts
@@ -53,8 +52,13 @@ module Acrofill
       key = resource_name.to_sym
       @references[key] ||=
         begin
-          found = entry(key)
-          found ? @doc.ref_for(found) : fallback
+          found = dr_fonts[key]
+          # #metrics already degrades to standard Helvetica for a /DR entry
+          # that is not a font dictionary; writing that same entry into the
+          # appearance's /Resources would point /Tf at a non-font object (or
+          # at a dangling reference the Writer serializes as `null`), so the
+          # two have to agree on what counts as usable.
+          @doc.deref(found).is_a?(Hash) ? @doc.ref_for(found) : fallback
         end
     end
 
@@ -69,10 +73,6 @@ module Acrofill
         end
     end
 
-    def entry(key)
-      dr_fonts[key]
-    end
-
     def fallback
       @fallback ||=
         @doc.add(Type: :Font, Subtype: :Type1, BaseFont: :Helvetica, Encoding: :WinAnsiEncoding)
@@ -84,32 +84,9 @@ module Acrofill
       name = base_font_name(dict)
       standard = Metrics.standard_font(name)
       ascender, descender, top, bottom = vertical(dict, standard)
-      Metrics::Font.new(widths(dict) || Metrics.widths_for(name),
-                        ascender, descender, top, bottom, remap(dict)).freeze
-    end
-
-    # A 256-entry code translation table when /Encoding /Differences moves
-    # glyphs to codes other than their WinAnsi ones, else nil. Without it a
-    # value is drawn with whatever glyphs happen to sit at its bytes: a font
-    # that puts "A" at code 90 would render "AZ" as "ZA".
-    def remap(dict)
-      differences = differences(dict)
-      return nil if differences.empty?
-
-      by_code = {}
-      Metrics::WIN_ANSI_GLYPHS.each_with_index do |glyph, index|
-        by_code[index + Metrics::FIRST_CODE] = glyph if glyph
-      end
-      differences.each { |code, glyph| by_code[code] = glyph }
-
-      at = {}
-      by_code.each { |code, glyph| at[glyph] ||= code }
-      table = Array.new(256) { |code| code }
-      Metrics::WIN_ANSI_GLYPHS.each_with_index do |glyph, index|
-        code = glyph && at[glyph]
-        table[index + Metrics::FIRST_CODE] = code if code
-      end
-      table == IDENTITY ? nil : table.freeze
+      Metrics.build_font(widths(dict) || Metrics.widths_for(name),
+                         ascender, descender, top, bottom,
+                         Metrics.remap_for(differences(dict)))
     end
 
     # /Differences is a flat array where an integer restarts the code
@@ -163,11 +140,11 @@ module Acrofill
 
     def vertical(dict, standard)
       descriptor = @doc.deref(dict[:FontDescriptor])
-      descriptor = nil unless descriptor.is_a?(Hash)
+      descriptor = {} unless descriptor.is_a?(Hash)
       bottom, top = font_bbox(descriptor)
       [
-        (descriptor && number(descriptor[:Ascent])) || standard&.ascender || DEFAULT_ASCENDER,
-        (descriptor && number(descriptor[:Descent])) || standard&.descender || DEFAULT_DESCENDER,
+        number(descriptor[:Ascent]) || standard&.ascender || DEFAULT_ASCENDER,
+        number(descriptor[:Descent]) || standard&.descender || DEFAULT_DESCENDER,
         top || standard&.bbox_top || DEFAULT_BBOX_TOP,
         bottom || standard&.bbox_bottom || DEFAULT_BBOX_BOTTOM
       ]
@@ -175,7 +152,7 @@ module Acrofill
 
     # [lower y, upper y] of /FontBBox, or [nil, nil] when it is unusable.
     def font_bbox(descriptor)
-      box = descriptor && @doc.deref(descriptor[:FontBBox])
+      box = @doc.deref(descriptor[:FontBBox])
       return [nil, nil] unless box.is_a?(Array) && box.size == 4
 
       [number(box[1]), number(box[3])]

data/lib/acrofill/form.rb

@@ -7,6 +7,11 @@ module Acrofill
     MULTILINE_FLAG = 1 << 12
     PUSHBUTTON_FLAG = 1 << 16
     COMB_FLAG = 1 << 24
+    # Values that uncheck a button, compared case-insensitively: "Off"
+    # unchecking while "off" ticked the box was a silent data error. A state
+    # the template actually names is matched first, so a checkbox whose on
+    # state is literally called "no" stays checkable.
+    OFF_VALUES = ['', 'off', 'false', 'no', '0'].freeze
 
     Field = Struct.new(:name, :type, :value, :states, keyword_init: true)
 
@@ -44,11 +49,17 @@ module Acrofill
       groups = @fields.fetch(name, [])
       return false if groups.empty?
 
-      case field_type(groups.first[:node])
-      when :Btn then fill_button(groups, value)
-      when :Tx, :Ch, nil then fill_text_groups(groups, value)
-      else false # signatures and unknown types are left untouched
-      end
+      # Several field dicts may share one name without sharing one /FT.
+      # Dispatching on the first one's type would push a checkbox through
+      # the text path, overwriting its /AP state dictionary with a text
+      # appearance, so each type is handled with its own groups.
+      groups.group_by { |group| field_type(group[:node]) }.map do |type, typed|
+        case type
+        when :Btn then fill_button(typed, value)
+        when :Tx, :Ch, nil then fill_text_groups(typed, value)
+        else false # signatures and unknown types are left untouched
+        end
+      end.any?
     end
 
     # Stamps every visible widget appearance into its page's content and
@@ -82,12 +93,6 @@ module Acrofill
       true
     end
 
-    def build_appearance(node, widget, value, multiline, comb)
-      return nil if value.empty?
-
-      @appearance.build(node, widget, value, multiline: multiline, comb: comb)
-    end
-
     def fill_text(group, value)
       node = group[:node]
       node[:V] = pdf_text_string(value)
@@ -98,7 +103,7 @@ module Acrofill
       comb = comb_cells(node, flags, multiline)
       group[:widgets].each do |widget|
         widget.delete(:AS)
-        ap_ref = build_appearance(node, widget, value, multiline, comb)
+        ap_ref = @appearance.build(node, widget, value, multiline:, comb:) unless value.empty?
         # An unusable geometry yields no appearance; dropping /AP is still
         # required, or the widget would keep rendering the *previous* value
         # while /V already holds the new one.
@@ -137,7 +142,7 @@ module Acrofill
       state =
         if named
           named
-        elsif ['', 'Off', 'false', 'no'].include?(value)
+        elsif OFF_VALUES.include?(value.downcase)
           :Off
         elsif states.size == 1
           states.first
@@ -233,7 +238,15 @@ module Acrofill
         raw.byteslice(2..).force_encoding('UTF-16BE')
            .encode('UTF-8', invalid: :replace, undef: :replace)
       else
-        raw.dup.force_encoding('UTF-8').scrub
+        as_utf8 = raw.dup.force_encoding('UTF-8')
+        return as_utf8 if as_utf8.valid_encoding?
+
+        # Not UTF-8, so it is PDFDocEncoded (or Latin-1) — decode it rather
+        # than scrub it. Scrubbing turns every accented byte into U+FFFD,
+        # which renames the field to something no caller can pass back in,
+        # leaving it permanently unfillable.
+        raw.dup.force_encoding('Windows-1252')
+           .encode('UTF-8', invalid: :replace, undef: :replace)
       end
     end
 

data/lib/acrofill/metrics.rb

@@ -18,6 +18,7 @@ module Acrofill
     WINDOWS_1252 = Encoding::Windows_1252
     # Encodings whose bytes are already the codes the font is drawn with.
     BYTE_ENCODINGS = [Encoding::Windows_1252, Encoding::BINARY].freeze
+    IDENTITY = Array.new(256) { |code| code }.freeze
 
     # The standard-14 text cuts, indexed by bold + 2 * italic per family.
     CUTS = {
@@ -28,8 +29,12 @@ module Acrofill
     # Family and weight hints for BaseFont names outside the standard 14.
     SERIF = /times|roman|serif|georgia|garamond/
     SANS = /sans/
-    FIXED = /courier|mono/
-    BOLD = /bold|black|heavy/
+    # "mono" must not swallow the Monotype foundry prefix: MonotypeCorsiva is
+    # a proportional script face, not a typewriter one.
+    FIXED = /courier|mono(?!type)/
+    # Likewise "black" is a weight only at the end of a word — Blackadder and
+    # Blackoak are display faces, Arial-Black and Roboto-Black are weights.
+    BOLD = /bold|black(?![a-z])|heavy/
     ITALIC = /italic|oblique/
 
     TABLES = {
@@ -194,7 +199,8 @@ module Acrofill
     # Everything the appearance code needs about one resolved face. +remap+
     # is a 256-entry code translation table, or nil when the font draws
     # WinAnsi codes as they are.
-    Font = Struct.new(:widths, :ascender, :descender, :bbox_top, :bbox_bottom, :remap) do
+    Font = Struct.new(:widths, :ascender, :descender, :bbox_top, :bbox_bottom, :remap,
+                      :code_widths) do
       # Windows-1252 text as the byte codes this font draws it with.
       def encode(text)
         return text unless remap
@@ -202,6 +208,12 @@ module Acrofill
         text.b.each_byte.map { |code| remap[code] }.pack('C*')
       end
 
+      # Width of +text+ at +size+ points, in points. +text+ is in this font's
+      # own codes (the output of #encode), so it is measured in that space.
+      def width_of(text, size)
+        Metrics.string_width(text, code_widths, size)
+      end
+
       def ascent(size) = ascender * size / 1000.0
 
       def descent(size) = -descender * size / 1000.0
@@ -212,21 +224,79 @@ module Acrofill
       def line_height(size) = (bbox_top - bbox_bottom) * size / 1000.0
     end
 
+    # A frozen Font, with its code-space width table derived once.
+    def self.build_font(widths, ascender, descender, top, bottom, remap = nil)
+      Font.new(widths, ascender, descender, top, bottom, remap,
+               code_width_table(widths, remap)).freeze
+    end
+
+    # Width of the glyph this font draws at each of the 256 byte codes.
+    # +widths+ is indexed by WinAnsi code, but /Differences can move a glyph
+    # onto any code — including one below 32, which no WinAnsi-indexed table
+    # can express — and the appearance stream emits the moved code. Measuring
+    # in the font's own code space is what keeps rendering and metrics in
+    # step; a code the font draws nothing at is worth nothing, not the
+    # average glyph width the old WinAnsi lookup fell back to.
+    def self.code_width_table(widths, remap)
+      table = Array.new(256, 0)
+      (FIRST_CODE..LAST_CODE).each do |code|
+        width = widths[code - FIRST_CODE] || DEFAULT_WIDTH
+        table[remap ? remap[code] : code] = width
+      end
+      table.freeze
+    end
+
     FONTS = VERTICAL.to_h do |name, (asc, desc, top, bottom)|
-      [name, Font.new(WIDTHS[name], asc, desc, top, bottom).freeze]
+      [name, build_font(WIDTHS[name], asc, desc, top, bottom)]
     end.freeze
 
-    # Width of +str+ at +size+ points. +widths+ is a table from #widths_for,
-    # or a BaseFont name (resolved here, at the cost of the lookup).
+    # Width of +str+ at +size+ points. +widths+ is a 256-entry code-space
+    # table from #code_width_table, or a BaseFont name (resolved here, at
+    # the cost of the lookup).
     def self.string_width(str, widths, size)
-      widths = widths_for(widths) unless widths.is_a?(Array)
-      str = to_win_ansi(str)
-      units = str.each_byte.sum do |code|
-        (code >= FIRST_CODE && widths[code - FIRST_CODE]) || DEFAULT_WIDTH
-      end
+      widths = font_for(widths).code_widths unless widths.is_a?(Array)
+      units = to_win_ansi(str).each_byte.sum { |code| widths[code] }
       units * size / 1000.0
     end
 
+    # A 256-entry code translation table for a font whose /Encoding moves
+    # glyphs off their WinAnsi codes, or nil when nothing moves. +differences+
+    # is {code => glyph name}, as /Differences declares it.
+    def self.remap_for(differences)
+      return nil if differences.empty?
+
+      at = drawn_at(differences)
+      table = IDENTITY.dup
+      WIN_ANSI_GLYPHS.each_with_index do |glyph, index|
+        table[index + FIRST_CODE] = at[glyph] if at[glyph]
+      end
+      table == IDENTITY ? nil : table.freeze
+    end
+
+    # glyph => the code this font draws it at. The WinAnsi codes are claimed
+    # first, in ascending order, so a glyph keeps the code it normally has; a
+    # /Differences entry parked on a code WinAnsi leaves undefined (129, 141,
+    # 143, 144, 157, or anything below 32) only wins a glyph that no WinAnsi
+    # code draws. That preference matters because widths are looked up by
+    # code: an embedded /Widths array covers the codes the base encoding uses,
+    # not the holes a subset font parks its spare glyphs in.
+    #
+    # Codes outside a byte are ignored rather than trusted: the table they
+    # would land in is packed with 'C*', which truncates instead of failing.
+    def self.drawn_at(differences)
+      at = {}
+      WIN_ANSI_GLYPHS.each_with_index do |win_ansi, index|
+        next unless win_ansi
+
+        code = index + FIRST_CODE
+        at[differences[code] || win_ansi] ||= code
+      end
+      differences.each do |code, glyph|
+        at[glyph] ||= code if code.is_a?(Integer) && code.between?(0, 255)
+      end
+      at
+    end
+
     # Metrics for a BaseFont name. Standard-14 names resolve directly;
     # anything else (ArialMT, TimesNewRomanPS-BoldMT, a template's embedded
     # face) is classified by family and weight, which is far closer than
@@ -276,6 +346,6 @@ module Acrofill
       str.encode(WINDOWS_1252, invalid: :replace, undef: :replace, replace: '?')
     end
 
-    private_class_method :serif?, :weight_index, :to_win_ansi
+    private_class_method :serif?, :weight_index, :to_win_ansi, :drawn_at
   end
 end

data/lib/acrofill/template.rb

@@ -4,7 +4,7 @@ module Acrofill
   # A pre-parsed, reusable template. Parsing is the dominant cost of a
   # fill (tokenizing and inflating the whole file); Template pays it once
   # and restores a pristine object graph from a Marshal snapshot for each
-  # subsequent fill — roughly 50x faster than re-parsing per fill.
+  # subsequent fill — measured at 7-8x faster per fill on real forms.
   #
   #   template = Acrofill::Template.new('claim_form.pdf')
   #   template.fill_form('a.pdf', { 'Name' => 'Jane' }, flatten: true)
@@ -15,11 +15,20 @@ module Acrofill
   # fill works on its own restored copy.
   class Template
     def initialize(path)
-      doc = Document.new(path)
-      @snapshot = doc.snapshot
+      @source = absolute(path)
+      @snapshot = Document.new(path).snapshot
     end
 
     def fill_form(destination, data = {}, options = {})
+      # Template#fill_form takes the destination first; Filler#fill_form
+      # takes the template first. Passing the template here is the natural
+      # slip, and since Template never re-reads the file the overwrite would
+      # go unnoticed until another consumer opened the corrupted template.
+      if @source && absolute(destination) == @source
+        raise Error, 'destination is the template itself; ' \
+                     'Template#fill_form takes (destination, data, options)'
+      end
+
       Filler.new.apply(Document.restore(@snapshot), destination, data, options)
     end
 
@@ -31,5 +40,15 @@ module Acrofill
     def field_names
       fields.map(&:name)
     end
+
+    private
+
+    # The path +input+ names, resolved so that "form.pdf" and "./form.pdf"
+    # compare equal, or nil when it is not a path at all (an IO, say).
+    # Pure string work: nothing here touches the filesystem.
+    def absolute(input)
+      path = input.respond_to?(:to_path) ? input.to_path : input
+      File.expand_path(path) if path.is_a?(String)
+    end
   end
 end

data/lib/acrofill/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Acrofill
-  VERSION = '0.4.0'
+  VERSION = '0.4.1'
 end

data/lib/acrofill.rb

@@ -15,9 +15,9 @@ require_relative 'acrofill/template'
 module Acrofill
   class Error < StandardError; end
 
-  # Mirrors the PdfForms.new(pdftk_path) constructor shape.
-  def self.new(*)
-    Filler.new(*)
+  # Mirrors the PdfForms.new(pdftk_path, options) constructor shape.
+  def self.new(*, **)
+    Filler.new(*, **)
   end
 
   def self.fill_form(template, destination, data = {}, options = {})

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acrofill
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - stiig
@@ -50,7 +50,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/stiig/acrofill
-  source_code_uri: https://github.com/stiig/acrofill
+  source_code_uri: https://github.com/stiig/acrofill/tree/main
   changelog_uri: https://github.com/stiig/acrofill/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/stiig/acrofill/issues
   rubygems_mfa_required: 'true'