stationery 0.8.0 → 0.10.0

data/lib/stationery/rich/renderer.rb

@@ -2,15 +2,24 @@
 
 require_relative "nodes"
 require_relative "styles"
+require_relative "renderer/indents"
 require_relative "renderer/inlines"
 require_relative "renderer/links"
+require_relative "renderer/boxes"
 
 module Stationery
   module Rich
     # Draws rich-text blocks with a component's element DSL. Images come from
     # `images:` (a callable given the src, returning a path, an IO or nil) or
-    # from files under `base_path:`; remote URLs are never fetched.
+    # 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. 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
 
@@ -23,22 +32,31 @@ module Stationery
         @base_path = base_path && File.expand_path(base_path.to_s)
         @bookmarks = bookmarks
         @links = Links.new(links || LINK_SCHEMES, builder.warnings)
+        @indents = 0
       end
 
-      def render(blocks) = @component.group(gap: @gap) { blocks.each { |block| block(block) } }
+      def render(blocks)
+        depth = indents_of(blocks)
+        @builder.warnings << Warnings::NestingLimit.new(depth:, limit: Indents::LIMIT) if depth > Indents::LIMIT
+        group(blocks)
+      end
 
       private
 
+      def group(blocks) = @component.group(gap: @gap) { blocks.each { |block| block(block) } }
+
       def block(block)
         case block
-        when Paragraph then paragraph(block.inlines, **@styles[:p])
-        when Heading then heading(block)
-        when List then list(block)
-        when Blockquote then @component.box(role: :blockquote, **@styles[:blockquote]) { render(block.blocks) }
-        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
 
@@ -50,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)
@@ -59,29 +78,38 @@ module Stationery
         { title: heading.inlines.grep(Inline).map(&:text).join, level: heading.level }
       end
 
+      def blockquote(quote)
+        @component.box(role: :blockquote, **@styles[:blockquote], **box_options(quote.style)) { group(quote.blocks) }
+      end
+
       def list(list)
         options = list.ordered ? { **@styles[:ol], start: list.start || 1 } : @styles[:ul]
         @component.public_send(list.ordered ? :ol : :ul, **options) do
           list.items.each do |blocks|
-            @component.li { @component.text_style(**@styles[:li]) { render(blocks) } }
+            @component.li { @component.text_style(**@styles[:li]) { group(blocks) } }
           end
         end
       end
 
       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) { render(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)
@@ -89,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
@@ -105,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/document.rb

@@ -16,16 +16,20 @@ module Stationery
                            tspan use symbol clipPath]).freeze
 
       def self.parse(source)
-        root = Parser.parse(source)
+        nesting = nil
+        root = Parser.parse(source) { |depth| nesting = depth }
         raise Error, "not an svg document" unless root&.name == "svg"
 
-        new(root)
+        new(root, nesting:)
       end
 
-      attr_reader :view_box, :unsupported
+      # `nesting` is how deep the source nested when that was deeper than
+      # Parser::MAX_DEPTH (and was flattened there), else nil.
+      attr_reader :view_box, :unsupported, :nesting
 
-      def initialize(root)
+      def initialize(root, nesting: nil)
         @root = root
+        @nesting = nesting
         @view_box = read_view_box
         @sheet = Stylesheet.parse(style_text)
         @gradients = Gradient.collect(root, @sheet)

data/lib/stationery/svg/parser.rb

@@ -8,10 +8,15 @@ module Stationery
     # Comments, processing instructions and doctypes are skipped; text content
     # (CDATA included) is kept only inside text, tspan and style, as String
     # children with entities decoded and each whitespace run one space.
+    #
+    # An element nested deeper than MAX_DEPTH is not descended into: it takes
+    # its place in the deepest element kept and so does what it holds, so
+    # nothing that walks the tree recurses deeper than that.
     module Parser
       Element = Data.define(:name, :attributes, :children)
 
       TEXT = %w[text tspan style].freeze
