stationery 0.9.0 → 0.10.1

data/lib/stationery/pdf/writer.rb

@@ -5,15 +5,26 @@ require "digest/md5"
 module Stationery
   module PDF
     # Collects numbered objects and writes them as a PDF file with a classic
-    # cross-reference table.
+    # cross-reference table. `render` returns the file as a String with the
+    # objects in numbered order. With a `sink:` (anything answering
+    # `call(bytes)`) the file goes there in pieces instead: `flush` writes every
+    # object set so far and drops it, so objects leave in the order they were
+    # flushed and the first bytes leave before the last page is assembled.
     class Writer
       HEADER = "%PDF-1.7\n%\xE2\xE3\xCF\xD3\n".b
+      WRITTEN = Object.new.freeze
 
       # `encryption` (an Encryption::StandardSecurity) encrypts every string
       # and stream except those of its own /Encrypt dictionary.
-      def initialize(encryption: nil)
+      def initialize(encryption: nil, sink: nil)
         @objects = []
+        @offsets = []
         @encryption = encryption
+        @sink = sink
+        @buffer = HEADER.dup unless sink
+        @size = HEADER.bytesize
+        @digest = Digest::MD5.new if sink && !encryption
+        announce(HEADER) if sink
       end
 
       # Hands out a reference now and lets the object be set later, so a page
@@ -24,6 +35,8 @@ module Stationery
       end
 
       def set(ref, value)
+        raise Error, "object #{ref.id} is already written" if @objects[ref.id - 1].equal?(WRITTEN)
+
         @objects[ref.id - 1] = value
         ref
       end
@@ -32,43 +45,84 @@ module Stationery
         set(reserve, value)
       end
 
+      # With a sink: writes every object set and not yet written, lowest number
+      # first, and drops it. References to objects still unset stay valid, as
+      # the cross-reference table is written last. Without a sink it does
+      # nothing: the String keeps its objects in numbered order.
+      def flush
+        return unless @sink
+
+        @encrypt ||= reserve if @encryption
+        write_pending
+      end
+
+      # Finishes the file: the remaining objects, the cross-reference table
+      # and the trailer. Returns the whole file as a String when there is no
+      # sink, else the number of bytes handed to it.
       def render(root:, info:)
+        set(@encrypt ||= reserve, @encryption.dictionary) if @encryption
         if (missing = @objects.index(nil))
           raise Error, "object #{missing + 1} reserved but never set"
         end
 
-        @encrypt = @encryption && add(@encryption.dictionary)
-        out = HEADER.dup
-        offsets = @objects.each_with_index.map { |object, index| write_object(out, index + 1, object) }
-        xref = out.bytesize
-        id = HexString.new(@encryption ? @encryption.file_id : Digest::MD5.digest(out))
+        write_pending
+        xref = @size
+        id = HexString.new(file_id)
 
-        out << "xref\n0 #{@objects.size + 1}\n0000000000 65535 f \n"
-        offsets.each { |offset| out << format("%010d 00000 n \n", offset) }
-        out << "trailer\n" << Serializer.dump(trailer(root, info, id))
-        out << "\nstartxref\n#{xref}\n%%EOF\n"
+        emit("xref\n0 #{@objects.size + 1}\n0000000000 65535 f \n")
+        @offsets.each { |offset| emit(format("%010d 00000 n \n", offset)) }
+        emit("trailer\n#{Serializer.dump(trailer(root, info, id))}")
+        emit("\nstartxref\n#{xref}\n%%EOF\n")
+        @buffer || @size
       end
 
       private
 
+      def write_pending
+        @objects.each_with_index do |object, index|
+          next if object.nil? || object.equal?(WRITTEN)
+
+          write_object(index + 1, object)
+          @objects[index] = WRITTEN
+        end
+      end
+
       def trailer(root, info, id)
         trailer = { Size: @objects.size + 1, Root: root, Info: info, ID: [id, id] }
         @encrypt ? trailer.merge(Encrypt: @encrypt) : trailer
       end
 
