acrofill 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3fd7c0e555d7ae744ba74b2c4bde970f938db256eb22d364584d1923650fa8a
-  data.tar.gz: 2f1f9205e4562e4dd6b483fa2a13a3855cb167c6c3d9b18b92871b3af87a2589
+  metadata.gz: 633b173570db39e5b16714fd23e558a6832ed36f38a549802eb9dcda64967854
+  data.tar.gz: 26d94b282728f297c7c61d51ed817749d8435ecdd6dd4962a11942ac0af30fe9
 SHA512:
-  metadata.gz: c6abbdd9dd06f176b5d916fc8e6a5ab6345b827fb177eb4a8d1844dd6d0d544ab1dc1eca085f33fbd032c05e56bd84506acdc582c610c35ad9fe1335a168f0e1
-  data.tar.gz: fc8550ec29027ee7b8d8023ca441a2aeb39efbc213493852db77bd28a1729d95dfee2dc5b123c31479be74696783c357ba52f1c33a11eb09993bab93ab796e82
+  metadata.gz: c5aad0c14c51e0d9e28a2c4c09b03d840b01c91ef83908ea0d31674f12ff0e4da8c33e7918600ba8ef409313a4faf0e8cfad30b325b3e23fa5c2786643fcdc97
+  data.tar.gz: 18be3697b53f7fe00d6d815a8cd7e0755ca3eef63eccc02e4f9dba181c4a14df648b05289e10ba9bf92b4e0ff62032ff9b1f42a6464a4ed3b75cd2c09b693261

data/CHANGELOG.md

@@ -7,6 +7,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- Single-line baselines now match pdftk when the text is taller than the
+  field, which real forms hit routinely (a 12pt `/DA` in a 10.8pt-high box
+  is common). Centering is bounded on both sides: the ascender is kept
+  inside the box and the baseline never drops below the box floor. This was
+  the last geometry difference on a 551-field sample of real templates.
+- Text is now measured with the metrics of the font it is actually drawn
+  with. A template that embeds its own face declares `/Widths` and a
+  `/FontDescriptor`, and those were ignored in favour of standard-14
+  tables — which put centered and right-aligned values as much as tens of
+  points away from where pdftk puts them (43pt on a 300pt-wide field in
+  one measured case). `/Widths` now drives glyph widths, `/FontDescriptor`
+  `/Ascent` the baseline and its `/FontBBox` the multiline row spacing,
+  falling back to the standard-14 tables only when the dictionary is
+  silent. This is the layout most real-world forms hit, since almost all
+  of them embed a subset face.
+
+### Changed
+
+- Vertical geometry is now font-aware and matches pdftk-java 3.3.3 exactly.
+  Baselines are placed from the font's own AFM ascender instead of a fixed
+  Helvetica value (Times sat 0.18pt low, Courier 0.45pt), and multiline rows
+  are spaced by the font's `FontBBox` extent with pdftk's 1pt top offset
+  instead of a flat `1.15 * size` leading.
+- `Acrofill::Metrics` exposes `.font_for`, returning widths plus ascender,
+  descender and `FontBBox` for one of the twelve standard-14 text cuts.
+  Vertical metrics are stored per cut, since Courier-Bold and Times-Italic
+  differ there even where their widths do not.
+- Font resolution moved out of `Appearance` into `Acrofill::Fonts`, which
+  owns the `/DR /Font` dictionary: metrics for a `/DA` resource name and
+  the reference a generated appearance points at.
+
+### Added
+
+- `benchmark/geometry_diff.rb` compares acrofill's appearance streams with
+  pdftk's field by field on your own templates.
+- `spec/pdftk_parity_spec.rb` pins alignment, baseline and multiline row
+  geometry — for standard-14 faces, template-supplied metrics, and text
+  taller than its field — to numbers measured from pdftk's own output.
+
+### Known differences from pdftk
+
+- Auto-sized fields (`0 Tf`): pdftk picks a font-dependent size that fills
+  the box (16.33pt in a 20pt box for Helvetica, and 20.73pt — taller than
+  the box — for Courier), with a hard 4pt floor. Acrofill keeps its own
+  `min(height * 0.66, 12pt)` and is not going to reproduce that.
+- Values too wide for the field: acrofill shrinks the font to fit, pdftk
+  keeps the size and clips.
+- Non-ASCII values: pdftk writes UTF-8 bytes into a `/WinAnsiEncoding`
+  font, which renders as mojibake; acrofill writes Windows-1252, so the
+  text is correct and the measured width differs accordingly.
+
 ## [0.2.0] - 2026-07-27
 
 ### Fixed
