stationery 0.8.0 → 0.9.0

data/lib/stationery/forms/acro_form.rb

@@ -3,14 +3,24 @@
 module Stationery
   module Forms
     # Collects the widgets pages place and writes the document's interactive
-    # form: one field per name, parent fields for dotted names, the shared
-    # Helvetica and ZapfDingbats resources and the catalog's /AcroForm.
+    # form: one field per name, parent fields for dotted names, the fonts the
+    # appearances draw with as default resources and the catalog's /AcroForm.
+    #
+    # The appearances themselves need no standard font: text is set in the
+    # document's embedded fonts and marks are paths. Only a form that asks
+    # viewers to regenerate appearances lists ZapfDingbats, which is what
+    # they redraw a check box or radio button's /MK caption with.
+    #
+    # A `signature:` (a PDF::Signature) becomes the value of the signature
+    # field it names, or of a field of its own whose widget nobody sees.
     class AcroForm
-      FONTS = { Helv: :Helvetica, ZaDb: :ZapfDingbats }.freeze
+      SYMBOLS = { ZaDb: { Type: :Font, Subtype: :Type1, BaseFont: :ZapfDingbats }.freeze }.freeze
+      # SignaturesExist and AppendOnly: what a signed form tells viewers.
+      SIGNED = 3
 
-      # A widget placed on a page: its field, PDF-space rect, page and the
-      # reference the page's /Annots already points at.
-      Widget = Data.define(:field, :rect, :page, :ref, :extra)
+      # A widget placed on a page: its field, appearance, PDF-space rect, page
+      # and the reference the page's /Annots already points at.
+      Widget = Data.define(:field, :appearance, :rect, :page, :ref, :extra)
 
       # A name segment: widgets when it is a field, children when a group.
       Node = Struct.new(:name, :widgets, :children)
@@ -24,35 +34,89 @@ module Stationery
         end
       end
 
-      def initialize(writer)
+      # `fonts` are the document's embedded fonts by resource name.
+      # `need_appearances: false` leaves out the flag asking viewers to
+      # regenerate every appearance (PDF/A and PDF/UA forbid it, and a
+      # signed file must not be redrawn).
+      def initialize(writer, fonts: {}, need_appearances: true, signature: nil)
         @writer = writer
+        @embedded = fonts
+        @need_appearances = need_appearances
+        @signature = signature
         @widgets = []
       end
 
-      # Reserves the widget annotation for `field` at `rect` on `page`.
-      # `extra` entries for the widget dictionary may be computed from its
-      # reference (a tagged PDF's /StructParent).
-      def add(field, rect, page)
+      # Reserves the widget annotation (a page annotation holding the field
+      # as :widget, its :appearance and :rect) on `page`. `extra` entries for
+      # the widget dictionary may be computed from its reference (a tagged
+      # PDF's /StructParent).
+      def add(annotation, page)
         ref = @writer.reserve
-        @widgets << Widget.new(field, rect, page, ref, block_given? ? yield(ref) : {})
+        appearance = annotation[:appearance] || Appearance.new(annotation[:widget], *size_of(annotation[:rect]))
+        @widgets << Widget.new(annotation[:widget], appearance, annotation[:rect], page, ref,
+                               block_given? ? yield(ref) : {})
+        ref
+      end
+
+      # Reserves the widget of a signature that fills no field: without a
+      # size or an appearance, printable and locked, on `page`. `taken` are
+      # the names the document's fields use.
+      def sign(page, taken: [])
+        name = (1..).lazy.map { |number| "Signature#{number}" }.find { |candidate| !taken.include?(candidate) }
+        ref = @writer.reserve
+        @widgets << Widget.new(Field.new(:signature, name, label: ""), nil, [0, 0, 0, 0], page, ref, {})
         ref
       end
 
       # Writes every field; returns the /AcroForm dictionary, or nil without
-      # fields.
+      # fields. /DR lists the fonts the appearances use, /DA selects the first.
       def write
+        @signed = signed
         return if @widgets.empty?
 