-      def write_object(out, number, object)
-        offset = out.bytesize
+      def write_object(number, object)
+        @offsets[number - 1] = @size
         crypt = crypt_for(number)
-        out << "#{number} 0 obj\n"
+        emit("#{number} 0 obj\n")
         if object.is_a?(Stream)
           data = crypt ? crypt.call(object.data) : object.data
-          out << Serializer.dump(object.dictionary.merge(Length: data.bytesize), crypt)
-          out << "\nstream\n" << data << "\nendstream"
+          emit(Serializer.dump(object.dictionary.merge(Length: data.bytesize), crypt))
+          emit("\nstream\n")
+          emit(data)
+          emit("\nendstream")
         else
-          out << Serializer.dump(object, crypt)
+          emit(Serializer.dump(object, crypt))
         end
-        out << "\nendobj\n"
-        offset
+        emit("\nendobj\n")
+      end
+
+      def emit(bytes)
+        @size += bytes.bytesize
+        @sink ? announce(bytes) : @buffer << bytes
+      end
+
+      def announce(bytes)
+        @digest&.update(bytes)
+        @sink.call(bytes)
+      end
+
+      # The encryption's own identifier, else a digest of the file so far.
+      def file_id
+        return @encryption.file_id if @encryption
+
+        @digest ? @digest.digest : Digest::MD5.digest(@buffer)
       end
 
       # The Serializer hook: encrypts a string or stream with this object's key.

data/lib/stationery/rich/nodes.rb

@@ -4,7 +4,9 @@ module Stationery
   # The block model rich-text parsers (HTML, Markdown) produce and elements render.
   module Rich
     # A run of text with its marks: any of bold:, italic:, underline:, strike:, code:, link: (href),
-    # script: (:sub/:sup) and break: true, a hard line break whose text is "".
+    # script: (:sub/:sup), color: (a colour), size: (points), scale: (a factor of the text size)
+    # and break: true, a hard line break whose text is "". A false bold:, italic:, underline: or
+    # strike: switches the mark off inside an element that has it.
     Inline = Data.define(:text, :marks) do
       def self.break = new(text: "", marks: { break: true })
 
@@ -12,15 +14,39 @@ module Stationery
       def break? = marks[:break] == true
     end
 
-    Paragraph = Data.define(:inlines)
-    Heading = Data.define(:level, :inlines)
-    List = Data.define(:ordered, :start, :items)
-    Blockquote = Data.define(:blocks)
-    CodeBlock = Data.define(:text, :language)
+    # Every block carries a `style` Hash from the source's CSS (see HTML::Css):
+    # align:, background:, padding:, margin:/margin_top:/margin_bottom:,
+    # border:, width:, break_before:, break_after:, keep_together:. Empty
+    # for Markdown and for HTML without styles.
+    Paragraph = Data.define(:inlines, :style) do
+      def initialize(inlines:, style: {}) = super
+    end
+    Heading = Data.define(:level, :inlines, :style) do
+      def initialize(level:, inlines:, style: {}) = super
+    end
+    List = Data.define(:ordered, :start, :items, :style) do
+      def initialize(ordered:, start:, items:, style: {}) = super
+    end
+    Blockquote = Data.define(:blocks, :style) do
+      def initialize(blocks:, style: {}) = super
+    end
+    CodeBlock = Data.define(:text, :language, :style) do
+      def initialize(text:, language:, style: {}) = super
+    end
     Rule = Data.define
