stationery 0.10.0 → 0.11.0

data/lib/stationery/document.rb

@@ -24,7 +24,8 @@ module Stationery
                       superclass.config.transform_values(&:dup)
                     else
                       { page: { size: :letter, margin: 36 }, families: {}, fallbacks: [], text: {}, metadata: {},
-                        templates: [], regions: [], strict: false, tagged: false, images: {}, attachments: [] }
+                        templates: [], regions: [], strict: false, tagged: false, incremental: false, images: {},
+                        attachments: [], shaping: {} }
                     end
       end
 
@@ -42,6 +43,14 @@ module Stationery
         config[:fallbacks] = names.map(&:to_s)
       end
 
+      # Hands every text to `shaper` to place its glyphs: the hook for
+      # complex scripts (Arabic, Indic, Thai, …) and right-to-left text, which
+      # stationery does not shape itself. Anything answering `call(text, font,
+      # **options)`; see Shaper. `shaper nil` takes an inherited one away.
+      def shaper(shaper)
+        config[:shaping] = { shaper: Shaper.check(shaper) }
+      end
+
       def default_text(**options)
         config[:text] = config[:text].merge(options)
       end
@@ -68,7 +77,7 @@ module Stationery
 
       # Bitmap defaults: `max_ppi:` (300; nil disables) is the resolution
       # above twice of which a drawn image is reported as oversized, and
-      # `downscale: true` resamples PNGs to it. See Layout::Image.
+      # `downscale: true` resamples PNGs and WebPs to it. See Layout::Image.
       def images(**options)
         config[:images] = config[:images].merge(options)
       end
@@ -78,6 +87,13 @@ module Stationery
         config[:strict] = value
       end
 
+      # Writes each page as soon as it is painted and lets go of it, so a long
+      # document peaks far lower: see #to_pdf for what the file looks like and
+      # which renders take the usual path all the same.
+      def incremental(value = true) # rubocop:disable Style/OptionalBooleanParameter
+        config[:incremental] = value
+      end
+
       # Writes a tagged (accessible) PDF: a structure tree of headings,
       # paragraphs and figures, and headers and footers marked as artifacts.
       # Set `metadata lang:` and give images `alt:` text.
@@ -158,11 +174,20 @@ module Stationery
     # path or an IO. With a block the file is streamed to it in pieces as it
     # is written and the call answers the number of bytes: the first bytes
     # leave before the last page is assembled and no output buffer is built.
-    # Layout runs in full first either way, so peak memory does not drop.
+    #
+    # `incremental: true` writes each page's body as soon as the page is
+    # painted and lets go of its operators, to a block before the next page is
+    # painted. The file is the same document with its objects in another
+    # order, and what is painted once every page is known (headers, footers,
+    # page templates, contents page numbers) is a content stream of its own.
+    # A render that must be checked before anything is written takes the
+    # usual path instead: one with `conformance:` or `sign:`, and a `strict`
+    # one that goes to a block.
     def to_pdf(target = nil, strict: self.class.config[:strict], debug: false, encrypt: self.class.config[:encrypt],
                tagged: self.class.config[:tagged], page_labels: self.class.config[:page_labels], attachments: [],
                xmp: metadata[:xmp] != false, conformance: self.class.config[:conformance],
-               factur_x: self.class.config[:factur_x], sign: self.class.config[:sign], &block)
+               factur_x: self.class.config[:factur_x], sign: self.class.config[:sign],
+               shaper: self.class.config[:shaping][:shaper], incremental: self.class.config[:incremental], &block)
       invoice = PDF::FacturX.for(factur_x, self)
       attachments = PDF::Attachments.merge(self.class.config[:attachments], attachments, invoice&.attachment)
       conformance = PDF::Conformance.for(invoice ? invoice.conformance(conformance) : conformance)
@@ -173,7 +198,8 @@ module Stationery
       raise ArgumentError, "pass a target or a block, not both" if target && block
 
       options = { strict:, debug:, encrypt:, tagged: tagged || conformance&.pdf_ua?, page_labels:, attachments:,
-                  xmp: xmp || !conformance.nil?, conformance:, invoice:, signature:, sink: block }
+                  xmp: xmp || !conformance.nil?, conformance:, invoice:, signature:, sink: block, shaper:,
+                  incremental: incremental && !conformance && !signature && !(strict && block) }
       Stationery.instrument("render.stationery", document: self.class.name) do |event|
         block ? render_pdf(event, **options) : write(render_pdf(event, **options), target)
       end