@@ -87,7 +167,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.2.0...HEAD
+[Unreleased]: https://github.com/stiig/acrofill/compare/v0.4.0...HEAD
+[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
 [0.1.1]: https://github.com/stiig/acrofill/compare/v0.1.0...v0.1.1

data/README.md

@@ -75,6 +75,33 @@ filler.fill_form(tpl, out, data, flatten: true)
 
 Unknown field names are silently ignored, matching pdftk.
 
+### Geometry parity
+
+Filled text lands where pdftk puts it: across four real-world
+government claim forms — 551 filled widgets — every appearance agrees with
+pdftk-java 3.3.3 to the two decimals it prints, except where acrofill
+deliberately differs (below). `spec/pdftk_parity_spec.rb` pins that
+placement against numbers read out of pdftk's own appearance streams —
+alignment, baselines for Helvetica/Times/Courier across box heights, text
+taller than its field, multiline row spacing, and the widths, ascent and
+`FontBBox` a template's own font dictionary supplies. Check it against
+your own templates with:
+
+```bash
+ruby benchmark/geometry_diff.rb path/to/form.pdf
+```
+
+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
 
 Because Acrofill runs in-process, it avoids the JVM (or C++ process)
@@ -163,13 +190,16 @@ Supported:
 - Text fields (`/Tx`) — hierarchical names (`parent.kid`), inherited
   `/DA`, alignment via `/Q` (left/center/right), auto font size (`0 Tf`),
   shrink-to-fit for overflowing values, multiline fields (`/Ff` bit 13)
-  with word wrapping, and WinAnsi width metrics for all standard-14 text
-  cuts (Helvetica/Times/Courier, regular through bold-italic). A
-  template's own `/BaseFont` — `ArialMT`, `TimesNewRomanPS-BoldMT`, an
-  embedded subset — is classified by family and weight rather than all
-  measured as Helvetica.
+  with word wrapping, and text measured with the metrics of the font it is
+  drawn with: a template's own `/Widths` and `/FontDescriptor` when the
+  face carries them (as embedded subsets do), otherwise WinAnsi tables for
+  all standard-14 cuts — widths, ascender and `FontBBox`, so baselines and
+  row spacing follow the actual face. A `/BaseFont` naming no standard cut
+  (`ArialMT`, `TimesNewRomanPS-BoldMT`) is classified by family and weight
+  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.
@@ -180,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

@@ -5,66 +5,94 @@ module Acrofill
   # text-field widget, honouring the field's /DA string and /Q alignment.
   class Appearance
     PADDING = 2.0
-    ASCENT = 0.718 # Helvetica cap-height-ish ascent, em fractions
-    DESCENT = 0.207
+    # pdftk offsets the first multiline row by 1pt from the box top.
+    TOP_OFFSET = 1.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
 
     def initialize(doc, acroform)
       @doc = doc
       @acroform = acroform
+      @fonts = Fonts.new(doc, acroform)
     end
 
     # Returns a Reference to the new appearance XObject, or nil when the
     # widget geometry is unusable.
-    def build(field_node, widget, value, multiline: false)
+    def build(field_node, widget, value, multiline: false, comb: nil)
       rect = normalized_rect(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)
-      widths = Metrics.widths_for(base_font_for(font_name))
-      align = alignment(field_node)
-
-      body =
-        if multiline
-          size = 12.0 if size <= 0
-          size = size.clamp(2.0, 144.0)
-          multiline_body(value, widths, size, width, height, align)
-        else
-          text = printable_text(value)
-          size = [height * 0.66, 12.0].min if size.zero?
-          size = shrink_to_fit(text, widths, size, width)
-          # Vertically center the ascent box, matching pdftk's baseline
-          # placement exactly: ty = (h - ascent*size) / 2.
-          ty = [(height - (size * ASCENT)) / 2.0, size * DESCENT].max
-          "#{fmt(line_x(text, widths, size, width, align))} #{fmt(ty)} Td\n" \
-            "(#{escape_literal(text)}) Tj\n"
-        end
+      font = @fonts.metrics(font_name)
+      size, body = draw(value, font, size, box, multiline: multiline, comb: comb)
+
+      @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:)
+      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)]
+      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"]
+      end
+    end
+
+    # A /DA size of 0 means "fit the box"; acrofill caps that at 12pt.
+    def auto_size(size, height)
+      size.zero? ? [height * 0.66, 12.0].min : size
+    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],
-        Resources: { Font: { font_name.to_sym => font_ref(font_name) } }
+        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
+    # Where pdftk puts a single line's baseline: the ascent box centered in
+    # the field, but never so low that the descender leaves the box, never so
+    # high that the ascender does, and never below the box floor. The last
+    # two only bind when the text is taller than the field it sits in, which
+    # real forms do hit — a 12pt /DA in a 10.8pt-high field is common.
+    def baseline(height, font, size)
+      ascent = font.ascent(size)
+      highest = height - ascent # baseline putting the ascender at the box top
+      return 0.0 if highest <= 0 # the glyphs are taller than the box
 