-        @fonts = FONTS.transform_values { |base| @writer.add(font(base)) }
+        @fonts = fonts
         fields = tree.children.values.map { |node| write_node(node, nil) }
-        { Fields: fields, NeedAppearances: true, DA: "/#{Field::FONT} 0 Tf 0 g", DR: { Font: @fonts } }
+        form = { Fields: fields }
+        form[:SigFlags] = SIGNED if @signed
+        form[:NeedAppearances] = true if @need_appearances
+        form[:DA] = "/#{@fonts.keys.first} 0 Tf 0 g" if @fonts.any?
+        resources = @fonts.merge(symbols)
+        form[:DR] = { Font: resources } if resources.any?
+        form
       end
 
       private
 
-      def font(base)
-        font = { Type: :Font, Subtype: :Type1, BaseFont: base }
-        base == :Helvetica ? font.merge(Encoding: :WinAnsiEncoding) : font
+      def size_of(rect) = [rect[2] - rect[0], rect[3] - rect[1]]
+
+      # The signature dictionary's reference, once the field it fills is
+      # known to exist; nil without a signature.
+      def signed
+        return unless @signature
+        return @writer.add(@signature.dictionary) if @widgets.any? { |widget| signs?(widget) }
+
+        raise ArgumentError, %(sign field: names "#{@signature.field}", but the document has no such signature_field)
+      end
+
+      def signs?(widget)
+        return widget.appearance.nil? if @signature.invisible?
+
+        widget.field.kind == :signature && widget.field.name == @signature.field
+      end
+
+      def symbols
+        return {} unless @need_appearances && @widgets.any? { |widget| widget.field.type == :Btn }
+
+        SYMBOLS.transform_values { |font| @writer.add(font) }
+      end
+
+      # The fonts the appearances name: the embedded ones, and the standard
+      # Helvetica when a field without a font book draws with it.
+      def fonts
+        names = @widgets.flat_map { |widget| widget.appearance&.font_names.to_a }.uniq
+        names.to_h do |name|
+          [name, @embedded.fetch(name) { @writer.add(Standard::FONT) }]
+        end
       end
 
       def tree
@@ -91,21 +155,27 @@ module Stationery
       # field's kids. A radio group's value is its checked choice.
       def write_field(widgets, own)
         field = widgets.first.field
+        default_appearance = widgets.first.appearance&.default_appearance
+        value = @signed && signs?(widgets.first) ? { V: @signed } : {}
         unless field.radio? || !widgets.one?
-          return @writer.set(widgets.first.ref, own.merge(field.field_entries, widget(widgets.first)))
+          entries = field.field_entries(default_appearance:)
+          return @writer.set(widgets.first.ref, own.merge(entries, value, widget(widgets.first)))
         end
 
         ref = @writer.reserve
-        value = field.radio? ? widgets.map(&:field).find(&:checked?)&.on_state || :Off : nil
-        widgets.each { |kid| @writer.set(kid.ref, widget(kid, value).merge(Parent: ref)) }
-        entries = value ? field.field_entries(value) : field.field_entries
-        @writer.set(ref, own.merge(entries, Kids: widgets.map(&:ref)))
+        choice = field.radio? ? widgets.map(&:field).find(&:checked?)&.on_state || :Off : nil
+        widgets.each { |kid| @writer.set(kid.ref, widget(kid, choice).merge(Parent: ref)) }
+        entries = choice ? field.field_entries(choice, default_appearance:) : field.field_entries(default_appearance:)
+        @writer.set(ref, own.merge(entries, value, Kids: widgets.map(&:ref)))
       end
 
       def widget(widget, group_value = nil)
-        x1, y1, x2, y2 = widget.rect
+        unless widget.appearance
+          return { Type: :Annot, Subtype: :Widget, F: PDF::Signature::INVISIBLE, Rect: widget.rect, P: widget.page }
+        end
+
         state = group_value && (widget.field.on_state == group_value ? group_value : :Off)