@@ -200,14 +226,16 @@ module Stationery
     def builder_for(book) = Builder.new(book:, text: self.class.config[:text], images: self.class.config[:images])
 
     # The PDF bytes; `event` is the render.stationery payload it fills in.
-    def render_pdf(event, strict:, debug:, tagged:, conformance:, **assembly)
+    def render_pdf(event, strict:, debug:, tagged:, conformance:, shaper:, incremental:, **assembly)
       tagging = Tagging::Tree.new if tagged
       warnings = Warnings.new
-      book = Fonts::FontBook.new(self.class.config[:families], fallbacks: self.class.config[:fallbacks], warnings:)
+      book = Fonts::FontBook.new(self.class.config[:families], fallbacks: self.class.config[:fallbacks], warnings:,
+                                                               shaper:, language: metadata[:lang])
       builder = builder_for(book)
       Stationery.instrument("build.stationery", document: self.class.name) { call(builder) }
       resources = Resources.new
-      pages = paginate(builder.root, book:, resources:, warnings:, debug:, tagging:)
+      sealer = sealer_for(incremental, conformance, **assembly)
+      pages = paginate(builder, sealer, book:, resources:, warnings:, debug:, tagging:)
       outline = builder.outline.resolve(Structure.resolve(pages, warnings:, resources:, book:, tagging:))
       tagging&.audit(pages, warnings, lang: metadata[:lang])
       @warnings = warnings
@@ -217,15 +245,15 @@ module Stationery
       event[:warnings] = warnings.size
       raise WarningsError, warnings if strict && warnings.any?
 
-      pdf = assemble(pages, resources, outline, tagging:, conformance:, **assembly)
+      pdf = assemble(pages, resources, outline, tagging:, conformance:, writer: sealer.writer, **assembly)
       event[:bytes] = byte_count(pdf)
       pdf
     end
 
     def assemble(pages, resources, outline, encrypt:, tagging:, page_labels:, attachments:, xmp:, conformance:,
-                 invoice:, signature:, sink:)
-      encryption = encrypt && PDF::Encryption::StandardSecurity.new(**encrypt)
-      assembler = PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:, tagging:, xmp:,
+                 invoice:, signature:, sink:, writer:)
+      assembler = PDF::Assembler.new(pages:, resources:, info:, outline:, tagging:, xmp:, writer:,
+                                     encryption: writer ? nil : encryption(encrypt),
                                      lang: metadata[:lang], page_labels: PDF::PageLabels.entries(page_labels),
                                      attachments:, conformance:, xmp_extensions: invoice&.xmp_extensions || {},
                                      xmp_schemas: [invoice&.xmp_schema].compact, signature:, sink:)
@@ -235,12 +263,26 @@ module Stationery
     end
 
     def byte_count(pdf) = pdf.is_a?(String) ? pdf.bytesize : pdf
+    def encryption(options) = options && PDF::Encryption::StandardSecurity.new(**options)
+
+    # What closes each page as it is painted. An incremental render writes
+    # every body at once, to the writer the rest of the file follows on; any
+    # other seals the pages nothing paints on again (no header, footer or
+    # page template, and no conformance audit to read them).
+    def sealer_for(incremental, conformance, encrypt:, sink:, **)
+      return PDF::PageSealer.new(writer: PDF::Writer.new(encryption: encryption(encrypt), sink:)) if incremental
+
+      config = self.class.config
+      PDF::PageSealer.new(final: conformance.nil? && config[:templates].empty? && config[:regions].empty?)
+    end
 
-    def paginate(root, book:, resources:, warnings:, debug:, tagging:)
+    # Takes the root from the builder as it hands it to the paginator, so
+    # nothing here keeps the nodes of a page that has been painted.
+    def paginate(builder, sealer, book:, resources:, warnings:, debug:, tagging:)
       Stationery.instrument("paginate.stationery", document: self.class.name) do |event|
         regions = Regions.new(self.class.config[:regions], measure: region_measure(book))
         paginator = Layout::Paginator.new(resources:, page: page_options, warnings:, debug:, regions:, tagging:)
-        paginator.paginate(root).tap do |pages|
+        paginator.paginate(builder.release) { |page| sealer.call(page) }.tap do |pages|
           PageTemplates.new(self, book:, resources:, debug:, regions:, warnings:, tagging:).apply(pages)
           event[:pages] = pages.size
         end