-    def fmt(num)
-      Serializer.format_number(num.to_f)
+      [highest / 2.0, font.descent(size)].max.clamp(0.0, highest)
     end
 
     # /Q (0 left, 1 center, 2 right), inheritable and possibly indirect.
@@ -73,29 +101,49 @@ module Acrofill
       align.is_a?(Integer) ? align : 0
     end
 
-    def line_x(text, widths, size, width, align)
-      text_width = Metrics.string_width(text, widths, size)
-      case align
-      when 1 then [(width - text_width) / 2.0, PADDING].max
-      when 2 then [width - PADDING - text_width, PADDING].max
+    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
       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) - (Metrics.string_width(char, font.widths, 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, widths, size, width, height, align)
-      max_width = width - (2 * PADDING)
+    def multiline_body(value, font, size, box)
+      max_width = box.width - (2 * PADDING)
       lines = value.to_s.split(/\r\n|[\r\n]/).flat_map do |paragraph|
-        wrap_line(printable_text(paragraph), widths, size, max_width)
+        wrap_line(font.encode(printable_text(paragraph)), font, size, max_width)
       end
 
-      leading = size * 1.15
-      first_y = height - PADDING - (size * ASCENT)
+      # pdftk spaces rows by the font's FontBBox extent and drops the first
+      # baseline by that extent from the top of the box.
+      leading = font.line_height(size)
+      first_y = box.height - font.top(size) + TOP_OFFSET
       body = "#{fmt(leading)} TL\n"
       previous_x = 0.0
       lines.each_with_index do |line, index|
-        x = line_x(line, widths, size, width, align)
+        x = line_x(line, font, size, box)
         body << "#{fmt(x - previous_x)} #{index.zero? ? fmt(first_y) : '0'} Td\n"
         body << "(#{escape_literal(line)}) Tj\nT*\n"
         previous_x = x
@@ -105,12 +153,12 @@ module Acrofill
 
     # Greedy wrap. Line and space widths are accumulated incrementally so
     # the cost is O(total characters), not O(words * line-length).
-    def wrap_line(text, widths, size, max_width)
-      space = Metrics.string_width(' ', widths, size)
+    def wrap_line(text, font, size, max_width)
+      space = Metrics.string_width(' ', font.widths, size)
       lines = ['']
       so_far = [0.0]
       text.split.each do |word|
-        word_width = Metrics.string_width(word, widths, size)
+        word_width = Metrics.string_width(word, font.widths, size)
         if lines.last.empty?
           lines[-1] = word
           so_far[-1] = word_width
@@ -182,42 +230,13 @@ module Acrofill
 
     # 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, widths, size, width)
+    def shrink_to_fit(text, font, size, width)
       max_width = width - (2 * PADDING)
-      text_width = Metrics.string_width(text, widths, size)
+      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)
     end
 