-        entries = widget.field.widget_entries(x2 - x1, y2 - y1, @fonts, state:)
+        entries = widget.field.widget_entries(widget.appearance, @fonts, state:)
         normal = entries.dig(:AP, :N)
         normal = normal.is_a?(Hash) ? normal.transform_values { |stream| @writer.add(stream) } : @writer.add(normal)
         entries.merge(AP: { N: normal }, Rect: widget.rect, P: widget.page, **widget.extra)

data/lib/stationery/forms/appearance.rb

@@ -6,28 +6,49 @@ module Stationery
     # a form looks right without relying on the viewer to regenerate it.
     # Variable text sits between `/Tx BMC … EMC`, the part a viewer redraws
     # when the value changes.
+    #
+    # It is drawn when the widget is placed, so the glyphs it uses are in the
+    # fonts before they are subset, and written as streams once the fonts
+    # have their references (#streams).
     class Appearance
       PADDING = 2
       LEADING = 1.15
-      CHECK = { glyph: "4", width: 0.846, middle: 0.345 }.freeze
+      # The check mark's corners in the unit square (y down) and its stroke.
+      CHECK = { points: [[0.22, 0.52], [0.42, 0.72], [0.78, 0.28]], stroke: 0.12 }.freeze
       DOT = 0.45
       SIGNATURE = { rule: 14, label_size: 7, label_baseline: 4, label_gray: 0.42 }.freeze
 
-      def initialize(field, width, height, fonts)
+      # `resources` are the render's, where the field's fonts get their names.
+      def initialize(field, width, height, resources = nil)
         @field = field
         @width = width
         @height = height
-        @fonts = fonts
+        @type = field.typeface.with(resources)
+        @contents = contents
+        keep
+      end
+
+      # Whether everything it draws with is embedded in the file.
+      def embedded? = @type.names.empty? || @type.embedded?
+
+      # The resource names of the fonts it draws with or keeps for editing.
+      def font_names = @type.names
+
+      # What the field's /DA says: the font and size a viewer redraws the
+      # value with. nil for a field without variable text.
+      def default_appearance
+        return unless @field.variable_text?
+
+        "/#{@type.name} #{num(@field.font_size)} Tf 0 g"
       end
 
       # One stream, or a Hash of streams by appearance state for buttons.
-      def normal
-        case @field.kind
-        when :text, :select then stream(frame + variable_text(text_lines))
-        when :checkbox then { @field.on_state => stream(frame + check), Off: stream(frame) }
-        when :radio then { @field.on_state => stream(circle + dot), Off: stream(circle) }
-        when :signature then stream(signature)
-        end
+      # `fonts` are the references by resource name.
+      def streams(fonts)
+        resources = font_names.empty? ? {} : { Font: fonts.slice(*font_names) }
+        return stream(@contents, resources) unless @contents.is_a?(Hash)
+
+        @contents.transform_values { |content| stream(content, resources) }
       end
 
       private
@@ -36,9 +57,29 @@ module Stationery
       def size = @field.font_size
       def num(value) = PDF::Serializer.number(value.is_a?(Float) && value == value.round ? value.round : value)
 
-      def stream(content)
+      def contents
+        case @field.kind
+        when :text, :select then frame + variable_text(text_lines)
+        when :checkbox then { @field.on_state => frame + check, Off: frame }
+        when :radio then { @field.on_state => circle + dot, Off: circle }
+        when :signature then signature
+        end
+      end
+
+      # What a viewer may draw after an edit: the other options of a select,
+      # and the base repertoire of a field that can be typed into.
+      def keep
+        return unless @field.variable_text?
+
+        @type.name
+        return if options[:read_only]
+
+        @type.keep(Array(options[:options]).join, size, repertoire: true)
+      end
+
+      def stream(content, resources)
         PDF::Stream.new(content, { Type: :XObject, Subtype: :Form, BBox: [0, 0, @width, @height],
-                                   Resources: { Font: @fonts } })
+                                   Resources: resources })
       end
 
       def frame
