acrofill 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7b9246e478c6ab2f8206ba44e766a2b4e9e9a946a48245d171d7e212bac54d2
-  data.tar.gz: e6f70298a5008e1419089328788cb1d66908cd3e2edfa2e3bd724e0a220ff176
+  metadata.gz: 2004f19b67792da81c96fb674f6659f9a8da74929334c73a7a46705337cf3545
+  data.tar.gz: 427e766a9775dfdbc5d6651c993418b0bf6d29694bc9462cae69aa719e242532
 SHA512:
-  metadata.gz: 4f858c6d8e34cf948d8ef554d31d9e0a7187408f256fadff63c15bd4af3ad6ad6e61329770e9db506482f179635b9305393d432a9176742893aa45643810f22c
-  data.tar.gz: 75b8174ebb610ec9be61a7b214a69a47071d5aa797bb13378917eb3d41b4279c9ee81e1348641703dd29e5436ca1dcda30148b3e50c70759b2d47fad8c137cb1
+  metadata.gz: c8b11295461d44e3ce2fe61ecd3b066f70fe60f69fd84ad9d38b7606eae4cc08d059ffd921e65cc75cc768b454af37e822d9f7b823d03ba6e768200aa0e3457e
+  data.tar.gz: fc4eae29263ce69cd1ac90c015b02f2b321fe6e8e3df8c5091b6888024fcc084a54919b158edfd5a7209ab426b697e37da908409a48ca81dfa9b5b00b477b9c1

data/CHANGELOG.md

@@ -7,6 +7,104 @@ 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
+
+- Comb fields (`/Ff` bit 25 with `/MaxLen`) lay each character out centered
+  in its own cell, `/Q` choosing which run of cells the value occupies,
+  matching pdftk cell for cell. They previously rendered as plain text.
+
+### Fixed
+
+- A value is now written in the codes its font actually draws it with. A
+  `/DR` font whose `/Encoding` carries a `/Differences` array moves glyphs
+  to other codes; writing the raw bytes drew whatever glyph happened to sit
+  there — a font mapping "A" to code 90 rendered "AZ" as "ZA". Widths
+  follow the emitted code, so measurement and rendering stay in step.
+
+### Changed
+
+- Flattening no longer stamps widgets a viewer would not display: `/F`
+  Hidden (bit 2) was already dropped, and NoView (bit 6, "not on screen",
+  PDF 32000 §12.5.3) now is too. pdftk stamps both, but burning in a
+  widget the template author concealed makes hidden values permanently
+  visible, so parity loses here. Widgets that are merely non-printing are
+  still stamped: they are what the viewer shows.
+
 ## [0.3.0] - 2026-07-27
 
 ### Fixed
@@ -142,7 +240,9 @@ 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.3.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
 [0.1.2]: https://github.com/stiig/acrofill/compare/v0.1.1...v0.1.2

data/README.md