-    Table = Data.define(:rows)
-    Cell = Data.define(:header, :align, :blocks)
-    Image = Data.define(:src, :alt, :width, :height)
+    Table = Data.define(:rows, :style) do
+      def initialize(rows:, style: {}) = super
+    end
+    Cell = Data.define(:header, :align, :blocks, :style) do
+      def initialize(header:, align:, blocks:, style: {}) = super
+    end
+    Image = Data.define(:src, :alt, :width, :height, :style) do
+      def initialize(src:, alt:, width:, height:, style: {}) = super
+    end
+    # A styled container (a `div` with a background, padding, margins or a
+    # page-break rule) holding blocks; an unstyled one flattens into its parent.
+    Container = Data.define(:blocks, :style)
+    PageBreak = Data.define
 
     # Operations on inline sequences shared by the parsers.
     module Inlines
@@ -42,12 +68,12 @@ module Stationery
       end
 
       # Groups inlines into paragraphs, with each image standing as a block between them.
-      def paragraphs(items)
+      def paragraphs(items, style: {})
         items.chunk_while { |a, b| !a.is_a?(Image) && !b.is_a?(Image) }.filter_map do |run|
           next run.first if run.first.is_a?(Image)
 
           inlines = merge(block_given? ? yield(run) : run)
-          Paragraph.new(inlines:) unless inlines.empty?
+          Paragraph.new(inlines:, style:) unless inlines.empty?
         end
       end
     end

data/lib/stationery/rich/renderer/boxes.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Rich
+    class Renderer
+      # What a block's CSS style becomes around the block: margins as spacers,
+      # a background and padding as a box, page-break rules as page breaks and
+      # kept-together groups, borders and widths as table options.
+      module Boxes
+        PADDING = { padding_top: 0, padding_right: 1, padding_bottom: 2, padding_left: 3 }.freeze
+
+        private
+
+        # Draws the block inside its margins and its box. A block styled with
+        # nothing but an alignment draws as it is.
+        def styled(style, &)
+          return yield if style.empty?
+
+          spaced(style) { boxed(style, &) }
+        end
+
+        # Page breaks and margins around the block, and the rule that keeps it
+        # on one page.
+        def spaced(style)
+          return yield unless spacing?(style)
+
+          top, bottom = margins(style)
+          @component.page_break if style[:break_before]
+          @component.group(keep_together: style[:keep_together] == true) do
+            @component.spacer(top) if top.positive?
+            yield
+            @component.spacer(bottom) if bottom.positive?
+          end
+          @component.page_break if style[:break_after]
+        end
+
+        def spacing?(style)
+          style[:break_before] || style[:break_after] || style[:keep_together] || margins(style).any?(&:positive?)
+        end
+
+        def margins(style)
+          all = style[:margin]
+          [style[:margin_top] || all&.[](0) || 0, style[:margin_bottom] || all&.[](2) || 0]
+        end
+
+        def boxed(style, &)
+          options = box_options(style)
+          options.empty? ? yield : @component.box(**options, &)
+        end
+
+        # The background and padding a style gives a box, to merge over a
+        # block's own (`styles[:blockquote]`, `styles[:pre]`).
+        def box_options(style)
+          options = {}
+          options[:background] = style[:background] if style[:background]
+          padding = padding_of(style)
+          options[:padding] = padding if padding
+          options
+        end
+
+        def padding_of(style)
+          sides = PADDING.select { |key, _| style[key] }
+          return style[:padding] if sides.empty?
+
+          padding = (style[:padding] || [0, 0, 0, 0]).dup
+          sides.each { |key, index| padding[index] = style[key] }
+          padding
+        end
+
+        def aligned(style) = style[:align] ? { align: style[:align] } : {}
+
+        def border_options(border)
+          return {} unless border
+          return { borders: [] } if border[:width].zero?
+
+          { border_width: border[:width], border_color: border[:color] }
+        end
+
+        def cell_options(style)
+          options = border_options(style[:border]).merge(box_options(style))
+          options[:borders] = %i[top right bottom left] if options[:border_width]
+          options
+        end
+
+        # Column widths from the first row, when every cell of it has one. A
+        # percentage is a share of the table, which then takes the full width
+        # unless it has a width of its own.
+        def column_widths(table)
+          widths = table.rows.first.map { |cell| cell.style[:width] }
+          return {} unless widths.all?
+
+          widths.any? { |width| fraction?(width) } && !table.style[:width] ? { widths:, width: :full } : { widths: }
+        end
+
+        # A table's own width: points, the full width for 100%, or a share of
+        # the space through a box of that width.
+        def sized(width)
+          return yield({}) unless width
+          return yield({ width: }) unless fraction?(width)
+          return yield({ width: :full }) if width >= 1
+
+          @component.box(width:) { yield({ width: :full }) }
+        end
+
+        def fraction?(value) = value.is_a?(Float) && value <= 1
+      end
+    end
+  end
+end