@@ -50,34 +91,49 @@ module Stationery
         end
       end
 
-      # [x, baseline, WinAnsi bytes] runs in PDF space.
+      def middle_baseline = (@height / 2.0) - ((@type.ascent(size) - @type.descent(size)) / 2)
+
+      # [x, baseline, text] runs in PDF space.
       def text_lines
         return comb_cells if options[:comb]
         return multiline_runs if options[:multiline]
 
-        [[PADDING, (@height / 2.0) - (size * (Metrics::ASCENT + Metrics::DESCENT) / 2), Metrics.encode(@field.value)]]
+        [[PADDING, middle_baseline, @field.value.to_s]]
       end
 
       def multiline_runs
-        top = @height - PADDING - (size * Metrics::ASCENT)
-        Metrics.wrap(@field.value, @width - (2 * PADDING), size).each_with_index.map do |line, index|
+        top = @height - PADDING - @type.ascent(size)
+        wrap(@field.value.to_s, @width - (2 * PADDING)).each_with_index.map do |line, index|
           [PADDING, top - (index * size * LEADING), line]
         end
       end
 
+      # The value broken into lines no wider than `width`, keeping its own
+      # line breaks; a word wider than a line stands alone.
+      def wrap(text, width)
+        text.split("\n", -1).flat_map do |paragraph|
+          paragraph.split.each_with_object([+""]) do |word, lines|
+            candidate = lines.last.empty? ? word : "#{lines.last} #{word}"
+            if lines.last.empty? || @type.width(candidate, size) <= width
+              lines[-1] = candidate
+            else
+              lines << word
+            end
+          end
+        end
+      end
+
       def comb_cells
         cell = @width.fdiv(@field.max_length)
-        baseline = (@height / 2.0) - (size * (Metrics::ASCENT + Metrics::DESCENT) / 2)
-        Metrics.encode(@field.value)[0, @field.max_length].chars.each_with_index.map do |char, index|
-          [(index * cell) + ((cell - Metrics.width(char, size)) / 2), baseline, char]
+        @field.value.to_s[0, @field.max_length].chars.each_with_index.map do |char, index|
+          [(index * cell) + ((cell - @type.width(char, size)) / 2), middle_baseline, char]
         end
       end
 
       def variable_text(runs)
         ops = ["/Tx BMC", "q", "1 1 #{num(@width - 2)} #{num(@height - 2)} re W n", "0 g"]
-        runs.reject { |_, _, bytes| bytes.empty? }.each do |x, y, bytes|
-          ops.push("BT", "/#{Field::FONT} #{num(size)} Tf", "#{num(x)} #{num(y)} Td",
-                   "#{PDF::Serializer.literal(bytes)} Tj", "ET")
+        runs.reject { |_, _, text| text.empty? }.each do |x, y, text|
+          ops.push("BT", "#{num(x)} #{num(y)} Td", *@type.show(text, size), "ET")
         end
         ops.push("Q", "EMC").join("\n") << "\n"
       end
@@ -93,11 +149,11 @@ module Stationery
       def signature
         y = @height - SIGNATURE[:rule]
         content = draw { |canvas| canvas.line(PADDING, y, @width - PADDING, y, color: options[:border], width: 0.75) }
-        label = Metrics.encode(options[:label])
+        label = options[:label].to_s
         return content if label.empty?
 
-        ops = ["q", "#{SIGNATURE[:label_gray]} g", "BT", "/#{Field::FONT} #{SIGNATURE[:label_size]} Tf",
-               "#{PADDING} #{SIGNATURE[:label_baseline]} Td", "#{PDF::Serializer.literal(label)} Tj", "ET", "Q"]
+        ops = ["q", "#{SIGNATURE[:label_gray]} g", "BT", "#{PADDING} #{SIGNATURE[:label_baseline]} Td",
+               *@type.show(label, SIGNATURE[:label_size]), "ET", "Q"]
         "#{content}#{ops.join("\n")}\n"
       end
 