+      MAX_DEPTH = 128
 
       IGNORED = /<!--.*?-->|<\?.*?\?>|<!DOCTYPE[^>]*>/m
       CDATA = /<!\[CDATA\[(.*?)\]\]>/m
@@ -21,17 +26,19 @@ module Stationery
 
       module_function
 
-      def parse(source)
+      # The root element. The block is given how deep the source nested when
+      # that was deeper than `max_depth`.
+      def parse(source, max_depth: MAX_DEPTH)
         source = source.to_s.gsub(IGNORED, "").gsub(CDATA) { Regexp.last_match(1).gsub(/[&<>]/, ESCAPES) }
         scanner = StringScanner.new(source)
-        root = Element.new("document", {}, [])
-        stack = [root]
+        tree = Tree.new(max_depth)
         while (content = scanner.scan_until(/(?=<)/))
-          keep(stack.last, content)
+          keep(tree.open, content)
           tag = scanner.scan(TAG) or (scanner.getch && next)
-          handle(stack, *tag.match(TAG).captures)
+          tree.tag(*tag.match(TAG).captures)
         end
-        root.children.first
+        yield tree.deepest if block_given? && tree.deepest > max_depth
+        tree.root
       end
 
       # Yields the element and every element below it, depth first.
@@ -46,12 +53,45 @@ module Stationery
         element.children << Stationery::Text::Entities.decode(content).gsub(/\s+/, " ")
       end
 
-      def handle(stack, closing, name, attributes, self_closing)
-        return stack.pop if closing == "/" && stack.size > 1
+      # The elements open while the source is read. `hoisted` counts the open
+      # ones too deep to descend into; their end tags are counted off again.
+      class Tree
+        attr_reader :deepest
 
-        element = Element.new(name, attributes.scan(ATTRIBUTE).to_h { |k, *v| [k, v.compact.first] }, [])
-        stack.last.children << element
-        stack << element if self_closing.empty?
+        def initialize(max_depth)
+          @document = Element.new("document", {}, [])
+          @stack = [@document]
+          @max_depth = max_depth
+          @hoisted = 0
+          @deepest = 0
+        end
+
+        def root = @document.children.first
+        def open = @stack.last
+
+        def tag(closing, name, attributes, self_closing)
+          return close if closing == "/"
+
+          element = Element.new(name, attributes.scan(ATTRIBUTE).to_h { |k, *v| [k, v.compact.first] }, [])
+          open.children << element
+          descend(element) if self_closing.empty?
+        end
+
+        private
+
+        def close
+          return @hoisted -= 1 if @hoisted.positive?
+
+          @stack.pop if @stack.size > 1
+        end
+
+        def descend(element)
+          depth = @stack.size + @hoisted
+          @deepest = depth if depth > @deepest
+          return @stack << element if @stack.size <= @max_depth
+
+          @hoisted += 1
+        end
       end
     end
   end

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/svg/walker.rb

@@ -11,6 +11,7 @@ module Stationery
     class Walker
       RENDERED = (Shapes::NAMES + %w[text g use svg]).freeze
       VIEWPORTS = %w[symbol svg].freeze
+      MAX_USES = 32 # a use of a use of a use …
 
       attr_reader :issues
 
@@ -69,6 +70,7 @@ module Stationery
         target, id = target_of(element)
         return unless target
         return issue("use: circular reference ##{id}") if chain.include?(id)
+        return issue("use: nested deeper than #{MAX_USES}") if chain.size >= MAX_USES
 
         attributes = element.attributes
         placed = style.transformed([1, 0, 0, 1, Shapes.f(attributes, "x"), Shapes.f(attributes, "y")])

data/lib/stationery/tagging/element.rb

@@ -39,7 +39,7 @@ module Stationery
         @type = type
         @alt = alt
         @kind = kind
-        @attributes = attributes.transform_values(&:dup)
+        @attributes = attributes.empty? ? {} : attributes.transform_values(&:dup)
         @kids = []
       end
 

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
@@ -133,6 +135,22 @@ module Stationery
         entries.each_slice(2).map { |_name, ref| attachment(objects.deref_hash(ref)) }
       end
 