data/lib/stationery/elements.rb

@@ -28,12 +28,16 @@ module Stationery
     # :blockquote, :note, :caption, …) groups its content in a tagged PDF.
     # `break_inside: :auto` splits it at any page break, `:avoid` never; by
     # default it splits only when it does not fit on a page of its own.
+    # `float: :left` or `:right` takes it to that side of the flow it is in,
+    # `margin:` away from the text that wraps beside it; it needs a `width:`.
     def box(at: nil, align: nil, gap: 0, width: nil, keep_with_next: nil, break_inside: nil, anchor: nil, bookmark: nil,
-            **, &)
+            float: nil, margin: nil, **, &)
       node = Layout::Box.new(container(align:, gap:, &), width:, **)
       node.keep_with_next = keep_with_next
       node.break_inside = break_inside
       node = mark(node, anchor, bookmark)
+      return @_builder.add(floated(node, float, margin, at:, width:)) if float || margin
+
       @_builder.add(at ? Layout::Positioned.new(node, x: at[0], y: at[1], width:) : node)
     end
 
@@ -54,6 +58,16 @@ module Stationery
       @_builder.add(node)
     end
 
+    # One flow poured through `count` columns, newspaper style (a `row` is
+    # columns side by side with content of their own). `gap:` is the space
+    # between columns; `balance: true` ends them at nearly the same height
+    # where the content ends, `false` fills each before the next starts;
+    # `rule: true | { color:, width: }` draws a line between them. Continues
+    # across pages; may hold another `columns`.
+    def columns(count: 2, gap: 12, balance: true, rule: nil, align: nil, &)
+      @_builder.add(Layout::Columns.new(container(align:, &), count:, gap:, balance:, rule:))
+    end
+
     # A base with layers painted over it: every ordinary child is part of the
     # base (which sets the height), every `layer` floats over it relative to
     # the stack's rectangle, taking no space. The stack moves to the next
@@ -122,9 +136,13 @@ module Stationery
     end
 
     # `alt:` describes the image in a tagged PDF (false: decorative). Sizing,
-    # `fit: :cover`, `radius:` and `rotate:` as for Layout::Image.
-    def image(source, align: nil, **)
+    # `fit: :cover`, `radius:` and `rotate:` as for Layout::Image. `float:
+    # :left` or `:right` takes it to that side of the flow it is in, `margin:`
+    # away from the text that wraps beside it (`align:` is then not read).
+    def image(source, align: nil, float: nil, margin: nil, **)
       node = Layout::Image.new(source, **@_builder.images, **)
+      return @_builder.add(floated(node, float, margin)) if float || margin
+
       @_builder.add(align ? Layout::Flow.new([node], align:) : node)
     end
 
@@ -155,6 +173,16 @@ module Stationery
 
     private
 
+    # `margin:` is a number (kept on the sides that face the text) or names
+    # the sides as `padding:` does.
+    def floated(node, side, margin, at: nil, width: true)
+      raise ArgumentError, "margin: is the space around a float: pass float: :left or :right" unless side
+      raise ArgumentError, "a box is placed by float: or by at:, not both" if at
+      raise ArgumentError, "a floated box needs a width: points, a fraction or :auto" unless width
+
+      Layout::Floated.new(node, side:, margin: margin || 0)
+    end
+
     # What the drawing uses that is not drawn, and nesting that was flattened.
     def svg_warnings(document, name)
       if document.unsupported.any?

data/lib/stationery/errors.rb

@@ -6,9 +6,13 @@ module Stationery
   # A font file stationery cannot read or embed (CFF2, collections, WOFF, …).
   class UnsupportedFont < Error; end
 
-  # An image format stationery cannot embed (WebP, GIF, interlaced PNG, …).
+  # An image format stationery cannot embed (GIF, lossy WebP, interlaced PNG, …).
   class UnsupportedImage < Error; end
 
+  # An answer of a shaper (see Shaper) that cannot be drawn: not glyphs, a
+  # glyph the font does not have, a cluster outside the text.
+  class ShaperError < Error; end
+
   # Raised by a strict render (`to_pdf(strict: true)`) that produced warnings.
   class WarningsError < Error
     attr_reader :warnings

data/lib/stationery/fonts/font.rb