@@ -107,12 +163,18 @@ module Stationery
         page.content
       end
 
+      # A check mark stroked as a path, so no symbol font is needed.
       def check
-        glyph = [@width, @height].min * 0.8
-        x = (@width - (glyph * CHECK[:width])) / 2
-        y = (@height / 2.0) - (glyph * CHECK[:middle])
-        ["q", "0 g", "BT", "/ZaDb #{num(glyph)} Tf", "#{num(x)} #{num(y)} Td", "(#{CHECK[:glyph]}) Tj", "ET", "Q"]
-          .join("\n") << "\n"
+        side = [@width, @height].min * 0.8
+        left = (@width - side) / 2.0
+        top = (@height - side) / 2.0
+        first, *rest = CHECK[:points].map { |x, y| [left + (x * side), top + (y * side)] }
+        draw do |canvas|
+          canvas.path(stroke: "#000000", line_width: side * CHECK[:stroke], cap: :round, join: :round) do |path|
+            path.move_to(*first)
+            rest.each { |point| path.line_to(*point) }
+          end
+        end
       end
     end
   end

data/lib/stationery/forms/field.rb

@@ -6,26 +6,29 @@ module Stationery
   module Forms
     # One form field widget: its kind, full (dotted) name, value and options.
     # Widgets sharing a name form one field (a radio group); dotted names are
-    # grouped under parent fields.
+    # grouped under parent fields. `typeface:` is what its appearance is set
+    # in: the document's fonts from the element DSL, the standard Helvetica
+    # otherwise. `tooltip:` is its accessible name (/TU), the name by default.
     class Field
       TYPES = { text: :Tx, checkbox: :Btn, radio: :Btn, select: :Ch, signature: :Sig }.freeze
       # Field flag bit positions (PDF 32000-1, 12.7.3.1 and 12.7.4).
       BITS = { read_only: 1, required: 2, multiline: 13, no_toggle_to_off: 15, radio: 16, combo: 18, edit: 19,
                comb: 25 }.freeze
       DEFAULTS = { font_size: 10, read_only: false, required: false, border: "#9CA3AF", background: "#FFFFFF",
-                   radius: 2 }.freeze
+                   radius: 2, tooltip: nil }.freeze
       OPTIONS = {
         text: %i[multiline max_length comb], checkbox: [], radio: %i[checked], select: %i[options editable],
         signature: %i[label]
       }.freeze
-      FONT = "Helv"
+      VARIABLE_TEXT = %i[text select].freeze
 
-      attr_reader :kind, :name, :value, :options
+      attr_reader :kind, :name, :value, :options, :typeface
 
-      def initialize(kind, name, value: nil, **options)
+      def initialize(kind, name, value: nil, typeface: Standard.new, **options)
         @kind = kind
         @name = validate_name(name.to_s)
         @value = value
+        @typeface = typeface
         unknown = options.keys - DEFAULTS.keys - OPTIONS.fetch(kind)
         raise ArgumentError, "unknown #{kind} field option: #{unknown.join(", ")}" if unknown.any?
 
@@ -36,7 +39,10 @@ module Stationery
       def segments = @name.split(".")
       def type = TYPES.fetch(@kind)
       def font_size = @options[:font_size]
-      def default_appearance = "/#{FONT} #{PDF::Serializer.number(font_size)} Tf 0 g"
+      # Whether a viewer redraws its text when the value changes.
+      def variable_text? = VARIABLE_TEXT.include?(@kind)
+      # The accessible name: `tooltip:`, a signature's label, else the name.
+      def tooltip = (@options[:tooltip] || @options[:label]).to_s.strip.then { |text| text.empty? ? @name : text }
       def max_length = @options[:comb].is_a?(Integer) ? @options[:comb] : @options[:max_length]
       def radio? = @kind == :radio
       def checked? = radio? ? @options[:checked] == true : @value == true
@@ -52,8 +58,10 @@ module Stationery
 
       # The field-level entries; the widget's come from #widget_entries.
       # `value` overrides this widget's own: a radio group's checked choice.