+      # Every signed signature field: `{ field:, name:, reason:, location:,
+      # 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
+
+        require "openssl"
+        signature_fields(objects.deref_hash(form)[:Fields], nil)
+      end
+
       # The structure tree of a tagged PDF as nested arrays; see StructureReader.
       def structure = @structure ||= StructureReader.new(reader).tree
 
@@ -167,6 +185,86 @@ module Stationery
           description: spec[:Desc] && decode(spec[:Desc]), relationship: }
       end
 
+      def signature_fields(refs, prefix)
+        Array(objects.deref_array(refs)).flat_map do |ref|
+          field = objects.deref_hash(ref)
+          name = [prefix, field[:T] && decode(field[:T])].compact.join(".")
+          kids = Array(objects.deref_array(field[:Kids])).select { |kid| objects.deref_hash(kid).key?(:T) }
+          next signature_fields(kids, name) if kids.any?
+
+          field[:FT] == :Sig && field[:V] ? [signature(name, objects.deref_hash(field[:V]))] : []
+        end
+      end
+
+      def signature(field, value)
+        range = objects.deref_array(value[:ByteRange])
+        text = value.slice(:Name, :Reason, :Location).transform_values { |string| decode(string) }
+        { field:, name: text[:Name], reason: text[:Reason], location: text[:Location],
+          signed_at: signing_time(value[:M]), subfilter: value[:SubFilter], byte_range: range, **verdict(range) }
+      end
+
+      def signing_time(date)
+        digits = date.to_s[/\AD:(\d{14})/, 1]
+        digits && Time.utc(*digits.unpack("a4a2a2a2a2a2").map(&:to_i))
+      end
+
+      # The signature is read from the file by its byte range, not from the
+      # parsed dictionary: it is the one string encryption leaves alone.
+      def verdict(range)
+        contents = pdf.byteslice(range[1], range[2] - range[1]).to_s
+        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),
+          timestamp: timestamp(der) }
+      rescue OpenSSL::OpenSSLError, ArgumentError, TypeError
+        { 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)
+        info = cms.signers.first
+        certificate = cms.certificates.find { |one| one.serial == info.serial && one.issuer == info.issuer }
+        certificate&.subject&.to_utf8
+      end
+
       def xmp_value(body)
         items = body.scan(XMP_ITEM).flatten.map { |item| xmp_text(item) }
         return xmp_text(body) if items.empty?

data/lib/stationery/testing/matchers.rb

@@ -183,6 +183,30 @@ module Stationery
         end
       end
 
+      class HaveSignature < Base
+        def initialize(name: nil, valid: true)
+          super(name)
+          @valid = valid
+        end
+
+        def description
+          "have #{@valid ? "a valid" : "an invalid"} signature#{" by #{show(@expected)}" if @expected}"
+        end
+
+        private
+
+        def match?(pdf)
+          pdf.signatures.any? { |one| (@expected.nil? || one[:name] == @expected) && one[:valid] == @valid }
+        end
+
+        def actual
+          signatures = @inspector.signatures
+          return "got none" if signatures.empty?
+
+          "got #{signatures.map { |one| "#{one[:name].inspect} (#{one[:valid] ? "valid" : "invalid"})" }.join(", ")}"
+        end
+      end
+
       class HaveNoWarnings < Base
         def description = "have no warnings"
 
@@ -227,6 +251,7 @@ module Stationery
       def have_attachment(name, **) = HaveAttachment.new(name, **)
       def have_conformance(*levels) = HaveConformance.new(*levels)
       def have_factur_x(profile: nil) = HaveFacturX.new(profile:)
+      def have_signature(name: nil, valid: true) = HaveSignature.new(name:, valid:)
       def have_no_warnings = HaveNoWarnings.new
       def have_structure(expected) = HaveStructure.new(expected)
       def have_tagged_content = HaveTaggedContent.new