@@ -24,17 +24,28 @@ module Stationery
                           0x3000 => 1.0 }.freeze
       SPACE_LIKE = { 0x2007 => "0", 0x2008 => "." }.freeze
       NO_FEATURES = [].freeze
+      # The bytes of text the shape and metrics memos hold before they start
+      # over. They exist for the words and lines a document repeats; without a
+      # limit a long document would keep every line it ever drew.
+      MEMO_BYTES = 1 << 16
+      REPLACEMENT = "\uFFFD"
 
       attr_reader :ttf
 
-      def initialize(ttf)
+      # `shaper:` places this font's glyphs instead of the font itself (see
+      # Shaper); `path:` is the file the font was read from and `language:`
+      # the document's, both for the shaper.
+      def initialize(ttf, shaper: nil, path: nil, language: nil)
         @ttf = ttf
+        @shaping = shaper && Shaping.new(self, shaper, path:, language:)
+        @loose = nil
         @used = {}
         @pairs = {}
         @glyphs = {}
         @blanks = {}
         @shapes = {}.compare_by_identity
         @metrics = {}.compare_by_identity
+        @memoised = 0
         @keys = { true => {}, false => {} }
         @frozen_keys = { true => {}.compare_by_identity, false => {}.compare_by_identity }
         @cid_keyed = ttf.cff? && ttf.cff.cid_keyed?
@@ -47,7 +58,14 @@ module Stationery
       # Letter spacing is added per glyph, so a ligature counts once; any
       # letter spacing turns ligatures off, as it does when drawing.
       # `features:` are OpenType feature tags applied on top of `liga`.
-      def width_of(text, size, letter_spacing: 0, kerning: false, ligatures: true, features: NO_FEATURES)
+      # With a shaper the width is its glyphs'; `shape: false` measures what
+      # #glyph_run draws.
+      def width_of(text, size, letter_spacing: 0, kerning: false, ligatures: true, features: NO_FEATURES,
+                   shape: true)
+        if @shaping && shape && (run = shaped(text, size, letter_spacing:, kerning:, ligatures:, features:))
+          return run.width
+        end
+
         ligatures &&= letter_spacing.zero?
         key = shape_key(ligatures, features)
         advance, kern = metrics(text, key)
@@ -83,6 +101,7 @@ module Stationery
       # with pair kerning between the glyphs.
       def glyph_run(text, kerning: false, ligatures: true, features: NO_FEATURES)
         gids, chars, blanks = shape(text, shape_key(ligatures, features))
+        gids.each { |gid| @used.delete(gid) if @loose.delete(gid) } if @loose
         gids.each_with_index { |gid, i| @used[gid] ||= blanks[i] ? " " : chars[i] }
         adjust = gids.each_with_index.map do |gid, i|
           kern = kerning && i + 1 < gids.size ? pair(gid, gids[i + 1]) : 0
@@ -91,6 +110,28 @@ module Stationery
         GlyphRun.new(font: self, gids:, adjust:, chars:)
       end
 
+      # The text as the document's shaper placed it, a ShapedRun with its
+      # letter spacing; nil without a shaper and when the shaper declines.
+      def shaped(text, size, letter_spacing: 0, kerning: false, ligatures: true, features: NO_FEATURES)
+        return unless @shaping
+
+        @shaping.run(text, size, kerning:, ligatures: ligatures && letter_spacing.zero?, features:)
+                &.with_letter_spacing(letter_spacing)
+      end
+
+      # Remembers a glyph a shaper placed and the text it stands for, and
+      # answers the text the ToUnicode map gives it: the first it stood for.
+      # `loosely:` is for a glyph that shares its text with others (it is
+      # shown inside a Span): the next text the glyph stands for replaces it.
+      def use(gid, text, loosely: false)
+        if @used.key?(gid)
+          return @used[gid] if loosely || !@loose&.delete(gid)
+        elsif loosely
+          (@loose ||= {})[gid] = true
+        end
+        @used[gid] = text
+      end
+
       # Whether a character the font lacks is drawn as a blank (see WHITESPACE).
       def blank?(char)
         @blanks.fetch(char) { @blanks[char] = WHITESPACE.match?(char) && !glyph?(char) && glyph?(" ") }
@@ -107,9 +148,11 @@ module Stationery
       end
 
       # { code => text } for every glyph drawn so far; a ligature's text is
-      # every character it stands for.
+      # every character it stands for. Glyph 0, .notdef, stands for every
+      # character the font lacks, so it maps to the replacement character
+      # and the run's ActualText carries the real ones (see GlyphRun).
       def used_codes