@@ -91,11 +91,16 @@ your own templates with:
 ruby benchmark/geometry_diff.rb path/to/form.pdf
 ```
 
-Three differences are deliberate: acrofill shrinks an overlong value to fit
-where pdftk clips it, it writes Windows-1252 for non-ASCII values where
-pdftk emits UTF-8 bytes into a WinAnsi font (which renders as mojibake), and
-it caps auto-sized (`0 Tf`) text at 12pt where pdftk scales it to fill the
-box. See the changelog for the measured numbers.
+Flattened output was checked the same way: on those four forms every
+stamped fragment lands where pdftk stamps it, bar the fields covered by the
+deliberate differences below.
+
+Four differences are deliberate: acrofill shrinks an overlong value to fit
+where pdftk clips it; it writes Windows-1252 for non-ASCII values where
+pdftk emits UTF-8 bytes into a WinAnsi font (which renders as mojibake); it
+caps auto-sized (`0 Tf`) text at 12pt where pdftk scales it to fill the box;
+and it drops widgets flagged Hidden or NoView when flattening instead of
+burning them into the page. See the changelog for the measured numbers.
 
 ## Performance
 
@@ -194,6 +199,7 @@ Supported:
   rather than all measured as Helvetica.
 - Checkboxes and radio groups (`/Btn`) — state selection via `/V`+`/AS`
   using the template's own appearance states.
+- Comb fields (`/Ff` bit 25) — one character centered per `/MaxLen` cell.
 - Choice fields (`/Ch`) — value set and rendered like text.
 - Flattening — every visible widget appearance is stamped into the page
   content; widget annotations and the AcroForm dictionary are removed.
@@ -204,8 +210,7 @@ Not supported (rejected or ignored, never a hard crash):
 
 - Encrypted documents (raise `Acrofill::Error`), XFA forms, digital
   signatures, JavaScript actions.
-- Push buttons; comb fields render as plain text; rich text (`/RV`) is
-  dropped on fill.
+- Push buttons; rich text (`/RV`) is dropped on fill.
 - Glyphs outside Windows-1252 in generated appearances (stored values
   keep full Unicode; unrenderable glyphs appear as `?`).
 

data/lib/acrofill/appearance.rb

@@ -7,8 +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
@@ -18,51 +26,81 @@ 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)
-      rect = normalized_rect(widget[:Rect] || @doc.inherited_value(field_node, :Rect))
+    def build(field_node, widget, value, multiline: false, comb: nil)
+      rect = @doc.normalized_box(widget[:Rect] || @doc.inherited_value(field_node, :Rect))
       return nil unless rect
 
-      width = rect[2] - rect[0]
-      height = rect[3] - rect[1]
-      return nil if width <= 0 || height <= 0
+      box = Box.new(rect[2] - rect[0], rect[3] - rect[1], alignment(field_node))
+      return nil if box.width <= 0 || box.height <= 0
 
       font_name, size, color_ops = parse_da(field_node)
       font = @fonts.metrics(font_name)
-      align = alignment(field_node)
+      size, body = draw(value, font, size, box, multiline: multiline, comb: comb)
 
-      body =
-        if multiline
-          size = 12.0 if size <= 0
-          size = size.clamp(2.0, 144.0)
-          multiline_body(value, font, size, width, height, align)
-        else
-          text = printable_text(value)
-          size = [height * 0.66, 12.0].min if size.zero?
-          size = shrink_to_fit(text, font, size, width)
-          "#{fmt(line_x(text, font, size, width, align))} #{fmt(baseline(height, font, size))} Td\n" \
-            "(#{escape_literal(text)}) Tj\n"
-        end
+      @doc.add(StreamObject.new(appearance_dict(font_name, box),
+                                content(font_name, size, color_ops, body).b))
+    end
+
+    private
+
+    def fmt(num)
+      Serializer.format_number(num.to_f)
+    end
+
+    # 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
+        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
+        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.positive? ? size : [height * 0.66, DEFAULT_SIZE].min
+    end
 
-      content = +"/Tx BMC\nq\nBT\n"
-      content << "#{color_ops}\n" unless color_ops.empty?
-      content << "/#{font_name} #{fmt(size)} Tf\n"
-      content << body
-      content << "ET\nQ\nEMC\n"
+    def content(font_name, size, color_ops, body)
+      stream = +"/Tx BMC\nq\nBT\n"
+      stream << "#{color_ops}\n" unless color_ops.empty?
+      stream << "/#{font_name} #{fmt(size)} Tf\n"
+      stream << body
+      stream << "ET\nQ\nEMC\n"
+    end
 
-      dict = {
+    def appearance_dict(font_name, box)
+      {
         Type: :XObject,
         Subtype: :Form,
         FormType: 1,
-        BBox: [0, 0, width, height],
+        BBox: [0, 0, box.width, box.height],
         Resources: { Font: { font_name.to_sym => @fonts.reference(font_name) } }
       }
-      @doc.add(StreamObject.new(dict, content.b))
-    end
-
-    private
-
-    def fmt(num)
-      Serializer.format_number(num.to_f)
     end
 
     # Where pdftk puts a single line's baseline: the ascent box centered in
@@ -84,72 +122,90 @@ module Acrofill
       align.is_a?(Integer) ? align : 0
     end
 
-    def line_x(text, font, size, width, align)
-      text_width = Metrics.string_width(text, font.widths, size)
-      case align
-      when 1 then [(width - text_width) / 2.0, PADDING].max
-      when 2 then [width - PADDING - text_width, PADDING].max
+    # +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)
+      case box.align
+      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
 
+    # A comb field divides its box into /MaxLen equal cells and centers one
+    # character in each; /Q picks the run of cells the value occupies. Each
+    # glyph is positioned absolutely, the way pdftk writes it.
+    def comb_body(text, font, size, box, cells)
+      cell = box.width / cells.to_f
+      chars = text.chars
+      first = case box.align
+              when 1 then [(cells - chars.size) / 2, 0].max
+              when 2 then [cells - chars.size, 0].max
+              else 0
+              end
+      ty = fmt(baseline(box.height, font, size))
+      chars.each_with_index.map do |char, index|
+        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
+
     # Greedy word wrap, top-down, honouring explicit line breaks. Lines
     # that would fall below the box are clipped by the BBox.
-    def multiline_body(value, font, size, width, height, align)
-      max_width = width - (2 * PADDING)
+    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(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 = 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, width, align)
+        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.
@@ -166,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.
@@ -178,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

@@ -6,6 +6,8 @@ module Acrofill
   # comes from the template, so each one is validated before use.
   class Flattener
     HIDDEN_FLAG = 2
+    NOVIEW_FLAG = 32
+    INVISIBLE = HIDDEN_FLAG | NOVIEW_FLAG
 
     def initialize(doc)
       @doc = doc
@@ -29,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)
@@ -55,21 +62,34 @@ 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)
-      return nil if annotation_flags(widget).anybits?(HIDDEN_FLAG)
+    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
+      # stamps both, but stamping Hidden makes values the template author
+      # concealed permanently visible, so parity loses here.
+      return nil if annotation_flags(widget).anybits?(INVISIBLE)
 
       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
@@ -81,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
@@ -96,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 = []
@@ -106,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
 
@@ -125,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

@@ -15,6 +15,7 @@ module Acrofill
   #   widths     /Widths + /FirstChar, else the standard-14 table
   #   ascender   /FontDescriptor /Ascent, else standard-14 AFM, else 800
   #   FontBBox   /FontDescriptor /FontBBox, else standard-14 AFM, else 900/-200
+  #   codes      /Encoding /Differences remap the value's bytes
   #
   # The standard-14 fallbacks apply only to a BaseFont that literally names
   # one of the fourteen; a face merely *resembling* one (ArialMT and friends)
@@ -40,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
@@ -51,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
 
@@ -67,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)
@@ -82,8 +84,33 @@ 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)
-                   .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
+    # counter and each following name takes the next code (PDF 32000
+    # §9.6.6.1).
+    def differences(dict)
+      encoding = @doc.deref(dict[:Encoding])
+      return {} unless encoding.is_a?(Hash)
+
+      entries = @doc.deref(encoding[:Differences])
+      return {} unless entries.is_a?(Array)
+
+      code = nil
+      entries.each_with_object({}) do |raw, result|
+        item = @doc.deref(raw)
+        case item
+        when Integer then code = item
+        when Symbol
+          next unless code&.between?(0, 255)
+
+          result[code] = item # a glyph name, matching Metrics::WIN_ANSI_GLYPHS
+          code += 1
+        end
+      end
     end
 
     def base_font_name(dict)
@@ -113,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
       ]
@@ -125,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

@@ -6,6 +6,12 @@ module Acrofill
   class Form
     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)
 
@@ -43,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
@@ -86,10 +98,12 @@ module Acrofill
       node[:V] = pdf_text_string(value)
       node.delete(:RV)
       node.delete(:I)
-      multiline = field_flags(node).anybits?(MULTILINE_FLAG)
+      flags = field_flags(node)
+      multiline = flags.anybits?(MULTILINE_FLAG)
+      comb = comb_cells(node, flags, multiline)
       group[:widgets].each do |widget|
         widget.delete(:AS)
-        ap_ref = @appearance.build(node, widget, value, multiline: multiline) unless value.empty?
+        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.
@@ -102,6 +116,16 @@ module Acrofill
       true
     end
 
+    # How many cells a comb field lays its value out in, or nil when the
+    # field is not a comb. The flag only means anything alongside /MaxLen
+    # and on a single-line field (PDF 32000 §12.7.4.3).
+    def comb_cells(node, flags, multiline)
+      return nil if multiline || !flags.anybits?(COMB_FLAG)
+
+      cells = @doc.deref(@doc.inherited_value(node, :MaxLen))
+      cells.is_a?(Integer) && cells.positive? ? cells : nil
+    end
+
     # Checkboxes and radio groups carry per-state appearance streams, so
     # filling only selects a state: /V on the field, /AS on each widget.
     # The value may be a state name ("Yes"), or anything non-empty when the
@@ -118,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
@@ -214,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

@@ -16,6 +16,9 @@ module Acrofill
     FIRST_CODE = 32
     LAST_CODE = 255
     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 = {
@@ -26,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 = {
@@ -158,8 +165,55 @@ module Acrofill
       'Courier-BoldOblique' => [629, -157, 801, -250].freeze
     }.freeze
 
-    # Everything the appearance code needs about one resolved face.
-    Font = Struct.new(:widths, :ascender, :descender, :bbox_top, :bbox_bottom) do
+    # WinAnsiEncoding glyph names, index = code - 32. Used to re-encode a
+    # value for a font whose /Encoding remaps codes: the value is turned
+    # into glyph names, then into the codes *this* font draws them at.
+    WIN_ANSI_GLYPHS = [
+      :space, :exclam, :quotedbl, :numbersign, :dollar, :percent, :ampersand, :quotesingle,
+      :parenleft, :parenright, :asterisk, :plus, :comma, :hyphen, :period, :slash, :zero,
+      :one, :two, :three, :four, :five, :six, :seven, :eight, :nine, :colon, :semicolon,
+      :less, :equal, :greater, :question, :at, :A, :B, :C, :D, :E, :F, :G, :H, :I, :J, :K,
+      :L, :M, :N, :O, :P, :Q, :R, :S, :T, :U, :V, :W, :X, :Y, :Z, :bracketleft, :backslash,
+      :bracketright, :asciicircum, :underscore, :grave, :a, :b, :c, :d, :e, :f, :g, :h, :i,
+      :j, :k, :l, :m, :n, :o, :p, :q, :r, :s, :t, :u, :v, :w, :x, :y, :z, :braceleft, :bar,
+      :braceright, :asciitilde, :controlDEL, :Euro, nil, :quotesinglbase, :florin,
+      :quotedblbase, :ellipsis, :dagger, :daggerdbl, :circumflex, :perthousand, :Scaron,
+      :guilsinglleft, :OE, nil, :Zcaron, nil, nil, :quoteleft, :quoteright, :quotedblleft,
+      :quotedblright, :bullet, :endash, :emdash, :tilde, :trademark, :scaron,
+      :guilsinglright, :oe, nil, :zcaron, :Ydieresis, :space, :exclamdown, :cent, :sterling,
+      :currency, :yen, :brokenbar, :section, :dieresis, :copyright, :ordfeminine,
+      :guillemotleft, :logicalnot, :hyphen, :registered, :macron, :degree, :plusminus,
+      :twosuperior, :threesuperior, :acute, :mu, :paragraph, :periodcentered, :cedilla,
+      :onesuperior, :ordmasculine, :guillemotright, :onequarter, :onehalf, :threequarters,
+      :questiondown, :Agrave, :Aacute, :Acircumflex, :Atilde, :Adieresis, :Aring, :AE,
+      :Ccedilla, :Egrave, :Eacute, :Ecircumflex, :Edieresis, :Igrave, :Iacute, :Icircumflex,
+      :Idieresis, :Eth, :Ntilde, :Ograve, :Oacute, :Ocircumflex, :Otilde, :Odieresis,
+      :multiply, :Oslash, :Ugrave, :Uacute, :Ucircumflex, :Udieresis, :Yacute, :Thorn,
+      :germandbls, :agrave, :aacute, :acircumflex, :atilde, :adieresis, :aring, :ae,
+      :ccedilla, :egrave, :eacute, :ecircumflex, :edieresis, :igrave, :iacute, :icircumflex,
+      :idieresis, :eth, :ntilde, :ograve, :oacute, :ocircumflex, :otilde, :odieresis,
+      :divide, :oslash, :ugrave, :uacute, :ucircumflex, :udieresis, :yacute, :thorn,
+      :ydieresis
+    ].freeze
+
+    # 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,
+                      :code_widths) do
+      # Windows-1252 text as the byte codes this font draws it with.
+      def encode(text)
+        return text unless remap
+
+        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
@@ -170,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
@@ -225,14 +337,15 @@ module Acrofill
       (BOLD.match?(lower) ? 1 : 0) + (ITALIC.match?(lower) ? 2 : 0)
     end
 
-    # Appearance text is already Windows-1252; anything else is converted so
-    # that measuring and rendering agree byte for byte.
+    # Appearance text is already Windows-1252, or raw font codes after
+    # #encode; anything else is converted so that measuring and rendering
+    # agree byte for byte.
     def self.to_win_ansi(str)
-      return str if str.encoding == WINDOWS_1252
+      return str if BYTE_ENCODINGS.include?(str.encoding)
 
       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.3.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.3.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'