data/lib/stationery/text/breaks.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Text
+    # Where a line may break inside a word: between two ideographic
+    # characters (UAX #14 class ID: CJK ideographs, kana, Hangul, fullwidth
+    # forms), never before a closing mark or a character that must not start
+    # a line (、。」ー and the small kana: classes CL, CP, EX and NS), never
+    # after an opening bracket (「（: class OP). A word is cut into units at
+    # those points; Latin text stays one unit, so its breaking is unchanged.
+    module Breaks
+      ZERO_WIDTH_SPACE = "​"
+
+      IDEOGRAPHIC = [
+        0x1100..0x11FF,   # Hangul Jamo
+        0x2E80..0x2FDF,   # CJK radicals
+        0x3005..0x3007,   # 々 〆 〇
+        0x3021..0x3029,   # Hangzhou numerals
+        0x3031..0x3035,   # kana repeat marks
+        0x3038..0x303C,
+        0x3041..0x309A,   # Hiragana (the small kana are taken out below)
+        0x30A1..0x30FA,   # Katakana
+        0x3100..0x312F,   # Bopomofo
+        0x3130..0x318F,   # Hangul compatibility Jamo
+        0x3190..0x31FF,   # Kanbun, Bopomofo extended, CJK strokes, Katakana phonetic extensions
+        0x3200..0x33FF,   # enclosed CJK, CJK compatibility
+        0x3400..0x4DBF,   # CJK extension A
+        0x4E00..0x9FFF,   # CJK unified ideographs
+        0xA000..0xA4CF,   # Yi
+        0xA960..0xA97F,   # Hangul Jamo extended A
+        0xAC00..0xD7AF,   # Hangul syllables
+        0xF900..0xFAFF,   # CJK compatibility ideographs
+        0xFE30..0xFE4F,   # CJK compatibility forms
+        0xFF10..0xFF19,   # fullwidth digits
+        0xFF21..0xFF3A, 0xFF41..0xFF5A, # fullwidth Latin
+        0xFF66..0xFF6F, 0xFF71..0xFF9D, # halfwidth Katakana (ｰ and the small ones are NS)
+        0x1B000..0x1B16F, # Kana supplement and extended
+        0x20000..0x3134F  # CJK extensions B–G
+      ].freeze
+
+      # Never at the start of a line: closing brackets and quotes, sentence
+      # and clause punctuation, prolonged sound and iteration marks, small kana.
+      CLOSING = [
+        0x3001..0x3003, 0x3009, 0x300B, 0x300D, 0x300F, 0x3011, 0x3015, 0x3017, 0x3019, 0x301B, 0x301C,
+        0x301F, 0x303B, 0x309B..0x309E, 0x30A0, 0x30FB..0x30FE,
+        0x3041, 0x3043, 0x3045, 0x3047, 0x3049, 0x3063, 0x3083, 0x3085, 0x3087, 0x308E, 0x3095, 0x3096,
+        0x30A1, 0x30A3, 0x30A5, 0x30A7, 0x30A9, 0x30C3, 0x30E3, 0x30E5, 0x30E7, 0x30EE, 0x30F5, 0x30F6,
+        0x31F0..0x31FF,
+        0xFE50..0xFE52, 0xFE54..0xFE57, 0xFE5A, 0xFE5C, 0xFE5E,
+        0xFF01, 0xFF09, 0xFF0C, 0xFF0E, 0xFF1A, 0xFF1B, 0xFF1F, 0xFF3D, 0xFF5D, 0xFF60, 0xFF61, 0xFF63,
+        0xFF64, 0xFF65, 0xFF67..0xFF6F, 0xFF70, 0xFF9E, 0xFF9F,
+        0x2025, 0x2026
+      ].freeze
+
+      # Never at the end of a line: opening brackets and quotes.
+      OPENING = [
+        0x3008, 0x300A, 0x300C, 0x300E, 0x3010, 0x3014, 0x3016, 0x3018, 0x301A, 0x301D,
+        0xFE59, 0xFE5B, 0xFE5D,
+        0xFF08, 0xFF3B, 0xFF5B, 0xFF5F, 0xFF62
+      ].freeze
+
+      CLOSING_CODES = CLOSING.flat_map { |entry| Array(entry) }.to_h { |code| [code, true] }.freeze
+      OPENING_CODES = OPENING.flat_map { |entry| Array(entry) }.to_h { |code| [code, true] }.freeze
+
+      module_function
+
+      def ideographic?(char)
+        code = char.ord
+        !CLOSING_CODES.key?(code) && IDEOGRAPHIC.any? { |range| range.cover?(code) }
+      end
+
+      def closing?(char) = CLOSING_CODES.key?(char.ord)
+      def opening?(char) = OPENING_CODES.key?(char.ord)
+
+      # Whether `text` holds any character these rules know about, the cheap
+      # test that keeps Latin text on the fast path.
+      def cjk?(text) = text.match?(CJK)
+
+      CJK = /[ᄀ-ᇿ⺀-⿟、-ヿ㄀-鿿ꀀ-꓏ꥠ-꥿가-힯豈-﫿︰-﹞！-ﾟ\u{1B000}-\u{1B16F}\u{20000}-\u{3134F}‥…]/
+
+      # The word's break units in order, each `[text, glued]`: `glued` is true
+      # for a unit that must stay with the unit before it (it starts with a
+      # closing mark), so the caller joins it to whatever came before, even
+      # across styled runs. A word without CJK characters is one unit.
+      def units(word)
+        return [[word, false]] unless cjk?(word)
+
+        units = []
+        current = +""
+        glued = false
+        open = false # current holds opening brackets only, waiting for what they open
+        word.each_char do |char|
+          if closing?(char)
+            glued = true if current.empty?
+          elsif starts_unit?(char, current, open)
+            units << [current.freeze, glued] unless current.empty?
+            current = +""
+            glued = false
+          end
+          current << char
+          open = opening?(char) && (open || current.length == 1)
+        end
+        units << [current.freeze, glued] unless current.empty?
+        units
+      end
+
+      # Whether `char` opens a new unit after `current`: an opening bracket or
+      # an ideographic character does unless `current` is only opening
+      # brackets; Latin text does after a unit that ends in a CJK character
+      # (an opening bracket or Latin followed by a closing mark stay glued).
+      def starts_unit?(char, current, open)
+        return false if current.empty? || open
+        return true if opening?(char) || ideographic?(char)
+
+        cjk?(current[-1]) && !(closing?(current[-1]) && !ideographic_unit?(current))
+      end
+
+      # A unit that carries an ideographic character (as opposed to Latin text
+      # followed by a closing mark, such as "abc。").
+      def ideographic_unit?(text) = text.each_char.any? { |char| ideographic?(char) }
+    end
+  end
+end