-        @used.to_h { |gid, char| [code(gid), char] }
+        @used.to_h { |gid, char| [code(gid), gid.zero? ? REPLACEMENT : char] }
       end
 
       def build(writer)
@@ -151,12 +194,19 @@ module Stationery
       # each blank or nil], remembered per string and feature tags.
       def shape(text, tags)
         (@shapes[tags] ||= {})[text] ||= begin
+          forget if (@memoised += text.bytesize) > MEMO_BYTES
           gids = text.each_char.map { |char| glyph_for(char) }
           gids, chars = tags.empty? ? [gids, text.chars] : substitute(gids, text, tags)
           [gids, chars, chars.map { |char| blank_units(char) }].each(&:freeze).freeze
         end
       end
 
+      def forget
+        @shapes.each_value(&:clear)
+        @metrics.each_value(&:clear)
+        @memoised = 0
+      end
+
       def substitute(gids, text, tags)
         start = 0
         glyphs = @ttf.ligatures.substitute(gids, tags)

data/lib/stationery/fonts/font_book.rb

@@ -6,17 +6,20 @@ module Stationery
     # document gets its own book so glyph usage (and so subsetting) is per
     # document, while the parsed TrueType data is shared through the Registry.
     class FontBook
-      attr_reader :families, :fallbacks, :warnings
+      attr_reader :families, :fallbacks, :warnings, :shaper
 
       # `fallbacks:` names the families tried, in order, for a character the
-      # run's own family has no glyph for.
-      def initialize(families = {}, fallbacks: [], warnings: Warnings.new)
+      # run's own family has no glyph for. `shaper:` places the glyphs of
+      # every font of the book (see Shaper), told the text is in `language:`.
+      def initialize(families = {}, fallbacks: [], warnings: Warnings.new, shaper: nil, language: nil)
+        @shaper = Shaper.check(shaper)
+        @language = language
         @families = families.dup
         @fallbacks = fallbacks.map(&:to_s).freeze
         @warnings = warnings
         @fonts = {}
         @resolved = {}
-        @split = {}.compare_by_identity
+        @split = ObjectSpace::WeakMap.new
       end
 
       def inspect = "#<#{self.class} families=#{@families.keys.inspect}>"
@@ -35,7 +38,7 @@ module Stationery
         styles = (weights[style.weight] ||= {})
         styles[style.style] ||= begin
           face = family(style.family).face(weight: style.weight, style: style.style)
-          [@fonts[face.path] ||= Font.new(Registry.load(face.path)), face].freeze
+          [@fonts[face.path] ||= font(face.path), face].freeze
         end
       end
 
@@ -52,6 +55,12 @@ module Stationery
 
       private
 
+      def font(path)
+        return Font.new(Registry.load(path)) unless @shaper
+
+        Font.new(Registry.load(path), shaper: @shaper, path:, language: @language)
+      end
+
       # Registered by name, bundled by name, an installed pack by name, then
       # the first registered family, then the bundled default.
       def family(name)

data/lib/stationery/fonts/glyph_run.rb

@@ -7,6 +7,11 @@ module Stationery
     # source text of each glyph (several characters for a ligature). All-zero
     # adjustments draw as a plain Tj string; otherwise as a TJ array. Glyphs
     # are written as the font's character codes (see Font#code).
+    #
+    # A character no font has is glyph 0, .notdef, which stands for no
+    # character in particular: each stretch of them is shown inside a Span
+    # whose ActualText is the characters, so the text still extracts, copies
+    # and reads aloud as written.
     GlyphRun = Data.define(:font, :gids, :adjust, :chars) do
       def width(size, letter_spacing: 0)
         units = gids.sum { |gid| font.ttf.advance(gid) }
@@ -18,20 +23,45 @@ module Stationery
         with(adjust: adjust.each_with_index.map { |a, i| chars[i] == " " ? a + extra : a })
       end
 
+      def missing? = gids.include?(0)
+
       def to_operator
