stationery 0.12.2 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a56459cfc65f70dab12835ced22ff09d88d5c7a66b8ea045ccb0776f75da27b6
-  data.tar.gz: 44889ebe589bed206a1b04940e6b24bad97f3be38f2b53179d8c98522c1ff7f0
+  metadata.gz: 20fc9e96d7c91ce004e7e9a25cbd9a2ae9d38b169707358c37e0f2cf0e48c711
+  data.tar.gz: c3a382d8a5e44aec3432f5e16576764ca87fe8225f2e5046b866480192ab36bc
 SHA512:
-  metadata.gz: 7c2af80a6c317cff9cea03b5259c63d6a2bfa74730371713b490713fc0e8cb311d5b644d4a239ff49843f312cbdb20504dc9f363195df1af2784948f5af0250a
-  data.tar.gz: 2591078b7e474565a8f35338dac311800f5c175576428756ba111fef71dc1e68e4b971efe86e7c64b6458c0b162087b1b32e75da6f4d703df735aee7dc45bafc
+  metadata.gz: 68a186240528e3394151ae13f71f56c0b6ab6c37f5ebbd82e15f3f2d2ff4e8ae7aecd7bf6c3262de2303778273b474e17c12e885ec65262a63b359503e4d2065
+  data.tar.gz: de90f228f712439d0ef21933892f58f29954099892c4a9178da93a4c81d16811ff449ec3f755c82a8f2f10305ea07d6eb8bd60f6c9bd668a1071324d77d80b05

data/CHANGELOG.md

@@ -1,12 +1,14 @@
 # Changelog
 
-## Unreleased
+## 0.13.0
 