-      def field_entries(value = field_value)
-        entries = { FT: type, DA: default_appearance }
+      # `default_appearance` is the /DA of a field with variable text.
+      def field_entries(value = field_value, default_appearance: nil)
+        entries = { FT: type, TU: PDF::TextString.new(tooltip) }
+        entries[:DA] = default_appearance if default_appearance
         entries[:Ff] = flags if flags.positive?
         entries[:V] = value unless value.nil?
         entries[:MaxLen] = max_length if max_length
@@ -70,9 +78,10 @@ module Stationery
         end
       end
 
-      # `state` overrides the button's own appearance state.
-      def widget_entries(width, height, fonts, state: nil)
-        normal = Appearance.new(self, width, height, fonts).normal
+      # `appearance` is the widget's Appearance and `fonts` the references by
+      # resource name; `state` overrides the button's own appearance state.
+      def widget_entries(appearance, fonts, state: nil)
+        normal = appearance.streams(fonts)
         entries = { Type: :Annot, Subtype: :Widget, F: 4, AP: { N: normal } }
         entries[:MK] = appearance_characteristics unless @kind == :signature
         entries[:AS] = state || (checked? ? on_state : :Off) if normal.is_a?(Hash)

data/lib/stationery/forms/metrics.rb

@@ -3,8 +3,9 @@
 module Stationery
   module Forms
     # Helvetica's advance widths (the standard-14 AFM, in 1/1000 em) for the