-    # The font resource dictionary from /AcroForm /DR /Font, or {} when the
-    # template supplies a malformed (non-dictionary) /DR or /Font.
-    def dr_fonts
-      @dr_fonts ||=
-        begin
-          dr = @doc.deref(@acroform[:DR])
-          fonts = dr.is_a?(Hash) ? @doc.deref(dr[:Font]) : nil
-          fonts.is_a?(Hash) ? fonts : {}
-        end
-    end
-
-    def base_font_for(resource_name)
-      font = @doc.deref(dr_fonts[resource_name.to_sym])
-      base = font.is_a?(Hash) ? @doc.deref(font[:BaseFont]).to_s : ''
-      base.sub(/\A[A-Z]{6}\+/, '') # drop the subset prefix (ABCDEF+Arial)
-    end
-
-    def font_ref(resource_name)
-      entry = dr_fonts[resource_name.to_sym]
-      entry ? @doc.ref_for(entry) : fallback_font
-    end
-
-    # Font not present in /DR: register one plain Helvetica and share it
-    # across every appearance built from this form.
-    def fallback_font
-      @fallback_font ||=
-        @doc.add(Type: :Font, Subtype: :Type1, BaseFont: :Helvetica, Encoding: :WinAnsiEncoding)
-    end
-
     def printable_text(value)
       value.to_s.gsub(/[[:space:]]+/, ' ').strip
            .encode('Windows-1252', invalid: :replace, undef: :replace, replace: '?')

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
@@ -61,7 +63,12 @@ module Acrofill
     # 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)
+      # 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)

data/lib/acrofill/fonts.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Acrofill
+  # The form's /DR /Font dictionary: the metrics a widget's /DA font resource
+  # actually implies, and the reference to put in a generated appearance's
+  # /Resources.
+  #
+  # Real templates embed their own faces, and those font dictionaries carry
+  # their own /Widths and /FontDescriptor. The appearance stream is drawn
+  # with that very font, so it has to be measured with it too — laying an
+  # embedded face out against standard-14 tables misplaces every centered or
+  # right-aligned value. pdftk reads the dictionary; these are the same rules,
+  # measured against pdftk-java 3.3.3 (see benchmark/geometry_diff.rb):
+  #
+  #   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)
+  # gets pdftk's generic defaults vertically, while its widths still fall back
+  # to the closest standard table, there being nothing better to measure with.
+  class Fonts
+    DEFAULT_ASCENDER = 800
+    DEFAULT_DESCENDER = -200
+    DEFAULT_BBOX_TOP = 900
+    DEFAULT_BBOX_BOTTOM = -200
+    # A code outside /FirstChar../LastChar draws as zero-width: pdftk does
+    # 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
+      @acroform = acroform
+      @metrics = {}
+      @references = {}
+    end
+
+    # 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)))
+    end
+
+    # Indirect reference to that font, for the appearance /Resources. Fonts
+    # absent from /DR share one registered Helvetica; a /DR font stored as a
+    # direct dictionary is promoted to an indirect object once, not once per
+    # widget.
+    def reference(resource_name)
+      key = resource_name.to_sym
+      @references[key] ||=
+        begin
+          found = entry(key)
+          found ? @doc.ref_for(found) : fallback
+        end
+    end
+
+    private
+
+    def dr_fonts
+      @dr_fonts ||=
+        begin
+          dr = @doc.deref(@acroform[:DR])
+          fonts = dr.is_a?(Hash) ? @doc.deref(dr[:Font]) : nil
+          fonts.is_a?(Hash) ? fonts : {}
+        end
+    end
+
+    def entry(key)
+      dr_fonts[key]
+    end
+
+    def fallback
+      @fallback ||=
+        @doc.add(Type: :Font, Subtype: :Type1, BaseFont: :Helvetica, Encoding: :WinAnsiEncoding)
+    end
+
+    def build(dict)
+      return Metrics.font_for('') unless dict.is_a?(Hash)
+
+      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
+    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)
+      @doc.deref(dict[:BaseFont]).to_s.sub(SUBSET_PREFIX, '')
+    end
+
+    # The font's own glyph widths, laid out the way Metrics tables are
+    # (index = code - 32), or nil when the dictionary does not supply usable
+    # ones. Only the codes acrofill can emit are read, so a /Widths array of
+    # any declared length costs the same.
+    def widths(dict)
+      first = @doc.deref(dict[:FirstChar])
+      declared = @doc.deref(dict[:Widths])
+      return nil unless first.is_a?(Integer) && declared.is_a?(Array)
+
+      low = [Metrics::FIRST_CODE - first, 0].max
+      high = [Metrics::LAST_CODE - first, declared.size - 1].min
+      return nil if high < low
+
+      table = Array.new(Metrics::LAST_CODE - Metrics::FIRST_CODE + 1, OUT_OF_RANGE_WIDTH)
+      (low..high).each do |index|
+        width = number(declared[index])
+        table[first + index - Metrics::FIRST_CODE] = width if width
+      end
+      table
+    end
+
+    def vertical(dict, standard)
+      descriptor = @doc.deref(dict[:FontDescriptor])
+      descriptor = nil 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,
+        top || standard&.bbox_top || DEFAULT_BBOX_TOP,
+        bottom || standard&.bbox_bottom || DEFAULT_BBOX_BOTTOM
+      ]
+    end
+
+    # [lower y, upper y] of /FontBBox, or [nil, nil] when it is unusable.
+    def font_bbox(descriptor)
+      box = descriptor && @doc.deref(descriptor[:FontBBox])
+      return [nil, nil] unless box.is_a?(Array) && box.size == 4
+
+      [number(box[1]), number(box[3])]
+    end
+
+    # Font dictionaries are template data: every scalar may be indirect, and
+    # a non-finite one would poison the geometry it feeds.
+    def number(raw)
+      value = @doc.deref(raw)
+      return nil unless value.is_a?(Numeric)
+
+      value = value.to_f
+      value.finite? ? value : nil
+    end
+  end
+end