+- Text fields and selects take `font_size: :fit` (#218): the size `font_size: :auto` draws (one line, a `comb:` field's cells or a `multiline:` value, within `min_font_size:` and `max_font_size:`), written in `/DA` as that number instead of `0`, so a viewer that redraws the field keeps the size; Firefox's editable input, which showed `:auto` at 9 px, now shows the number, capped at the field's height ÷ 1.35 and set in the browser's own face. A longer value typed afterwards does not shrink, and an empty field is written at its largest size, so a field left empty to be filled in wants `:auto`. A field placed in several places writes its first widget's size. `Inspector#layout` and `stationery inspect` report the number. `text_field "price", value: "4 990 kr", font_size: :fit, max_font_size: 96, height: 110`. The price card example uses it. A field that does not is written as it was. `Forms::Field`, `Forms::Appearance`.
 - Text fields and selects take `align:`, `color:` and `font_size: :auto` (#216): `align:` (`:left`, `:center`, `:right`) is written as `/Q`, `color:` (any colour the gem takes, black by default) as the colour operator of `/DA`, and `font_size: :auto` as `0 Tf`, within `min_font_size:` (4 by default) and `max_font_size:` (the field's height by default). The gem's own appearance aligns, colours and sizes the value the same way, so a field looks the same before and after a viewer redraws it: one line at the largest tenth of a point that fits the field's height and width, a `comb:` field's widest character in its cell, a `multiline:` value wrapped to the width and fitted to the height. `comb:` ignores `align:`. `text_field "price", value: "4 990 kr", align: :center, color: "#DC2626", font_size: :auto, height: 110`. A field that uses none of them is written as it was. Under `monochrome` a `color:` is checked like any other colour (`Warnings::NotMonochrome`, or black with `snap: true`); `Inspector#layout` and `stationery inspect` report a text field's or choice's `align:`, `font_size:` and `color:`. A price card example (`examples/price_card.rb`). `Forms::Field`, `Forms::Appearance`, `Forms::AutoSize`, `Testing::Layout`. **Behaviour change:** under PDF/A, a CMYK colour in a form field's appearance or `/DA` is reported as `Warnings::ConformanceIssue` (`CMYK colour in form field "price"`), its `border:` and `background:` included, which were not checked before.
 - The skill (`stationery skill install`) and the README it is written from are corrected (#209): the `max_pages` example renders before it reads `warnings`; a preview reads `params.fetch("id") { … }`, so its default is not looked up when `id` is given; the streamed-table example preloads what its rows read; the invoice recipe computes VAT with `Rational`, not Float, and says when a document may derive its totals; the report recipe escapes the chart labels it writes into SVG (`ERB::Util.html_escape`); the form recipe gives its fields a `tooltip:` and says a field without one is announced by its field name; the label recipe sizes a native QR code by the printer's dpi (a module of at most 720 / dpi points) and says what a barcode left in the picture loses. Statements that overstated are qualified: `encrypt` under a conformance level raises `ArgumentError`, not `ConformanceError`; `NeedAppearances` is left out under a conformance level or a signature; what the untrusted-input guarantees cover; and what a B-T timestamp proves once the certificate has expired. Run `stationery skill install` again to update an installed copy.
 - A tagged render is written with object streams (#206): its structure elements, and every other object that is not a stream, are packed 200 to a deflated `/Type /ObjStm`, with a cross-reference stream in place of the table and trailer (ISO 32000-1, 7.5.7 and 7.5.8). A table of 300 rows, 8 pages, is 115 KB tagged where it was 501 KB, 36 objects where it was 4,544; the tagged examples are 9 to 65% smaller. It is on by default for a render that is tagged (`tagged`, `to_pdf(tagged: true)`, `conformance :pdf_ua1`), and `object_streams false` at class level or `to_pdf(object_streams: false)` writes the classic table for a reader that cannot read object streams; `to_pdf(object_streams: true)` packs an untagged render too. Streams, the `/Encrypt` dictionary and a signature's dictionary stay out, so an encrypted, a signed and an incremental render are packed too, and PDF/A-2b, PDF/A-3b and PDF/UA-1 pass veraPDF packed. `to_png` and `to_zpl` refuse `object_streams:` as a PDF option. `Document#page_count` is how many pages the last render laid out, which `stationery render` now reports. In `PDF::Writer` (`object_streams:`, `add_unpacked`) and `PDF::ObjectStreams`.
 - `stationery verify` checks PDFs in the engines viewers are built on (#210): qpdf (the file's structure), Poppler (Evince, Okular), MuPDF, PDFium (Chrome, Edge), pdf.js (Firefox) and PDFKit (Preview, Safari). Each engine reads the file and what it reads is held against what pdf-reader reads of it: the page count, each page's text lines (found, not compared: NFKC, no whitespace, no soft hyphens, a list item's marker may be read apart, as a column of markers), that a page with text or an image paints something, links and their targets, outline titles, form fields with their values and appearances, attachments, signatures (and `pdfsig`'s verdict), a tagged file's structure tree, and every font embedded with a ToUnicode map. Any error or warning an engine gives fails the check, but for the three messages `Stationery::Verify::Allowlist` names with why each is the check's environment and not the file. `stationery verify invoice.pdf report.rb --engines qpdf,pdfjs --password P --json` renders a Ruby file first, as `inspect` does, runs every engine installed without `--engines`, and exits 0, 1 or 2 (usage); it prints one line per file and engine, the problems under it, and the engines not installed with the line that installs each. The engines are tools you install (`brew install qpdf poppler mupdf`, `pip install pypdfium2`, `npm i pdfjs-dist`; PDFKit on macOS), or run in the image `ghcr.io/zoolutions/stationery-verify`, published with each release, which has every engine but PDFKit: `docker run --rm -v "$PWD:/data:ro" ghcr.io/zoolutions/stationery-verify /data/invoice.pdf`. The gem gains no dependency: `stationery verify` needs `pdf-reader`, as `inspect` does, and `require "stationery"` does not load it, so a render allocates and writes what it did. `bundle exec rake verify:readers` renders every example, the conformance renders, an encrypted invoice, a packed invoice and an unpacked tagged report to `tmp/readers/` and checks them; CI runs it through the image on Linux and with qpdf, Poppler, MuPDF and PDFKit on macOS. `Testing::Inspector.new(subject, password:)` opens an encrypted file. `Stationery::Verify`, `Stationery::CLI::Verify`.
-- **Behaviour changes:** a tagged render is packed: its catalog, pages, annotations and structure elements are inside deflated object streams, so a test or tool that searches the file's bytes for them (`/StructParent`, `/Type /Page`) finds nothing (`document.page_count` has the pages), and the file ends in a cross-reference stream, not `xref` and `trailer`. A reader of PDF 1.4 and earlier cannot open it; `object_streams: false` writes it as 0.12.0 did, byte for byte. A tagged render streamed to a block is a few bytes longer than the String, as each flush closes an object stream. Untagged documents are byte for byte what they were in 0.12.0.
+- Renders are safe from many threads at once, from the fibers of one Async reactor, and inside a non-main Ractor on Ruby 4.0 (#222). What renders share is kept once per Ractor, each cache behind a lock of its own (`Stationery::Store`, `Stationery::LRU`, `Stationery::Memo`): parsed fonts, decoded images, colours parsed from Strings, hyphenation patterns, the paddings of table cells and the Reed–Solomon divisors of barcodes; no lock is kept in a constant or a class instance variable any more. A parsed font reads its kerning, ligatures and CFF table with the rest of the parse, so it never changes once built and can be made shareable and handed to a Ractor as it is; a decoded image builds its resamples and JPEG scales under a lock of its own. Every constant of the gem is deep-frozen. Boot ends with `Stationery.finalize!`, which the Railtie runs once the app has initialized (a Rails-less app calls it once its setup is done): it freezes `Stationery.font_paths`, keeps the instrumenter in use and finalizes every document class loaded by then, with their subclasses. `Document.finalize!` freezes a class's settings and makes them Ractor-shareable as far as what they hold lets them be, so the class renders inside any Ractor when all of them are; it never raises: a block that uses an unshareable local from around it, a `shaper` or a `sign` key that is not shareable, is kept as it is and the class renders on the main Ractor only, as before (`Ractor.shareable?(InvoicePdf.config)` says whether its settings are; the instrumenter in use must be shareable too). A String the app gave is copied, not frozen in place, and an object the gem did not build is never frozen (`Stationery.settled`). A font family is frozen as it is built. A document class's settings are built when it is defined, not when they are first read. conformance-kit holds the gem to it: its thread-safety cops in RuboCop, a render of text, shapes, a JPEG, a table, a QR code and a footer inside a Ractor compared byte for byte with the main Ractor's, the thread and fiber examples over the same render, and an audit of every constant and class instance variable (`bundle exec conformance-kit check`). Documents render the same bytes as before. README: "Threads, fibers and Ractors". `Stationery.finalize!`, `Stationery::Document.finalize!`, `Stationery::Store`.
+- **Behaviour changes:** a tagged render is packed: its catalog, pages, annotations and structure elements are inside deflated object streams, so a test or tool that searches the file's bytes for them (`/StructParent`, `/Type /Page`) finds nothing (`document.page_count` has the pages), and the file ends in a cross-reference stream, not `xref` and `trailer`. A reader of PDF 1.4 and earlier cannot open it; `object_streams: false` writes it as 0.12.0 did, byte for byte. A tagged render streamed to a block is a few bytes longer than the String, as each flush closes an object stream. Untagged documents are byte for byte what they were in 0.12.0. In a Rails app, `Stationery.font_paths` is frozen once the app has initialized (the Railtie runs `Stationery.finalize!`), so a path appended later, in an `after_initialize` of the app's own, raises `FrozenError`. So does a call that changes the settings of a document class the app had loaded by then: with `config.eager_load` (production, and the CI test runs of a Rails 7.1+ app) that is every class under `app/`, without it (development) only those its boot touched, so a class reconfigured after boot fails in production and not in development. `Stationery::Fonts::Family` objects are frozen. The gem's constants are deep-frozen (`Stationery::Page::SIZES`, `Stationery::Text::Markup::STYLES`, …), and `Stationery::Hyphenation::LOCK`, `Stationery::Preview::REGISTRY_LOCK` and `Stationery::Layout::Table::Cell::BOXES` are gone. Until `Stationery.finalize!` keeps it, the default instrumenter is looked up on every render, so `ActiveSupport::Notifications` loaded after the gem is used. A document class copies its parent's settings when it is defined, not when they are first read, so a setting a parent class gains after a subclass is defined (a reopened `ApplicationPdf`) no longer reaches that subclass.
 
 ## 0.12.0 (2026-09-29)
 

data/README.md

@@ -139,7 +139,7 @@ ls "$(bundle show stationery)/examples"      # or: gem contents stationery
 | `keep_with_next: true \| points` | On `text`, `box` or `group`: never end a page with this node; with a number, keep at least that many points of what follows with it. |
 | `text_style(**style) { }` | Default text style for a block. |
 | `canvas(height:) { \|canvas, rect\| }` | Draw directly: rectangles, rounded rectangles, circles, lines, Bézier paths, clipping, images, links; `rotate(degrees, around:) { }` and `transform([a, b, c, d, e, f]) { }` blocks. |
-| `text_field(name, value:, width:, height:, multiline:, max_length:, comb:, read_only:, required:, font_size:, min_font_size:, max_font_size:, align:, color:, border:, background:, radius:, tooltip:, at:)` | An interactive text input (AcroForm). `width:` is `:full` or points; `font_size:` is points or `:auto`; `align:` is `:left`, `:center` or `:right`; dotted names (`"address.city"`) group fields. See [Forms](#forms). |
+| `text_field(name, value:, width:, height:, multiline:, max_length:, comb:, read_only:, required:, font_size:, min_font_size:, max_font_size:, align:, color:, border:, background:, radius:, tooltip:, at:)` | An interactive text input (AcroForm). `width:` is `:full` or points; `font_size:` is points, `:auto` or `:fit`; `align:` is `:left`, `:center` or `:right`; dotted names (`"address.city"`) group fields. See [Forms](#forms). |
 | `checkbox(name, checked:, size:, label:, at:)` | An interactive check box, with an optional label drawn to its right. |
 | `radio(name, value, checked:, size:, label:, at:)` | One choice of a radio group: radios sharing `name` form one field whose value is the checked `value`. |
 | `select(name, options:, value:, width:, height:, editable:, font_size:, min_font_size:, max_font_size:, align:, color:, at:)` | A drop-down (combo box); `editable: true` also accepts typed values. |
@@ -418,8 +418,12 @@ signature_field "signature", label: "Signature of the applicant"
   `font_size: :auto` writes `0 Tf` and the appearance draws the largest size, in tenths of a point,
   at which one line fits the field's height and width (a `comb:` field's cells; a `multiline:`
   field wrapped to its width and height), within `min_font_size:` (4 by default) and
-  `max_font_size:` (the height by default). A `comb:` field ignores `align:`, its cells place each
-  character. Under `monochrome`, `color:` is checked like any other colour; under PDF/A a CMYK one
+  `max_font_size:` (the height by default). `font_size: :fit` sizes the value the same way and writes
+  the number it chose in `/DA`, so every viewer reads a size, where `0 Tf` showed 9 px in Firefox's
+  editable input (which still caps a size at the field's height ÷ 1.35 and sets it in its own face).
+  A longer value typed afterwards does not shrink, and an empty field is sized to its bound, so a
+  field left empty to be filled in wants `:auto`. `min_font_size:` and `max_font_size:` go with
+  either. A `comb:` field ignores `align:`, its cells place each character. Under `monochrome`, `color:` is checked like any other colour; under PDF/A a CMYK one
   is reported. A field that uses none of them is written as it was.
 - A radio group's value is its checked choice's `value` (`Off` when none is checked); a select box
   lists its `options:` and draws the chosen `value`; a signature field is left unsigned for the
@@ -1518,7 +1522,11 @@ font_family "Noto Sans"                                                # found i
 font_family "Noto Sans", **Stationery::Fonts.paths(:noto_sans, dir: "vendor/fonts") # outside Rails
 ```
 
-or append it yourself: `Stationery.font_paths << File.expand_path("vendor/fonts")`.
+or append it yourself: `Stationery.font_paths << File.expand_path("vendor/fonts")`,
+before `Stationery.finalize!` freezes the list (see
+[Threads, fibers and Ractors](#threads-fibers-and-ractors); the Railtie runs it
+once the app has initialized, so add paths in `config/application.rb` or an
+initializer).
 From Ruby: `Stationery::Fonts.install(:noto_sans, into: "vendor/fonts")`
 returns `{ regular: path, bold: path, … }`; `Stationery::Fonts.catalog` lists
 the packs. `rake fonts:verify` (development only) downloads every pack and
@@ -1882,7 +1890,7 @@ own; lines read top to bottom, then left to right. An image is `{ x:, y:, width:
 [w, h] }` in the order drawn (the rectangle it fills, before any clip); a link has its `uri:`, or the
 `page:` and `top:` it goes to; a field has its full `name:`, `type:` (`:text`, `:choice`,
 `:checkbox`, `:radio`, `:button`, `:signature`), `value:`, for a button the `state:` that turns
-it on, and for a text field or a choice the `align:`, `font_size:` (`:auto` for `0 Tf`) and `color:`
+it on, and for a text field or a choice the `align:`, `font_size:` (`:auto` for `0 Tf`, the number for `:fit`) and `color:`
 (`"#RRGGBB"`) its value is drawn in. `outline` is the bookmarks as `{ title:, page:, top:, children: }`. `metadata` leaves out the
 dates, which change with every render, so two renders of one document have the same layout.
 `warnings` are the render's messages when the subject is a document.
@@ -1933,6 +1941,66 @@ events instead (`Stationery.instrumenter = MyInstrumenter.new`), and
 spans inside a document. When you hit a slow render, a trace with these
 events attached is the most useful thing to put in an issue.
 
+## Threads, fibers and Ractors
+
+A render keeps its state to itself: a document, its fonts' glyph usage and its
+pages belong to the render. What renders share is cached once per Ractor,
+behind the cache's own lock: parsed fonts (16 files), decoded images (16),
+colours parsed from Strings, hyphenation patterns. So any number of threads,
+or fibers of one Async reactor, may render at once, and a render inside a
+non-main Ractor (Ruby 4.0) fills caches of its own. A parsed font never
+changes once it is read, so it can be made shareable and handed to a Ractor
+as it is.
+
+A Ractor can read only what is shareable, so boot ends with
+`Stationery.finalize!`, which freezes what renders read. The Railtie runs it
+once the app has initialized; a Rails-less app calls it once its setup is
+done:
+
+```ruby
+class InvoicePdf < Stationery::Document
+  page size: :a4
+  footer { |page| text "#{page.number} / #{page.count}" }
+
+  def initialize(lines) = @lines = lines
+  def view_template = @lines.each { |line| text line }
+end
+Stationery.finalize! # outside Rails: font_paths and every document class loaded so far
+
+pdfs = Array.new(4) { |i| Ractor.new(["Invoice #{i}"]) { |lines| InvoicePdf.new(lines).to_pdf } }.map(&:value)
+```
+
+- `Stationery.finalize!` freezes `Stationery.font_paths`, keeps the
+  instrumenter in use and finalizes every document class loaded by then,
+  with their subclasses (`Document.finalize!`). In a Rails app with
+  `config.eager_load` (production, and the CI test runs of a Rails 7.1+ app)
+  that is every class under `app/`. A class loaded later (autoloaded in
+  development) or defined after boot is not finalized: it renders on the
+  main Ractor as before, and `InvoicePdf.finalize!` finalizes it.
+- A finalized class's settings cannot change (a `FrozenError`); a subclass
+  has its own. They are made Ractor-shareable as far as what they hold lets
+  them be, and nothing raises: a block of a page template, header or footer
+  that uses an unshareable local from around it, a `shaper` or a `sign` key
+  that is not shareable, is kept as it is, so the class renders on the main
+  Ractor as before and not inside another one.
+  `Ractor.shareable?(InvoicePdf.config)` says whether its settings are
+  shareable; a render inside a Ractor also needs a shareable instrumenter
+  (below), and the class's own methods (`view_template`, the methods its
+  blocks call) may reach only what a Ractor can.
+  A String the app gave is copied, not frozen in place, and an object the gem
+  did not build is never frozen.
+- An instrumenter for renders inside a Ractor must be shareable: a module
+  (`ActiveSupport::Notifications`) or a frozen object. Another one is kept,
+  for the main Ractor.
+- What a Ractor is handed (`Ractor.new(lines)`) is copied unless it is
+  shareable.
+
+The gem is held to this by [conformance-kit](https://github.com/zoolutions/conformance-kit):
+`bundle exec conformance-kit check` (on Ruby 4.0) renders a document of
+text, shapes, a JPEG, a table, a QR code and a footer inside a Ractor and
+compares its bytes with the main Ractor's, and audits every constant and
+class instance variable of the gem for state a Ractor cannot read.
+
 ## Performance
 
 `bundle exec rake bench` renders three documents with Stationery, with Prawn 2.5 +
@@ -1978,7 +2046,7 @@ without its gem.
 A lossless WebP is decoded in Ruby when it is first loaded, which a JPEG or an opaque PNG
 (both passed through) never is: a 1000 × 1000 px image takes 0.2 to 0.4 s on the machine
 above, by what is in it, and the image cache keeps it for the renders that follow. A JPEG is
-decoded only for `to_png` or a monochrome render, once per process and scale: a 1000 × 1000
+decoded only for `to_png` or a monochrome render, once per Ractor and scale: a 1000 × 1000
 px photo in 0.25 s, a 12-megapixel phone photo in 2.8 s at full size and 0.7 s at the quarter
 size a label or a preview needs (progressive: 3.4 s and 1.4 s; about four times as long
 without YJIT).

data/examples/price_card.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 # A shop-window price card a person fills in on screen and prints: the
-# product's name centred and shrunk to fit its line (`font_size: :auto`),
-# the price large, centred and red, the price per unit right-aligned in grey
-# and a select of units. The fields have no border and no background, so the
-# printed card shows the values alone; a viewer that redraws a field after
-# an edit keeps its alignment, colour and auto-size (/Q and /DA). Run it to
-# write examples/price_card.pdf:
+# product's name centred and shrunk to fit its line, the price large,
+# centred and red, the price per unit right-aligned in grey and a select of
+# units. The name and price are fitted by the gem and the size it chose is
+# written to the file (`font_size: :fit`), so every viewer shows them at
+# that size. The fields have no border and no background, so the printed
+# card shows the values alone; a viewer that redraws a field after an edit
+# keeps its alignment, colour and size (/Q and /DA). Run it to write
+# examples/price_card.pdf:
 #
 #   ruby -Ilib examples/price_card.rb
 #   ruby -Ilib exe/stationery render examples/price_card.rb
@@ -51,14 +53,14 @@ class ExamplePriceCard < Stationery::Document
     spacer 10
     label "Product"
     text_style(weight: :bold) do
-      text_field "product", value: @product, height: 44, font_size: :auto, max_font_size: 32, align: :center,
+      text_field "product", value: @product, height: 44, font_size: :fit, max_font_size: 32, align: :center,
                             tooltip: "Product", **BARE
     end
     rule height: 0.5, color: HAIRLINE
     spacer 10
     label "Price"
     text_style(weight: :bold) do
-      text_field "price", value: @price, height: 150, font_size: :auto, max_font_size: 120, align: :center,
+      text_field "price", value: @price, height: 150, font_size: :fit, max_font_size: 120, align: :center,
                           color: SALE, tooltip: "Price", **BARE
     end
     spacer 6

data/lib/stationery/barcode/data_matrix.rb

@@ -12,7 +12,7 @@ module Stationery
     class DataMatrix
       # Symbol size => [data codewords, error correction codewords, data
       # regions across, modules across a region, interleaved blocks].
-      SIZES = {
+      SIZES = Stationery.shareable(
         10 => [3, 5, 1, 8, 1], 12 => [5, 7, 1, 10, 1], 14 => [8, 10, 1, 12, 1], 16 => [12, 12, 1, 14, 1],
         18 => [18, 14, 1, 16, 1], 20 => [22, 18, 1, 18, 1], 22 => [30, 20, 1, 20, 1], 24 => [36, 24, 1, 22, 1],
         26 => [44, 28, 1, 24, 1], 32 => [62, 36, 2, 14, 1], 36 => [86, 42, 2, 16, 1], 40 => [114, 48, 2, 18, 1],
@@ -20,7 +20,7 @@ module Stationery
         72 => [368, 144, 4, 16, 4], 80 => [456, 192, 4, 18, 4], 88 => [576, 224, 4, 20, 4],
         96 => [696, 272, 4, 22, 4], 104 => [816, 336, 4, 24, 6], 120 => [1050, 408, 6, 18, 6],
         132 => [1304, 496, 6, 20, 8], 144 => [1558, 620, 6, 22, 10]
-      }.freeze
+      )
       PAD = 129
       UPPER_SHIFT = 235
       QUIET = 1

data/lib/stationery/barcode/data_matrix_placement.rb

@@ -9,7 +9,7 @@ module Stationery
       # where a stroke meets the edge, and the fixed pattern in the corner
       # left over.
       class Placement
-        UTAH = [[-2, -2], [-2, -1], [-1, -2], [-1, -1], [-1, 0], [0, -2], [0, -1], [0, 0]].freeze
+        UTAH = Stationery.shareable([[-2, -2], [-2, -1], [-1, -2], [-1, -1], [-1, 0], [0, -2], [0, -1], [0, 0]])
 
         attr_reader :grid
 

data/lib/stationery/barcode/ean13.rb

@@ -9,8 +9,8 @@ module Stationery
     # them with `text` when they are wanted).
     class EAN13
       L = %w[0001101 0011001 0010011 0111101 0100011 0110001 0101111 0111011 0110111 0001011].freeze
-      R = L.map { |code| code.tr("01", "10") }.freeze
-      G = R.map(&:reverse).freeze
+      R = Stationery.shareable(L.map { |code| code.tr("01", "10") })
+      G = Stationery.shareable(R.map(&:reverse))
       # Which of L and G the six digits on the left use, by the first digit.
       PARITY = %w[LLLLLL LLGLGG LLGGLG LLGGGL LGLLGG LGGLLG LGGGLL LGLGLG LGLGGL LGGLGL].freeze
       QUIET = 11

data/lib/stationery/barcode/qr.rb

@@ -11,7 +11,7 @@ module Stationery
     class QR
       LEVELS = %i[l m q h].freeze
       # Error correction codewords a block, and blocks, by level and version.
-      ECC_PER_BLOCK = {
+      ECC_PER_BLOCK = Stationery.shareable(
         l: [7, 10, 15, 20, 26, 18, 20, 24, 30, 18, 20, 24, 26, 30, 22, 24, 28, 30, 28, 28, 28, 28, 30, 30, 26, 28, 30,
             30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
         m: [10, 16, 26, 18, 24, 16, 18, 22, 22, 26, 30, 22, 22, 24, 24, 28, 28, 26, 26, 26, 26, 28, 28, 28, 28, 28,
@@ -20,8 +20,8 @@ module Stationery
             30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
         h: [17, 28, 22, 16, 22, 28, 26, 26, 24, 28, 24, 28, 22, 24, 24, 30, 28, 28, 26, 28, 30, 24, 30, 30, 30, 30,
             30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30]
-      }.freeze
-      BLOCKS = {
+      )
+      BLOCKS = Stationery.shareable(
         l: [1, 1, 1, 1, 1, 2, 2, 2, 2, 4, 4, 4, 4, 4, 6, 6, 6, 6, 7, 8, 8, 9, 9, 10, 12, 12, 12, 13, 14, 15, 16, 17, 18,
             19, 19, 20, 21, 22, 24, 25],
         m: [1, 1, 1, 2, 2, 4, 4, 4, 5, 5, 5, 8, 9, 9, 10, 10, 11, 13, 14, 16, 17, 17, 18, 20, 21, 23, 25, 26, 28, 29,
@@ -30,7 +30,7 @@ module Stationery
             40, 43, 45, 48, 51, 53, 56, 59, 62, 65, 68],
         h: [1, 1, 2, 4, 4, 4, 5, 6, 8, 8, 11, 11, 16, 16, 18, 16, 19, 21, 25, 25, 25, 34, 30, 32, 35, 37, 40, 42, 45,
             48, 51, 54, 57, 60, 63, 66, 70, 74, 77, 81]
-      }.freeze
+      )
       QUIET = 4
       PADS = [0xEC, 0x11].freeze
       # An ECI segment naming UTF-8 (assignment 26), before text that is not ASCII.

data/lib/stationery/barcode/qr_matrix.rb

@@ -18,7 +18,7 @@ module Stationery
           ->(x, y) { (((x * y) % 2) + ((x * y) % 3)).zero? },
           ->(x, y) { (((x * y) % 2) + ((x * y) % 3)).even? },
           ->(x, y) { (((x + y) % 2) + ((x * y) % 3)).even? }
-        ].freeze
+        ].map { Stationery.shareable(it) }.freeze
 
         attr_reader :size, :modules, :mask
 

data/lib/stationery/barcode/reed_solomon.rb

@@ -19,15 +19,16 @@ module Stationery
         end
         (255...512).each { |power| @exp[power] = @exp[power - 255] }
         @first_root = first_root
-        @divisors = {}
+        @divisors = :"stationery_reed_solomon_#{polynomial}_#{first_root}"
       end
 
       def multiply(a, b) = a.zero? || b.zero? ? 0 : @exp[@log[a] + @log[b]]
 
       # The generator polynomial of `degree`, highest power first and its
-      # leading 1 left out.
+      # leading 1 left out; made once per degree and Ractor (see Store), so
+      # the coder itself never changes and every Ractor can share it.
       def divisor(degree)
-        @divisors[degree] ||= begin
+        Store.fetch(@divisors) { Memo.new }.fetch(degree) do
           result = Array.new(degree, 0)
           result[-1] = 1
           root = @exp[@first_root]
@@ -38,7 +39,7 @@ module Stationery
             end
             root = multiply(root, 2)
           end
-          result
+          result.freeze
         end
       end
 
@@ -54,8 +55,8 @@ module Stationery
         result
       end
 
-      QR = new(0x11D, 0)
-      DATA_MATRIX = new(0x12D, 1)
+      QR = Stationery.shareable(new(0x11D, 0))
+      DATA_MATRIX = Stationery.shareable(new(0x12D, 1))
     end
   end
 end

data/lib/stationery/canvas/debug.rb

@@ -11,7 +11,7 @@ module Stationery
         flow: "#9CA3AF", positioned: "#DB2777", image: "#0D9488", page: "#06B6D4", region: "#0EA5E9",
         field: "#7C3AED", stack: "#F59E0B"
       }.freeze
-      DEBUG_DASHES = { padding: [2, 2], cell_padding: [2, 2], flow: [1, 2] }.freeze
+      DEBUG_DASHES = Stationery.shareable({ padding: [2, 2], cell_padding: [2, 2], flow: [1, 2] })
 
       def debug? = @debug == true || (@debug.is_a?(Array) && @debug.any?)
 

data/lib/stationery/canvas/interface.rb

@@ -29,7 +29,7 @@ module Stationery
       include Debug
 
       # The callable #tag_runs hands its block where nothing is marked.
-      PASS = ->(_element = nil, &block) { block.call }
+      PASS = Stationery.shareable(->(_element = nil, &block) { block.call })
 
       # The render's collector (nil on a bare canvas), for what a node
       # notices only while painting, such as an oversized image.

data/lib/stationery/canvas/marking.rb

@@ -91,7 +91,7 @@ module Stationery
         end
       end
 
-      PASS = ->(_element = nil, &block) { block.call }
+      PASS = Stationery.shareable(->(_element = nil, &block) { block.call })
 
       private
 

data/lib/stationery/cli.rb

@@ -18,11 +18,16 @@ module Stationery
     # Raised by a command to fail with a message and exit code 1.
     class Error < StandardError; end
 
+    # Filled as the commands' files load, on the main Ractor; frozen, so a
+    # registration publishes a new Hash.
+    @commands = {}.freeze
+
     class << self
-      def commands = @commands ||= {}
+      attr_reader :commands
 
       def register(name, command)
-        commands[name.to_s] = command
+        # rubocop:disable-next ThreadSafety/ClassInstanceVariable -- written while the commands' files load, on the main Ractor; always a frozen Hash
+        @commands = @commands.merge(name.to_s => command).freeze
       end
 
       def start(argv, out: $stdout, err: $stderr) = new(out:, err:).run(argv.dup)

data/lib/stationery/color.rb

@@ -8,33 +8,23 @@ module Stationery
     # The colours parsed from Strings that are remembered, by their String:
     # every fill, stroke and run of text names its colour ("#000000"), and
     # parsing it again made eleven objects. Past this many the memo starts
-    # over, as the fonts' memos do.
+    # over, as the fonts' memos do. Each Ractor keeps its own (see Store).
     MEMO = 256
 
-    @parsed = {}
-    @lock = Mutex.new
-
     attr_reader :space, :components, :fill, :stroke
 
     def self.parse(value)
       case value
       when Color then value
-      when String then @parsed[value] || remember(value)
+      when String then memo.fetch(value) { from_hex(value) }
       when Array then from_array(value)
       else invalid(value)
       end
     end
 
-    # A Hash keeps a frozen copy of a String key, so a String changed after
-    # it was parsed does not change what the memo holds.
-    def self.remember(value)
-      color = from_hex(value)
-      @lock.synchronize do
-        @parsed.clear if @parsed.size >= MEMO
-        @parsed[value] ||= color
-      end
-    end
-    private_class_method :remember
+    # This Ractor's colours parsed from Strings (a Memo).
+    def self.memo = Store.fetch(:stationery_colors) { Memo.new(limit: MEMO) }
+    private_class_method :memo
 
     def self.from_hex(value)
       hex = value[HEX, 1] || invalid(value)

data/lib/stationery/css/stylesheet.rb

@@ -47,7 +47,7 @@ module Stationery
         @unsupported = unsupported
       end
 
-      EMPTY = new([], []).freeze
+      EMPTY = Stationery.shareable(new([], []))
 
       def empty? = @rules.empty?
 

data/lib/stationery/document.rb

@@ -18,15 +18,39 @@ module Stationery
     INFO_KEYS = { title: :Title, author: :Author, subject: :Subject, keywords: :Keywords, creator: :Creator,
                   producer: :Producer }.freeze
 
+    # The settings every document starts from, shareable as they are.
+    @config = Stationery.shareable(
+      { page: { size: :letter, margin: 36 }, families: {}, fallbacks: [], text: {}, metadata: {},
+        templates: [], regions: [], strict: false, tagged: false, incremental: false, images: {},
+        attachments: [], shaping: {}, print: {}, missing_glyphs: :raise }
+    )
+
     class << self
-      def config
-        @config ||= if superclass.respond_to?(:config)
-                      superclass.config.transform_values(&:dup)
-                    else
-                      { page: { size: :letter, margin: 36 }, families: {}, fallbacks: [], text: {}, metadata: {},
-                        templates: [], regions: [], strict: false, tagged: false, incremental: false, images: {},
-                        attachments: [], shaping: {}, print: {}, missing_glyphs: :raise }
-                    end
+      # The class's settings, built when the class is defined: each of its
+      # parent's copied, so a subclass's never reaches the parent, then
+      # changed by the calls of its class body, on the main Ractor. A render
+      # only reads them, and a non-main Ractor can once finalize! has run.
+      attr_reader :config
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@config, config.transform_values(&:dup))
+      end
+
+      # Ends the class's boot: its settings are frozen, and made
+      # Ractor-shareable as far as they can be (Stationery.settled), so the
+      # class renders inside any Ractor when all of them are. A block of its
+      # page templates, headers or footers that uses an unshareable local
+      # from around it, or a shaper that is not shareable itself, is kept as
+      # it is: the class then renders on the main Ractor only, as before.
+      # Never raises. Stationery.finalize! runs it on every class loaded by
+      # then; run it yourself on a class loaded later. After it the settings
+      # cannot change (FrozenError), and a subclass has its own. Answers the
+      # class; running it again changes nothing.
+      def finalize!
+        # rubocop:disable-next ThreadSafety/ClassInstanceVariable -- written at boot on the main Ractor, before any render
+        @config = Stationery.settled(config) unless config.frozen?
+        self
       end
 
       # `size:` is a name of Page::SIZES, [width, height] in points or with

data/lib/stationery/elements/forms.rb

@@ -9,8 +9,8 @@ module Stationery
   module Elements
     # A text input. `width:` is :full or points; `multiline:`, `max_length:`,
     # `comb:` (a cell count, or true with max_length:), `read_only:`,
-    # `required:`, `font_size:` (points, or :auto with `min_font_size:` and
-    # `max_font_size:`), `align:` (:left, :center, :right), `color:`,
+    # `required:`, `font_size:` (points, or :auto or :fit with `min_font_size:`
+    # and `max_font_size:`), `align:` (:left, :center, :right), `color:`,
     # `border:`, `background:` and `radius:`.
     def text_field(name, value: "", width: :full, height: 22, at: nil, **)
       field_node(Forms::Field.new(:text, name, value: value.to_s, typeface: field_typeface, **), width:, height:, at:)

data/lib/stationery/examples.rb

@@ -5,7 +5,7 @@ module Stationery
   # each is and what each shows. `stationery examples` lists them and the
   # skill (see Skill) names them.
   module Examples
-    DIR = File.expand_path("../../examples", __dir__)
+    DIR = File.expand_path("../../examples", __dir__).freeze
 
     module_function
 

data/lib/stationery/fonts/bundled.rb

@@ -6,12 +6,12 @@ module Stationery
     # read the first time a document draws with it, so requiring the gem
     # never touches the files.
     module Bundled
-      DIR = File.expand_path("data", __dir__)
+      DIR = File.expand_path("data", __dir__).freeze
       DEFAULT = "Inter"
-      FAMILIES = {
+      FAMILIES = Stationery.shareable(
         "Inter" => { regular: "Inter-Regular.ttf", bold: "Inter-Bold.ttf",
                      italic: "Inter-Italic.ttf", bold_italic: "Inter-BoldItalic.ttf" }
-      }.freeze
+      )
 
       def self.names = FAMILIES.keys
 

data/lib/stationery/fonts/catalog.rb

@@ -15,8 +15,9 @@ module Stationery
                   "cee9892f9f0cc8fe882c9e9537ee6a89621d86ee7ceaf70b02e2b2b1c25c061a", "OFL.txt"].freeze
       LIBERATION = "https://github.com/liberationfonts/liberation-fonts/files/7261482/" \
                    "liberation-fonts-ttf-2.1.5.tar.gz#liberation-fonts-ttf-2.1.5"
-      LIBERATION_OFL = ["#{LIBERATION}/LICENSE",
-                        "93fed46019c38bbe566b479d22148e2e8a1e85ada614accb0211c37b2c61c19b", "OFL.txt"].freeze
+      LIBERATION_OFL = Stationery.shareable(["#{LIBERATION}/LICENSE",
+                                             "93fed46019c38bbe566b479d22148e2e8a1e85ada614accb0211c37b2c61c19b",
+                                             "OFL.txt"])
       LIBERATION_LICENSE = 'OFL-1.1, Reserved Font Name "Liberation"'
 
       # { style => [url, sha, "Family-Style.ttf"] } with the URL built from the file name.
@@ -90,7 +91,7 @@ module Stationery
                             italic: "605c01c711b44480a7508d349dfbf3264e81fa43d69e61cfa7d10b86e764c4d1",
                             bold_italic: "79451f3c09fe25116098853b7a2ca6e2436220ccc11af022979adbcf195be130")
         )
-      ].freeze
+      ].map { Stationery.shareable(it) }.freeze
 
       def self.fetch(key)
         PACKS.find { |pack| pack.key.to_s == key.to_s } ||

data/lib/stationery/fonts/cff.rb

@@ -15,7 +15,7 @@ module Stationery
       FD_ARRAY = 1236
       FD_SELECT = 1237
       SUBRS = 19
-      REAL_NIBBLES = [*"0".."9", ".", "E", "E-", nil, "-"].freeze
+      REAL_NIBBLES = Stationery.shareable([*"0".."9", ".", "E", "E-", nil, "-"])
 
       # An INDEX from `start` to `stop` (exclusive); items are [offset, length].
       Index = Data.define(:start, :items, :stop)
@@ -32,6 +32,8 @@ module Stationery
         @charstrings = index_at(@top.fetch(CHARSTRINGS).first)
         @num_glyphs = @charstrings.items.size
         @charset = self.class.parse_charset(@data, @top.fetch(CHARSET).first, @num_glyphs) if cid_keyed?
+        @fd_array = index_at(@top.fetch(FD_ARRAY).first) if cid_keyed?
+        @local_subrs = (cid_keyed? ? 0...@fd_array.items.size : [0]).to_h { |fd| [fd, private_subrs(font_dict(fd))] }
       end
 
       def inspect = "#<#{self.class} glyphs=#{@num_glyphs}#{" cid" if cid_keyed?}>"
@@ -61,11 +63,9 @@ module Stationery
 
       # The local Subrs INDEX a glyph's charstring calls, or nil: the Private
       # DICT's, or in a CID-keyed font that of the Font DICT FDSelect gives
-      # the glyph. Read once per Font DICT.
-      def local_subrs(gid)
-        fd = cid_keyed? ? fd_index(gid) : 0
-        (@local_subrs ||= {}).fetch(fd) { @local_subrs[fd] = private_subrs(font_dict(fd)) }
-      end
+      # the glyph. Every Font DICT's is read with the table, so a parse never
+      # changes once built.
+      def local_subrs(gid) = @local_subrs[cid_keyed? ? fd_index(gid) : 0]
 
       def item(index, number) = @data.byteslice(*index.items.fetch(number))
 
@@ -157,7 +157,6 @@ module Stationery
       def font_dict(number)
         return @top unless cid_keyed?
 
-        @fd_array ||= index_at(@top.fetch(FD_ARRAY).first)
         self.class.parse_dict(item(@fd_array, number))
       end
 

data/lib/stationery/fonts/cff_subset.rb

@@ -10,7 +10,7 @@ module Stationery
     # layout they describe. Charstrings are not interpreted: a deprecated
     # `seac` accent in a drawn glyph would lose its base and accent glyphs.
     module CffSubset
-      ENDCHAR = "\x0E".b
+      ENDCHAR = "\x0E".b.freeze
 
       module_function
 

data/lib/stationery/fonts/family.rb

@@ -28,8 +28,11 @@ module Stationery
         raise ArgumentError, "unknown font style #{unknown.join(", ")} (use #{STYLES.join(", ")})" if unknown.any?
         raise ArgumentError, "font family #{name} needs a regular face" unless paths[:regular]
 
-        @name = name.to_s
-        @paths = paths.transform_values(&:to_s).freeze
+        # Frozen copies, so a family is shareable as it is built and a
+        # document class holding it can be finalized for any Ractor.
+        @name = -name.to_s
+        @paths = paths.transform_values { -it.to_s }.freeze
+        freeze
       end
 
       def face(weight: :regular, style: :normal)