data/lib/stationery/rich/renderer/indents.rb

@@ -30,6 +30,7 @@ module Stationery
           blocks.map do |block|
             case block
             when Blockquote then 1 + indents_of(block.blocks)
+            when Container then indents_of(block.blocks)
             when List then 1 + (block.items.map { |item| indents_of(item) }.max || 0)
             when Table then block.rows.flatten.map { |cell| indents_of(cell.blocks) }.max || 0
             else 0

data/lib/stationery/rich/renderer/inlines.rb

@@ -15,8 +15,12 @@ module Stationery
           font: ->(value) { [:font, value] if value }
         }.freeze
 
+        # A true mark switches the style on, a false one (from CSS) switches it off again.
         MARK_STEPS = {
-          bold: [[:b]], italic: [[:i]], underline: [[:u]], strike: [[:strikethrough]]
+          bold: { true => [[:b]], false => [[:with, { weight: :regular }]] },
+          italic: { true => [[:i]], false => [[:with, { style: :normal }]] },
+          underline: { true => [[:u]], false => [[:with, { underline: false }]] },
+          strike: { true => [[:strikethrough]], false => [[:with, { strikethrough: false }]] }
         }.freeze
 
         def initialize(runs, styles, links = Links.new(:all, nil))
@@ -50,7 +54,10 @@ module Stationery
           when :link then [[:link, value], *style_steps(@styles[:a])]
           when :code then style_steps(@styles[:code])
           when :script then [[value]]
-          else MARK_STEPS.fetch(mark, [])
+          when :color then [[:color, value]]
+          when :size then [[:size, value]]
+          when :scale then [[:scale, value]]
+          else MARK_STEPS.dig(mark, value) || []
           end
         end
 

data/lib/stationery/rich/renderer.rb

@@ -5,6 +5,7 @@ require_relative "styles"
 require_relative "renderer/indents"
 require_relative "renderer/inlines"
 require_relative "renderer/links"
+require_relative "renderer/boxes"
 
 module Stationery
   module Rich
@@ -12,9 +13,12 @@ module Stationery
     # `images:` (a callable given the src, returning a path, an IO or nil) or
     # from files under `base_path:`; remote URLs are never fetched. Block
     # quotes and lists nested deeper than Indents::LIMIT stop indenting, which
-    # is reported as a NestingLimit warning.
+    # is reported as a NestingLimit warning. A block's `style` (from the
+    # source's CSS) adds margins, a box, an alignment or a page break around
+    # what `styles:` draws; a block without one draws exactly as before.
     class Renderer
       include Indents
+      include Boxes
 
       REMOTE = /\A[a-z][a-z0-9+.-]*:/i
       LINK_SCHEMES = %w[http https mailto tel].freeze
@@ -43,14 +47,16 @@ module Stationery
 
       def block(block)
         case block
-        when Paragraph then paragraph(block.inlines, **@styles[:p])
-        when Heading then heading(block)
-        when List then indented(block) { list(block) }
-        when Blockquote then indented(block) { blockquote(block) }
-        when CodeBlock then code(block)
+        when Paragraph then styled(block.style) { paragraph(block.inlines, **@styles[:p], **aligned(block.style)) }
+        when Heading then styled(block.style) { heading(block) }
+        when List then styled(block.style) { indented(block) { list(block) } }
+        when Blockquote then spaced(block.style) { indented(block) { blockquote(block) } }
+        when CodeBlock then spaced(block.style) { code(block) }
         when Rule then @component.rule(**@styles[:hr])