data/lib/acrofill/form.rb

@@ -6,6 +6,7 @@ module Acrofill
   class Form
     MULTILINE_FLAG = 1 << 12
     PUSHBUTTON_FLAG = 1 << 16
+    COMB_FLAG = 1 << 24
 
     Field = Struct.new(:name, :type, :value, :states, keyword_init: true)
 
@@ -81,15 +82,23 @@ 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)
       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 = build_appearance(node, widget, value, multiline, comb)
         # 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 +111,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

data/lib/acrofill/metrics.rb

@@ -6,18 +6,25 @@ module Acrofill
   # Windows-1252 bytes against a /WinAnsiEncoding font, so the byte emitted
   # is the byte measured). Extracted from Adobe AFM metrics.
   #
-  # Only six tables are stored: the oblique cuts of Helvetica have the same
-  # widths as the upright face, and the whole Courier family is monospaced.
-  # #widths_for maps every other BaseFont name onto them.
+  # Only six width tables are stored: the oblique cuts of Helvetica have the
+  # same widths as the upright face, and the whole Courier family is
+  # monospaced. Vertical metrics (ascender, descender, FontBBox extent) are
+  # per cut, since they differ where widths do not.
   module Metrics
     DEFAULT_WIDTH = 556
     COURIER_WIDTH = 600
     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
 
-    # Bold/italic Times cuts, indexed by bold + 2 * italic.
-    TIMES = %w[Times-Roman Times-Bold Times-Italic Times-BoldItalic].freeze
+    # The standard-14 text cuts, indexed by bold + 2 * italic per family.
+    CUTS = {
+      helvetica: %w[Helvetica Helvetica-Bold Helvetica-Oblique Helvetica-BoldOblique].freeze,
+      times: %w[Times-Roman Times-Bold Times-Italic Times-BoldItalic].freeze,
+      courier: %w[Courier Courier-Bold Courier-Oblique Courier-BoldOblique].freeze
+    }.freeze
     # Family and weight hints for BaseFont names outside the standard 14.
     SERIF = /times|roman|serif|georgia|garamond/
     SANS = /sans/
@@ -25,7 +32,7 @@ module Acrofill
     BOLD = /bold|black|heavy/
     ITALIC = /italic|oblique/
 