-        return "<#{hex(gids)}> Tj" unless adjusted?
+        return show unless missing?
+
+        last = gids.size - 1
+        gids.each_index.chunk_while { |a, b| gids[a].zero? == gids[b].zero? }.map do |indices|
+          piece = with(gids: gids.values_at(*indices), adjust: adjust.values_at(*indices),
+                       chars: chars.values_at(*indices))
+          piece.marked(trailing: indices.last < last)
+        end.join("\n")
+      end
+
+      protected
+
+      # One stretch of a run: .notdef glyphs inside their Span. `trailing`
+      # keeps the adjustment after the last glyph, which a stretch followed
+      # by another needs and the end of a run does not.
+      def marked(trailing:)
+        return show(trailing:) unless missing?
+
+        "/Span <</ActualText <FEFF#{chars.join.encode(Encoding::UTF_16BE).unpack1("H*").upcase}>>> BDC\n" \
+          "#{show(trailing:)}\nEMC"
+      end
+
+      private
+
+      def show(trailing: false)
+        return "<#{hex(gids)}> Tj" unless adjusted?(trailing)
 
         parts = gids.each_index.slice_after { |i| !adjust[i].zero? }.flat_map do |indices|
           last = indices.last
           chunk = ["<#{hex(indices.map { |i| gids[i] })}>"]
-          last == gids.size - 1 || adjust[last].zero? ? chunk : chunk << PDF::Serializer.number(-adjust[last])
+          (last == gids.size - 1 && !trailing) || adjust[last].zero? ? chunk : chunk << PDF::Serializer.number(-adjust[last])
         end
         "[#{parts.join(" ")}] TJ"
       end
 
-      private
-
-      def adjusted? = adjust[0...-1].any? { |a| !a.zero? }
+      def adjusted?(trailing) = (trailing ? adjust : adjust[0...-1]).any? { |a| !a.zero? }
 
       def hex(ids) = ids.map { |gid| font.code(gid) }.pack("n*").unpack1("H*").upcase
     end