-        when Table then table(block)
+        when Table then styled(block.style.except(:border, :width)) { table(block) }
         when Image then image(block)
+        when Container then styled(block.style) { group(block.blocks) }
+        when PageBreak then @component.page_break
         end
       end
 
@@ -62,7 +68,8 @@ module Stationery
         style = @styles[:"h#{heading.level}"]
         size = style[:size] || (@builder.style.size * style.fetch(:scale, 1))
         bookmark = heading_bookmark(heading)
-        paragraph(heading.inlines, **style.except(:scale), size:, heading: heading.level, **({ bookmark: } if bookmark))
+        paragraph(heading.inlines, **style.except(:scale), size:, heading: heading.level,
+                                                           **aligned(heading.style), **({ bookmark: } if bookmark))
       end
 
       def heading_bookmark(heading)
@@ -72,7 +79,7 @@ module Stationery
       end
 
       def blockquote(quote)
-        @component.box(role: :blockquote, **@styles[:blockquote]) { group(quote.blocks) }
+        @component.box(role: :blockquote, **@styles[:blockquote], **box_options(quote.style)) { group(quote.blocks) }
       end
 
       def list(list)
@@ -86,18 +93,23 @@ module Stationery
 
       def code(block)
         font = @styles[:code][:font]
-        @component.box(**@styles[:pre]) { @component.text(block.text, **({ font: } if font)) }
+        @component.box(**@styles[:pre], **box_options(block.style)) do
+          @component.text(block.text, **({ font: } if font))
+        end
       end
 
       def table(table)
         header = table.rows.first&.all?(&:header) ? 1 : 0
         rows = table.rows.map { |row| row.map { |cell| cell_content(cell) } }
-        @component.table(rows, header:, cell: @styles[:table][:cell])
+        cell = @styles[:table][:cell].merge(border_options(table.style[:border]))
+        sized(table.style[:width]) { |width| @component.table(rows, header:, cell:, **width, **column_widths(table)) }
       end
 
       def cell_content(cell)
         style = cell.header ? @styles[:table][:header] : {}
-        -> { @component.text_style(**style, align: cell.align) { group(cell.blocks) } }
+        content = -> { @component.text_style(**style, align: cell.align) { group(cell.blocks) } }
+        options = cell_options(cell.style)
+        options.empty? ? content : { content:, **options }
       end
 
       def image(node)
@@ -105,7 +117,7 @@ module Stationery
         return unless source
 
         loaded = Images.load(source)
-        @component.image(loaded, alt: node.alt, **dimensions(node, loaded))
+        @component.image(loaded, alt: node.alt, **aligned(node.style), **dimensions(node, loaded))
       rescue UnsupportedImage => e
         skip(node.src, e.message)
       end
@@ -121,9 +133,14 @@ module Stationery
         File.file?(path) ? path : skip(src, "not found")
       end
 
+      # A CSS width wins over the width and height attributes (the height
+      # then follows the aspect ratio); a percentage is a share of the space.
       def dimensions(node, loaded)
-        width = node.width
-        height = node.height
+        styled = node.style[:width]
+        return { width: styled } if fraction?(styled)
+
+        width = styled || node.width
+        height = styled ? nil : node.height
         limit = @styles[:img][:max_width]
         natural = width || (height ? loaded.width * height.fdiv(loaded.height) : loaded.width)
         return { width:, height: } unless limit && natural > limit

data/lib/stationery/svg/style.rb

@@ -2,6 +2,9 @@
 
 module Stationery
   module SVG
+    Selector = CSS::Selector
+    Stylesheet = CSS::Stylesheet
+
     # Presentation attributes an element inherits from its ancestors, and the
     # transform it draws with. An element's own values cascade: presentation
     # attributes, then stylesheet rules, then its inline `style`. `color` sets