-    WIDTHS = {
+    TABLES = {
       'Helvetica' => [
         278, 278, 355, 556, 556, 889, 667, 191, 333, 333, 389, 584, 278, 333, 278, 278, 556,
         556, 556, 556, 556, 556, 556, 556, 556, 556, 278, 278, 584, 584, 584, 556, 1015, 667,
@@ -125,6 +132,90 @@ module Acrofill
       'Courier' => Array.new(LAST_CODE - FIRST_CODE + 1, COURIER_WIDTH).freeze
     }.freeze
 
+    # Cuts that share a width table with another cut.
+    WIDTHS = TABLES.merge(
+      'Helvetica-Oblique' => TABLES['Helvetica'],
+      'Helvetica-BoldOblique' => TABLES['Helvetica-Bold'],
+      'Courier-Bold' => TABLES['Courier'],
+      'Courier-Oblique' => TABLES['Courier'],
+      'Courier-BoldOblique' => TABLES['Courier']
+    ).freeze
+
+    # [ascender, descender, FontBBox top, FontBBox bottom] in 1/1000 em,
+    # from the same Adobe AFM data as the widths. pdftk places baselines
+    # from the ascender and spaces multiline rows by the FontBBox extent,
+    # so these drive vertical geometry.
+    VERTICAL = {
+      'Helvetica' => [718, -207, 931, -225].freeze,
+      'Helvetica-Bold' => [718, -207, 962, -228].freeze,
+      'Helvetica-Oblique' => [718, -207, 931, -225].freeze,
+      'Helvetica-BoldOblique' => [718, -207, 962, -228].freeze,
+      'Times-Roman' => [683, -217, 898, -218].freeze,
+      'Times-Bold' => [683, -217, 935, -218].freeze,
+      'Times-Italic' => [683, -217, 883, -217].freeze,
+      'Times-BoldItalic' => [683, -217, 921, -218].freeze,
+      'Courier' => [629, -157, 805, -250].freeze,
+      'Courier-Bold' => [629, -157, 801, -250].freeze,
+      'Courier-Oblique' => [629, -157, 805, -250].freeze,
+      'Courier-BoldOblique' => [629, -157, 801, -250].freeze
+    }.freeze
+
+    # 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) 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
+
+      def ascent(size) = ascender * size / 1000.0
+
+      def descent(size) = -descender * size / 1000.0
+
+      # Distance from the box top to the first baseline, and between rows.
+      def top(size) = bbox_top * size / 1000.0
+
+      def line_height(size) = (bbox_top - bbox_bottom) * size / 1000.0
+    end
+
+    FONTS = VERTICAL.to_h do |name, (asc, desc, top, bottom)|
+      [name, Font.new(WIDTHS[name], asc, desc, top, bottom).freeze]
+    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).
     def self.string_width(str, widths, size)
@@ -136,19 +227,36 @@ module Acrofill
       units * size / 1000.0
     end
 
-    # The width table for a BaseFont name. Standard-14 names hit the table
-    # directly; anything else (ArialMT, TimesNewRomanPS-BoldMT, a template's
-    # embedded face) is classified by family and weight, which is far closer
-    # than measuring everything as Helvetica.
+    # 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
+    # treating everything as Helvetica.
+    def self.font_for(base_font)
+      FONTS.fetch(canonical_name(base_font))
+    end
+
     def self.widths_for(base_font)
+      font_for(base_font).widths
+    end
+
+    # Metrics for a name that *is* one of the standard 14, or nil. Unlike
+    # #font_for this does not classify: a template's own face only inherits
+    # standard-14 vertical metrics when it actually names one.
+    def self.standard_font(base_font)
+      FONTS[base_font.to_s]
+    end
+
+    # Maps any BaseFont name onto one of the twelve standard-14 text cuts.
+    def self.canonical_name(base_font)
       name = base_font.to_s
-      return WIDTHS[name] if WIDTHS.key?(name)
+      return name if FONTS.key?(name)
 
       lower = name.downcase
-      return WIDTHS['Courier'] if FIXED.match?(lower)
-      return WIDTHS[TIMES[weight_index(lower)]] if serif?(lower)
-
-      WIDTHS[BOLD.match?(lower) ? 'Helvetica-Bold' : 'Helvetica']
+      family = if FIXED.match?(lower) then :courier
+               elsif serif?(lower) then :times
+               else :helvetica
+               end
+      CUTS[family][weight_index(lower)]
     end
 
     def self.serif?(lower)
@@ -159,10 +267,11 @@ 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

data/lib/acrofill/version.rb

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

data/lib/acrofill.rb

@@ -5,6 +5,7 @@ require_relative 'acrofill/document'
 require_relative 'acrofill/metrics'
 require_relative 'acrofill/serializer'
 require_relative 'acrofill/writer'
+require_relative 'acrofill/fonts'
 require_relative 'acrofill/appearance'
 require_relative 'acrofill/flattener'
 require_relative 'acrofill/form'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acrofill
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - stiig
@@ -38,6 +38,7 @@ files:
 - lib/acrofill/document.rb
 - lib/acrofill/filler.rb
 - lib/acrofill/flattener.rb
+- lib/acrofill/fonts.rb
 - lib/acrofill/form.rb
 - lib/acrofill/metrics.rb
 - lib/acrofill/serializer.rb