data/lib/stationery/fonts/shaped_run.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # One stretch of text as a shaper placed it (see Shaper): its glyphs in
+    # visual order at one size, the source text of each cluster, and the
+    # extra points after each glyph that letter and word spacing add. It
+    # answers what a GlyphRun does, so the canvas draws either.
+    #
+    # Drawn as Tj/TJ like any run. The PDF's widths stay the font's own, so
+    # an advance the shaper changed is a TJ adjustment; an x offset moves the
+    # pen before its glyph and back after it, a y offset is a text rise (Ts)
+    # around it. Both are text space, so they follow a synthetic oblique's
+    # shear and leave the text matrix the line was positioned with alone.
+    #
+    # A glyph can only map to one text in the font's ToUnicode, and a reader
+    # takes glyphs in the order drawn. Wherever that cannot give the source
+    # text (glyphs out of logical order, several glyphs for one cluster, a
+    # glyph already standing for another text, .notdef) the glyphs are shown
+    # inside a Span whose ActualText is the characters in logical order.
+    ShapedRun = Data.define(:font, :size, :glyphs, :texts, :extra, :rise) do
+      def self.build(font, size, text, glyphs)
+        starts = glyphs.map(&:cluster).uniq.sort
+        texts = starts.each_with_index.to_h do |start, index|
+          [start, text[(index.zero? ? 0 : start)...(starts[index + 1] || text.length)]]
+        end
+        new(font:, size:, glyphs: glyphs.freeze, texts: texts.freeze, extra: Array.new(glyphs.size, 0).freeze, rise: 0)
+      end
+
+      def gids = glyphs.map(&:gid)
+
+      # The spacing is part of the run, whatever is asked for here.
+      def width(*, **) = (glyphs.sum(&:advance) * size / units_per_em) + extra.sum
+
+      # Letter spacing follows each cluster, not each glyph: a mark stays on
+      # its base and a ligature counts once.
+      def with_letter_spacing(points)
+        points.zero? ? self : widened { points }
+      end
+
+      # Widens every U+0020 space, as justification asks.
+      def with_word_spacing(points, _size = size)
+        widened { |text| points * text.count(" ") }
+      end
+
+      # The characters the shaper found no glyph for.
+      def missing
+        glyphs.select { |glyph| glyph.gid.zero? }.map(&:cluster).uniq.flat_map { |cluster| texts[cluster].chars }
+      end
+
+      def to_operator
+        groups = stretches.chunk_while { |(left, _), (right, _)| left == right }
+                          .map { |group| [group.first.first, group.flat_map(&:last)] }
+        groups.each_with_index.map do |(plain, indices), index|
+          trailing = index < groups.size - 1
+          plain ? show(indices, trailing) : marked(indices, trailing)
+        end.join("\n")
+      end
+
+      private
+
+      def units_per_em = font.ttf.units_per_em.to_f
+
+      def widened
+        last = glyphs.size - 1
+        with(extra: glyphs.each_with_index.map do |glyph, index|
+          closes = index == last || glyphs[index + 1].cluster != glyph.cluster
+          closes ? extra[index] + yield(texts[glyph.cluster]) : extra[index]
+        end)
+      end
+
+      # [[plain, glyph indexes], …]: the run cut wherever everything drawn so
+      # far comes before everything still to draw in the text. A piece is
+      # plain when the font's ToUnicode gives its text.
+      def stretches
+        counts = glyphs.map(&:cluster).tally
+        own = glyphs.map { |glyph| own?(glyph, counts[glyph.cluster] == 1) }
+        lows = lowest_ahead
+        high = -1
+        glyphs.each_index.slice_when { |index, following| (high = [high, glyphs[index].cluster].max) < lows[following] }
+              .map { |indices| [indices.size == 1 && own[indices.first], indices] }
+      end
+
+      # The lowest cluster from each glyph to the end of the run.
+      def lowest_ahead
+        low = nil
+        glyphs.reverse_each.map { |glyph| low = [low || glyph.cluster, glyph.cluster].min }.reverse
+      end
+
+      # Marks the glyph as used, and answers whether the font's ToUnicode maps
+      # it to its cluster's text. A glyph sharing its cluster holds the text
+      # only until a glyph drawn on its own claims another.
+      def own?(glyph, alone)
+        text = texts[glyph.cluster]
+        return font.use(glyph.gid, text) == text && glyph.gid.positive? if alone
+
+        font.use(glyph.gid, text, loosely: true)
+        false
+      end
+
+      def marked(indices, trailing)
+        text = indices.map { |index| glyphs[index].cluster }.uniq.sort.map { |cluster| texts[cluster] }.join
+        "/Span <</ActualText <FEFF#{text.encode(Encoding::UTF_16BE).unpack1("H*").upcase}>>> BDC\n" \
+          "#{show(indices, trailing)}\nEMC"
+      end
+
+      # The operators showing these glyphs. `trailing` keeps the movement
+      # after the last glyph, which glyphs that follow need.
+      def show(indices, trailing)
+        ops = []
+        parts = []
+        pending = 0.0
+        lift = 0
+        indices.each do |index|
+          glyph = glyphs[index]
+          pending += thousandths(glyph.x_offset)
+          lift = lifted(ops, parts, glyph) unless glyph.y_offset == lift
+          parts << pending unless pending.round(4).zero?
+          parts << glyph.gid
+          pending = after(index)
+        end
+        parts << pending if trailing && !pending.round(4).zero?
+        flush(ops, parts)
+        ops << "#{PDF::Serializer.number(rise)} Ts" unless lift.zero?
+        ops.join("\n")
+      end
+
+      # Ends the string being shown and sets the rise of the glyph; answers
+      # how far it is now lifted.
+      def lifted(ops, parts, glyph)
+        flush(ops, parts)
+        ops << "#{PDF::Serializer.number(rise + (glyph.y_offset * size / units_per_em))} Ts"
+        glyph.y_offset
+      end
+
+      # How far the pen moves after a glyph beyond the font's own advance, in
+      # thousandths of the size: the shaper's advance, the spacing, and back
+      # from the glyph's x offset.
+      def after(index)
+        glyph = glyphs[index]
+        thousandths(glyph.advance - font.ttf.advance(glyph.gid) - glyph.x_offset) + (extra[index] * 1000.0 / size)
+      end
+
+      def thousandths(units) = units * 1000.0 / units_per_em
+
+      # Glyph ids (Integers) and movements (Floats) as one Tj or TJ.
+      def flush(ops, parts)
+        return if parts.empty?
+
+        strings = parts.chunk_while { |left, right| left.is_a?(Integer) && right.is_a?(Integer) }.map do |chunk|
+          chunk.first.is_a?(Integer) ? "<#{hex(chunk)}>" : PDF::Serializer.number(-chunk.first)
+        end
+        ops << (strings.size == 1 ? "#{strings.first} Tj" : "[#{strings.join(" ")}] TJ")
+        parts.clear
+      end
+
+      def hex(ids) = ids.map { |gid| font.code(gid) }.pack("n*").unpack1("H*").upcase
+    end
+  end
+end