-    # printable ASCII range, enough to lay out a field's appearance; other
-    # WinAnsi characters count as a digit's width.
+    # printable ASCII range, enough to lay out the appearance of a field made
+    # without a font book (see Standard); other WinAnsi characters count as a
+    # digit's width.
     module Metrics
       ASCII = [
         278, 278, 355, 556, 556, 889, 667, 191, 333, 333, 389, 584, 278, 333, 278, 278, # space - /
@@ -29,21 +30,6 @@ module Stationery
       def width(bytes, size)
         bytes.each_byte.sum { |byte| (byte in 32..126) ? ASCII[byte - 32] : DEFAULT } * size / 1000.0
       end
-
-      # `text` broken into WinAnsi lines no wider than `width`, keeping its own
-      # line breaks; a word wider than a line stands alone.
-      def wrap(text, width, size)
-        encode(text).split("\n", -1).flat_map do |paragraph|
-          paragraph.split.each_with_object([+""]) do |word, lines|
-            candidate = lines.last.empty? ? word : "#{lines.last} #{word}"
-            if lines.last.empty? || width(candidate, size) <= width
-              lines[-1] = candidate
-            else
-              lines << word
-            end
-          end
-        end
-      end
     end
   end
 end

data/lib/stationery/forms/typeface.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Forms
+    # What a field's appearance is set in. A field built by the element DSL
+    # draws with the document's own fonts (Typeface): embedded, subset and
+    # Identity-H encoded like any other text, with the book's fallbacks per
+    # character, so a value in any script the fonts cover renders. A field
+    # made without a font book (`Forms::Field.new` on a bare canvas) draws
+    # with the standard Helvetica in Windows-1252 (Standard).
+    #
+    # Both answer the same questions for an Appearance once bound to a
+    # render's resources with #with.
+    class Typeface
+      # What an editable field's font keeps beyond the value it shows, so the
+      # text a viewer redraws after an edit has its glyphs: printable ASCII
+      # and Latin-1. A read-only field keeps its value's glyphs only.
+      REPERTOIRE = [*0x20..0x7E, *0xA0..0xFF].pack("U*").freeze
+
+      def initialize(book, style, resources = nil)
+        @book = book
+        @style = style
+        @resources = resources
+        @names = {}
+      end
+
+      # This typeface naming its fonts in `resources` (a render's Resources).
+      def with(resources) = self.class.new(@book, @style, resources)
+
+      def embedded? = true
+      def ascent(size) = primary.ascender(size)
+      def descent(size) = primary.descender(size)
+      def width(text, size) = runs(text, size).sum { |font, run| font.width_of(run.text, size, ligatures: false) }
+
+      # The resource names of the fonts drawn or kept so far.
+      def names = @names.values
+
+      # The name the field's /DA selects: the font of the surrounding text.
+      def name = name_of(primary)
+
+      # The operators showing `text` at the current text position: a font
+      # selection and a string per run of one font. Characters no font has
+      # draw as .notdef and are reported, as in any other text.
+      def show(text, size)
+        runs(text, size).flat_map do |font, run|
+          report(font, run)
+          ["/#{name_of(font)} #{PDF::Serializer.number(size)} Tf", glyphs(font, run.text).to_operator]
+        end
+      end
+
+      # Keeps the glyphs of `text` in the embedded fonts without drawing it
+      # (a select's other options), and the REPERTOIRE when `repertoire:`.
+      def keep(text, size, repertoire: false)
+        runs(text, size).each do |font, run|
+          name_of(font)
+          glyphs(font, run.text)
+        end
+        return unless repertoire
+
+        name
+        glyphs(primary, REPERTOIRE.each_char.select { |char| primary.glyph?(char) }.join)
+      end
+
+      private
+
+      def primary = @primary ||= @book.resolve(@style).first
+      def name_of(font) = @names[font] ||= @resources.font(font)
+
+      # Marks the glyphs as used, so the subset embeds them.
+      def glyphs(font, text) = font.glyph_run(text, ligatures: false)
+
+      # [font, run] per stretch of `text` one font draws.
+      def runs(text, size)
+        return [] if text.empty?
+
+        @book.fallback([Text::Run.new(text, @style.with(size:))]).map { |run| [@book.resolve(run.style).first, run] }
+      end
+
+      def report(font, run)
+        run.text.each_char do |char|
+          next if Fonts::Fallback.carried?(char) || font.glyph?(char)
+
+          @book.warnings.missing_glyph(char, run.style.family)
+        end
+      end
+    end
+
+    # The standard Helvetica, not embedded: text is Windows-1252 bytes and
+    # characters outside it become "?".
+    class Standard
+      NAME = :Helv
+      FONT = { Type: :Font, Subtype: :Type1, BaseFont: :Helvetica, Encoding: :WinAnsiEncoding }.freeze
+
+      def with(_resources) = self.class.new
+      def embedded? = false
+      def ascent(size) = size * Metrics::ASCENT
+      def descent(size) = size * -Metrics::DESCENT
+      def width(text, size) = Metrics.width(Metrics.encode(text), size)
+      def names = @named ? [NAME] : []
+      # Nothing to keep: a standard font is the viewer's, whole.
+      def keep(*, **) = nil
+
+      def name
+        @named = true
+        NAME
+      end
+
+      def show(text, size)
+        ["/#{name} #{PDF::Serializer.number(size)} Tf", "#{PDF::Serializer.literal(Metrics.encode(text))} Tj"]
+      end
+    end
+  end
+end

data/lib/stationery/html/document.rb

@@ -1,14 +1,20 @@
 # frozen_string_literal: true
 
+require_relative "../rich/nesting"
 require_relative "tokenizer"
 require_relative "tree_builder"
 
 module Stationery
   # Lenient HTML to rich-text blocks (see Stationery::Rich).
   module HTML
-    def self.parse(source)
+    # Elements nested deeper than `max_depth` are flattened into the deepest
+    # one kept; the block is then given how deep the source went.
+    def self.parse(source, max_depth: Rich::Nesting::DEFAULT)
+      nesting = Rich::Nesting.new(max_depth)
       Stationery.instrument("parse.stationery", format: :html, bytes: source.bytesize) do
-        TreeBuilder.parse(Tokenizer.tokenize(source))
+        TreeBuilder.parse(Tokenizer.tokenize(source), nesting).tap do
+          yield nesting.deepest if nesting.exceeded? && block_given?
+        end
       end
     end
   end