@@ -27,12 +30,7 @@ module Stationery
         NAMED.fetch(value.downcase, value)
       end
 
-      def self.declarations(style)
-        style.to_s.split(";").filter_map do |declaration|
-          key, value = declaration.split(":", 2).map(&:strip)
-          [key, value] if key && value
-        end.to_h
-      end
+      def self.declarations(style) = CSS.declarations(style)
 
       attr_reader :values, :matrix, :color
 

data/lib/stationery/testing/inspector.rb

@@ -12,6 +12,8 @@ module Stationery
     # Needs the pdf-reader gem, loaded on first use.
     class Inspector
       UTF16_BOM = "\xFE\xFF".b
+      # id-aa-signatureTimeStampToken: a signature's RFC 3161 timestamp.
+      TIMESTAMP_TOKEN = "1.2.840.113549.1.9.16.2.14"
       XMP_PROPERTY = %r{^\s*<((?!rdf:)[\w.-]+:[\w.-]+)>(.*?)</\1>$}
       XMP_ITEM = %r{<rdf:li[^>]*>(.*?)</rdf:li>}
       XMP_ENTITIES = { "&amp;" => "&", "&lt;" => "<", "&gt;" => ">", "&quot;" => '"' }.freeze
@@ -134,10 +136,13 @@ module Stationery
       end
 
       # Every signed signature field: `{ field:, name:, reason:, location:,
-      # signed_at:, subfilter:, byte_range:, signer:, valid: }`. `signer` is
-      # the signing certificate's subject ("CN=…,O=…"). `valid` is whether
-      # the signature covers the whole file and verifies against the
+      # signed_at:, subfilter:, byte_range:, signer:, valid:, timestamp: }`.
+      # `signer` is the signing certificate's subject ("CN=…,O=…"). `valid` is
+      # whether the signature covers the whole file and verifies against the
       # certificate it carries; the certificate's own trust is not judged.
+      # `timestamp` is nil, or `{ time:, tsa:, valid: }` for the RFC 3161 token
+      # a signature carries: `valid` when the token is over this signature
+      # and verifies against the TSA certificate it carries.
       def signatures
         form = catalog[:AcroForm]
         return [] unless form
@@ -207,13 +212,51 @@ module Stationery
       # parsed dictionary: it is the one string encryption leaves alone.
       def verdict(range)
         contents = pdf.byteslice(range[1], range[2] - range[1]).to_s
-        cms = OpenSSL::PKCS7.new(PDF::Signature.der([contents[1..-2]].pack("H*")))
+        der = PDF::Signature.der([contents[1..-2]].pack("H*"))
+        cms = OpenSSL::PKCS7.new(der)
         signed = pdf.byteslice(range[0], range[1]) + pdf.byteslice(range[2], range[3])
         flags = OpenSSL::PKCS7::NOVERIFY | OpenSSL::PKCS7::BINARY
         whole = range[0].zero? && range[2] + range[3] == pdf.bytesize && contents.start_with?("<")
-        { signer: signer(cms), valid: whole && cms.verify([], OpenSSL::X509::Store.new, signed, flags) }
+        { signer: signer(cms), valid: whole && cms.verify([], OpenSSL::X509::Store.new, signed, flags),
+          timestamp: timestamp(der) }
       rescue OpenSSL::OpenSSLError, ArgumentError, TypeError