data/lib/stationery/text/paragraph.rb

@@ -34,6 +34,14 @@ module Stationery
         [with_lines(@lines.first(count)), with_lines(@lines.drop(count))]
       end
 
+      # [first `count` lines, the rest]; nil for an empty side.
+      def split_at(count)
+        return [nil, self] if count <= 0
+        return [self, nil] if count >= @lines.size
+
+        [with_lines(@lines.first(count)), with_lines(@lines.drop(count))]
+      end
+
       # A paragraph that fits `max_height`: truncated to whole lines, shrunk
       # (never below 4pt) or left as is for :visible.
       def fit(max_height, overflow:)

data/lib/stationery/text/runs_builder.rb

@@ -46,6 +46,10 @@ module Stationery
       def size(value, text = nil, &) = styled({ size: value }, text, &)
       def font(family, text = nil, &) = styled({ family: family.to_s }, text, &)
       def link(url, text = nil, &) = styled({ link: url.to_s }, text, &)
+      # The current size multiplied: `scale(1.5) { … }` is one and a half times the text around it.
+      def scale(factor, text = nil, &) = styled({ size: @styles.last.size * factor }, text, &)
+      # Any style fields at once, also to switch a mark off: `with({ weight: :regular }) { … }`.
+      def with(overrides, text = nil, &) = styled(overrides, text, &)
 
       private