-        { signer: nil, valid: false }
+        { signer: nil, valid: false, timestamp: nil }
+      end
+
+      # The timestamp token among the first SignerInfo's unsigned attributes,
+      # judged against that SignerInfo's signature value; nil without one.
+      def timestamp(der)
+        info = OpenSSL::ASN1.decode(der).value[1].value[0].value[4].value[0].value
+        unsigned = info[6..].to_a.find { |item| item.tag == 1 && item.tag_class == :CONTEXT_SPECIFIC }
+        attribute = unsigned&.value&.find { |one| one.value[0].oid == TIMESTAMP_TOKEN }
+        attribute && timestamp_verdict(attribute.value[1].value.first, info[5].value)
+      end
+
+      # The token verified as a TimeStampResp would be, against the signature
+      # value it should cover. The certificates it carries are the trust
+      # anchors (a TSA sends its chain, often without the root), so this
+      # says the token is sound, not that the TSA is one to trust.
+      def timestamp_verdict(token, signature)
+        granted = OpenSSL::ASN1::Sequence.new([OpenSSL::ASN1::Integer.new(0)])
+        response = OpenSSL::Timestamp::Response.new(OpenSSL::ASN1::Sequence.new([granted, token]).to_der)
+        info = response.token_info
+        covers = info.message_imprint == OpenSSL::Digest.digest(info.algorithm, signature)
+        { time: info.gen_time, tsa: signer(response.token), valid: covers && timestamp_verifies?(response) }
+      end
+
+      def timestamp_verifies?(response)
+        info = response.token_info
+        request = OpenSSL::Timestamp::Request.new
+        request.algorithm = info.algorithm
+        request.message_imprint = info.message_imprint
+        request.nonce = info.nonce if info.nonce
+        store = OpenSSL::X509::Store.new
+        store.flags = OpenSSL::X509::V_FLAG_PARTIAL_CHAIN
+        response.token.certificates.to_a.each { |certificate| store.add_cert(certificate) }
+        response.verify(request, store)
+        true
+      rescue OpenSSL::OpenSSLError
+        false
       end
 
       def signer(cms)

data/lib/stationery/testing/marked_text.rb

@@ -16,6 +16,8 @@ module Stationery
                  set_character_spacing set_word_spacing set_text_rise set_horizontal_text_scaling
                  set_text_rendering_mode].freeze
 
+      UTF16_BOM = "\xFE\xFF".b
+
       def_delegators :@state, *STATE
 
       # { MCID => text } and the strings shown outside marked content.
@@ -31,20 +33,30 @@ module Stationery
         @unmarked = []
       end
 
+      # A sequence with ActualText reads as that text, whatever it shows.
       def begin_marked_content_with_pl(_tag, properties)
-        @open << (properties[:MCID] if properties.is_a?(Hash))
+        properties = {} unless properties.is_a?(Hash)
+        @open << properties[:MCID]
+        return unless properties[:ActualText]
+
+        @actual = decode(properties[:ActualText])
+        @actual_depth = @open.size
       end
 
       def begin_marked_content(_tag) = @open << nil
-      def end_marked_content = @open.pop
+
+      def end_marked_content
+        @actual = nil if @actual_depth && @open.size <= @actual_depth
+        @open.pop
+      end
+
       def show_text(string) = append(string)
       def show_text_with_positioning(params) = params.grep(String).each { |string| append(string) }
 
       private
 
       def append(string)
-        font = @state.current_font
-        text = font.unpack(string).map { |code| font.to_utf8(code) }.join
+        text = shown(string)
         return @unmarked << text if @open.empty?
 
         mcid = @open.compact.last
@@ -55,6 +67,24 @@ module Stationery
         @texts[mcid] = "#{@texts[mcid]}#{separator}#{text}"
         @baselines[mcid] = baseline
       end
+
+      # The characters a string shows: its ActualText once, when it has one.
+      def shown(string)
+        if @actual
+          text = @actual
+          @actual = ""
+          return text
+        end
+
+        font = @state.current_font
+        font.unpack(string).map { |code| font.to_utf8(code) }.join
+      end
+
+      def decode(text)
+        return text.dup.force_encoding(Encoding::UTF_8) unless text.b.start_with?(UTF16_BOM)
+
+        text.b.byteslice(2..).force_encoding(Encoding::UTF_16BE).encode(Encoding::UTF_8)
+      end
     end
   end
 end