stationery 0.11.1 → 0.12.1

data/README.md

@@ -7,6 +7,29 @@ TrueType and OpenType fonts, JPEG, PNG and lossless WebP images and SVG drawings
 
 **Documentation: [stationery.zoolutions.llc](https://stationery.zoolutions.llc)**
 
+The same docs for an agent: over MCP (`search_docs`, `get_page`, `list_pages`), as
+[`/llms.txt`](https://stationery.zoolutions.llc/llms.txt) and
+[`/llms-full.txt`](https://stationery.zoolutions.llc/llms-full.txt), and every page
+as Markdown at its URL with `.md`. In Claude Code:
+
+```sh
+claude mcp add --transport http stationery https://stationery.zoolutions.llc/mcp
+```
+
+Any other MCP client takes the same URL, `https://stationery.zoolutions.llc/mcp`,
+as a remote server over HTTP: no key, read-only.
+
+A skill for coding agents ships with the gem: how a document is built, the rules that surprise,
+how to look at a render before calling it done, conformance, labels and a recipe per thing people
+ask for, written from this README for the version installed:
+
+```sh
+stationery skill install                  # ~/.claude/skills/stationery, and Codex's and ~/.agents' when they are there
+stationery skill install --project        # the project's .claude/skills/stationery, to commit with the app
+stationery skill status                   # current, outdated or missing, by the gem's version
+stationery skill print > stationery.md    # one file, for an agent that takes one
+```
+
 - **No runtime dependencies.** Standard library only.
 - **No native extensions and no other processes.** No Prawn, no headless
   Chrome, nothing to leak or kill.
@@ -70,9 +93,26 @@ InvoicePdf.new(invoice).to_pdf          # => "%PDF-1.7…" (binary String)
 InvoicePdf.new(invoice).to_pdf("a.pdf") # also writes a path or an IO
 ```
 
-`examples/` has a complete, runnable invoice, annual report, letter, packing slip, fillable form, postcard collage, magazine article, event flyer, two-column newsletter and Factur-X e-invoice
+`examples/` has a complete, runnable invoice, annual report, letter, packing slip, shipping label, fillable form, postcard collage, magazine article, event flyer, two-column newsletter and Factur-X e-invoice,
+and one per thing people build: a 2,000-row price list written `incremental`, a contract with initials
+on every page and signature fields, a landscape certificate, a two-column résumé with its body in HTML,
+a restaurant menu in `columns` with floats, a till receipt on an 80 mm roll, a PDF/UA-1 accessible report and a notice in English, German
+and Swedish, each hyphenated in its language
 ([previews and live PDFs](https://stationery.zoolutions.llc/docs/examples)); `bundle exec rake examples`
 renders them all, or render one with `stationery render examples/report.rb`.
+`examples/shaping/rtl_letter.rb`, a letter in Arabic, needs HarfBuzz and an Arabic font, which the gem
+does not ship (see [Complex scripts](#complex-scripts-the-shaper-hook)).
+
+The examples ship with the gem, with the images they read, so they are there to read and to run in an
+application that has only the gem. Inter is the one font the gem ships: the invoice examples are set in
+the Open Sans of the test suite in the repository and in Inter elsewhere.
+
+```sh
+stationery examples                          # their names and what each shows
+stationery examples invoice                  # the path of one; --source prints its code
+stationery render "$(stationery examples invoice)" --out invoice.pdf
+ls "$(bundle show stationery)/examples"      # or: gem contents stationery
+```
 
 ## Elements
 
@@ -84,9 +124,10 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `box(padding:, background:, border:, radius:, width:, height:, min_height:, overflow:, at:, link:, outset:, break_inside:, decoration:, rotate:, shadow:, float:, margin:) { }` | A container. Moves to the next page whole when it fits there and continues across pages when it does not; `break_inside: :auto` splits it at any page break, `:avoid` never splits it. At a cut, `decoration: :slice` (default) drops the padding and border, `:clone` keeps the padding. `overflow: :truncate` or `:shrink_to_fit` for fixed heights; a fixed `height:` never splits. `min_height:` is a floor that still splits: the first fragment keeps as much of it as the page holds, the next carries the rest (not combinable with `height:`). `at: [x, y]` pins it to a page position. `link:` makes the whole box clickable. `outset:` bleeds the background past the box (e.g. into the page margins). `rotate: -3` turns the painted box around its centre (layout box unchanged, never splits; a `link:` keeps its unrotated rectangle). `shadow: true` or `{ offset: [0, 4], blur: 8, color:, opacity: 0.15 }` paints a soft drop shadow under it, taking no space. `overflow: :hidden` clips the content to the rounded outline. `float: :left` or `:right` with a `width:` takes it to that side, `margin:` away from the text that wraps beside it: see [Floats](#floats). |
 | `row(gap:, align:, break_inside:) { column(width:) { } }` | Columns side by side. `width:` is points, a fraction (`0.5`), `:auto` or `nil` (equal share). Splits across pages like a box, every column at once; a row with a fixed-height column never splits; columns with `min_height:` do. |
 | `columns(count:, gap:, balance:, rule:) { }` | One flow poured through `count` columns, newspaper style: column 1 top to bottom, then column 2. Breaks where a page would (between lines with `orphans:`/`widows:`, never inside `break_inside: :avoid`, `keep_with_next` honoured). `balance: true` (default) ends the columns at nearly the same height where the content ends and fills them evenly, what cannot be shared going to the earlier columns (ten lines in three columns are 4, 3 and 3); `false` fills each before the next. Continues across pages; `page_break` inside ends the page; `rule: true \| { color:, width: }` draws a line between columns. |
-| `table(rows, widths:, width:, header:, split_rows:, cell:) { \|t\| }` | Tables. Cells are strings, layout nodes, procs built with the DSL (`-> { image logo }`) or components. Style with `t.row(0)`, `t.rows(-1)`, `t.column(1)`, `t.columns(1..)`, chained, plus `t.zebra`. Header rows repeat after a page break. A cell may be `{ content:, colspan:, rowspan: }` plus any cell option; rows list only the cells they start, as in HTML, and pages never break through a rowspan. Spans are set in the rows, not through selections. A row taller than the page continues on the next page, cut through its cells, with the header repeated; `split_rows: true` cuts any row that reaches the page bottom instead of moving it whole. |
+| `table(rows, widths:, width:, header:, split_rows:, cell:) { \|t\| }` | Tables. Cells are strings, layout nodes, procs built with the DSL (`-> { image logo }`) or components. Style with `t.row(0)`, `t.rows(-1)`, `t.column(1)`, `t.columns(1..)`, chained, plus `t.zebra`. Header rows repeat after a page break. A cell may be `{ content:, colspan:, rowspan: }` plus any cell option; rows list only the cells they start, as in HTML, and pages never break through a rowspan. Spans are set in the rows, not through selections. A row taller than the page continues on the next page, cut through its cells, with the header repeated; `split_rows: true` cuts any row that reaches the page bottom instead of moving it whole. `rows` is an Array or any Enumerable; an Enumerator (lazy or not) given a width for every column is read as pages reach it, selected from its start only: see [Large documents](#large-documents). |
 | `image(path_or_io, width:, height:, fit:, align:, radius:, rotate:, max_ppi:, downscale:, float:, margin:)` | JPEG, PNG or lossless WebP, aspect preserved. `fit: [w, h]` scales to fit inside; `fit: :cover` fills `width:` × `height:` and crops around the centre. `radius:` rounds the corners; `rotate:` turns it (degrees, clockwise) without changing the space it takes. Drawn at more than twice `max_ppi:` (300) it is reported as oversized; `downscale: true` resamples a PNG or WebP to that resolution instead. |
 | `svg(source_or_path, width:, height:, color:, align:)` | Vector icons and drawings; `currentColor` takes `color:` (or the `color` an element sets). Linear and radial gradients (`fill="url(#id)"`, `href` chains, both gradient units); `text`/`tspan` in the document's fonts; `<style>` stylesheets (element, class, id and `*` selectors); `use`, `symbol` sprites and nested `svg` viewports (`viewBox`, `preserveAspectRatio`); `clipPath` (both `clipPathUnits`). |
+| `barcode(data, type:, level:, module_size:, width:, height:, color:, quiet_zone:, native:, align:, alt:)` | A barcode drawn as vector bars, encoded in Ruby: `type: :code128` (the default; printable ASCII, digit runs in code set C), `:ean13` (12 digits and the check digit, or 13 checked), `:qr` (byte mode, `level: :l, :m, :q, :h`, versions 1 to 40, UTF-8 marked with an ECI) or `:datamatrix` (ECC 200 in ASCII encodation, digit pairs in one codeword, squares from 10 × 10 to 144 × 144). `module_size:` points a module (1, or 2 for a square one) or as many as fit `width:`; a linear one is `height:` (36) tall. The quiet zone is part of its size unless `quiet_zone: false`, and it shrinks to fit the space. Monochrome renders put it on the dot grid, a whole number of dots a module. `native: true` has `to_zpl` write the printer's own command for it: see [Label printers](#label-printers-to_zpl). A figure in a tagged PDF, its `alt:` by default the kind and the data. |
 | `wrap(gap:, row_gap:, align:) { }` | Children side by side at their own widths, wrapping onto new rows (chips, tags). |
 | `stack(gap:, align:) { }` | A base with layers painted over it: ordinary children set the height, `layer` children float over them and take no space. Moves to the next page whole. |
 | `layer(top:, right:, bottom:, left:, width:, height:, **box) { }` | Inside `stack`: a box placed by insets from the stack's edges, in points or as a fraction (`0.4`, `1/3r`) of its width/height; negative insets overhang. Takes every box option (`rotate:`, `shadow:`, `radius:`, …). |
@@ -136,17 +177,20 @@ text more                                       # around the pull quote
 - Text (paragraphs, headings, the text inside a `group` or an `html` block) wraps: every line takes
   the width left at its own top and is aligned and justified in it. A paragraph whose widest word
   does not fit beside the floats starts below them.
-- A list item and a `box` that paints nothing of its own wrap what they hold: they keep the full
-  width, and their lines are narrow beside the float and wide below it. That is a box without
-  `background:`, `border:`, `shadow:` or `link:` and without `width:`, `height:`, `rotate:`,
-  `overflow:` or `valign:`. Its padding lies under the float, as a block's does in CSS, so beside
-  the float its lines are the float's `margin:` away from it. A list item keeps its indent from the
-  float, with the marker beside its first line.
-- Anything else (a `box` with a background, a border or a size of its own, a `row`, `columns`, `table`,
-  `rule`, `image`, `svg`, form field) is a block:
-  it goes beside the float in the width that is left, and keeps that width all the way down, when
-  its own width (or the least its content takes) fits there; else it starts below the float. A
-  `spacer` takes its height beside the float; a `page_break` ends the page and the float with it.
+- A list item and a `box` that takes the width it is given wrap what they hold, as a block does
+  in CSS: they keep the full width, and their lines are narrow beside the float and wide below it.
+  A box with a `background:`, a `border:`, a `shadow:` or a `link:` paints it across the full
+  width, under the float: the float is painted after the boxes beside it, so it sits on top of the
+  background, and a float with `opacity:` or a `shadow:` shows the background through it. The
+  box's padding lies under the float, as a block's does in CSS, so beside the float its lines are
+  the float's `margin:` away from it. A list item keeps its indent from the float, with the marker
+  beside its first line, over the background of its body if the body has one.
+- A `box` with a size or a place of its own (`width:`, `height:`, `rotate:`, `overflow:` other than
+  `:visible`, `valign:` other than `:top`), a `row`, `columns`, a `table`, `rule`, `image`, `svg` or
+  form field is a block: it goes beside the float in the width that is left, and keeps that width
+  all the way down, when its own width (or the least its content takes) fits there; else it starts
+  below the float. A `spacer` takes its height beside the float; a `page_break` ends the page and
+  the float with it.
 - Several floats: the next one goes beside those already there when it fits, else below them, and
   never above one written before it. Left and right floats share a line with the text between them.
 - The flow that holds a float is at least as tall as the float, so what follows a box, a column or a
@@ -155,8 +199,19 @@ text more                                       # around the pull quote
   after it could not start beside it there, it moves to the next page with that content. A
   paragraph beside a float splits between lines as always (`orphans:`, `widows:`); the lines carried
   over are wrapped again at the full width, because the float stayed behind. So are those of a list
-  item and of a box.
-- In a tagged PDF the float is where it was written: an image is a `Figure`, a box has its `role:`.
+  item and of a box. The part that stays on the page keeps the place its whole was given, beside
+  the floats or below them.
+- Floats written one after the other that are taller than a page together are cut before the
+  first that does not fit: it starts the next page, with the floats and the text written after it,
+  so the page it left holds the floats above it and nothing beside them. It is the same in a box, a
+  list item, a column and a table cell. Only a float taller than a page by itself runs over it, and
+  is reported as an `Overflow`. Floats that fit a page together stay together: when one of them
+  does not fit what is left of the page, they all go to the next.
+- What does not fit below the floats at the top of a page (a box that stays whole, a line where
+  none is left) goes to the next page and leaves the floats behind.
+- In a tagged PDF the float is where it was written, painted after the boxes beside it or not: an
+  image is a `Figure`, a box has its `role:`, and a floated box without one beside a box with a
+  background is a `Div`, which keeps its content in place.
 
 A line beside a float is taken to be as tall as a line of the paragraph's own style when its width
 is looked up, so one much taller word may reach a little past a float's bottom edge before the text
@@ -340,7 +395,8 @@ signature_field "signature", label: "Signature of the applicant"
   in the text style around the field, in the document's own fonts: embedded, with the fallbacks
   applied per character, so a value in any script the fonts cover is drawn (`/V` holds it as
   Unicode). A character no font has is drawn as `.notdef` inside a `Span` whose `ActualText` is the
-  character, as in any other text, so the appearance still extracts as written. Check marks and radio dots are paths. `NeedAppearances` is set too, so viewers redraw
+  character, as in any other text (or as the font's stand-in under `conformance` with
+  `missing_glyphs: :replace`), so the appearance still extracts as written. Check marks and radio dots are paths. `NeedAppearances` is set too, so viewers redraw
   edited values; ZapfDingbats is listed for the ones that redraw a button's mark, never embedded
   and never used by the appearances themselves.
 - A field that can be edited keeps printable ASCII and Latin-1 in its font beyond the value it shows
@@ -381,6 +437,22 @@ render Callout.new(color: "#F3F4F6") { text "Amount due" }
 ## Pages
 
 - `page size: :a4 | :a3 | :a5 | :letter | :legal | :tabloid | [w, h], margin:, layout: :landscape`
+- Sizes are points. `mm(102)`, `cm(2)`, `inch(4)` and `pt(12)` convert to them in every component and
+  document (`include Stationery::Units` anywhere else), and `page` reads lengths with their unit:
+
+  ```ruby
+  class Label < Stationery::Document
+    page size: ["102mm", "74mm"], margin: "3mm"     # or "102 x 74 mm", "4in x 6in", [mm(102), mm(74)]
+
+    def view_template = box(at: [mm(20), mm(45)], width: mm(60)) { text "Fragile" }
+  end
+  ```
+
+  Units are `mm`, `cm`, `in` and `pt`; decimals take a point (`"101.6mm"`). Beside the office sizes there
+  are `:a6`, `:a7`, `:b5`, the envelopes `:dl`, `:c5` and `:c6` (short edge first: `layout: :landscape`
+  is the address side) and the label stock `:label_4x6`, `:label_4x3`, `:label_4x2`, `:label_100x150`
+  and `:label_100x50`. A size or margin that cannot be read raises `ArgumentError` when the class is
+  defined.
 - `page_template { |page| … }` runs on every page after pagination with `page.number`, `page.count`,
   `page.width`, `page.height`, `page.margin` and `page.content_box`. `page_template(layer: :background)`
   paints under the content (full-bleed backgrounds).
@@ -412,13 +484,294 @@ render Callout.new(color: "#F3F4F6") { text "Amount due" }
   that starts there, with `style:` `:decimal`, `:roman`, `:roman_lower`, `:alpha`, `:alpha_lower` or
   `nil` (prefix only), `start:` and `prefix:`. `to_pdf(page_labels:)` overrides it for one render.
 - Content taller than a page is placed anyway; `document.warnings` lists every overflow.
+- Content that does not fit a page continues on the next, as a letter or a report should. A label, a
+  receipt or a card must not: `max_pages 1` in the class body says so. A render that needs more pages
+  lays them all out and reports `Warnings::TooManyPages`, naming what the first page past the limit
+  starts with, so `strict` raises:
+
+  ```ruby
+  class ShippingLabel < Stationery::Document
+    page size: :label_4x6, margin: mm(4)
+    max_pages 1
+  end
+
+  label.warnings.map(&:message)
+  # => ["the document may have 1 page and needs 2: page 2 starts with a Code 128 barcode"]
+  ```
+
+  Text is named by its first line, quoted and cut at 40 characters, anything else by its kind (`a
+  table`, `an image`, `a QR code`, `a box`). `to_pdf` and `to_png` keep every page, so the one that
+  spilled can be looked at; `to_zpl` writes no label at all (see Label printers below). `to_pdf(max_pages:)`,
+  `to_png(max_pages:)` and `to_zpl(max_pages:)` replace the limit for one render and `nil` takes it
+  away, as `max_pages nil` does in a subclass; a subclass's `page` keeps it. The declaration writes
+  nothing: a document that fits is byte for byte what it is without it.
 - After `to_pdf`, `document.warnings` is an Enumerable of everything the render noticed but did not
   raise on, each with a `#message`: overflows, SVG elements that were skipped (`UnsupportedSvg`), and
   the other `Stationery::Warnings::*` kinds (missing glyphs, unknown font families, skipped images,
-  unresolved links, duplicate anchors). Equal warnings are listed once; warnings from page templates
+  unresolved links, duplicate anchors, in a tagged render what is missing for accessibility, and in a
+  [monochrome](#monochrome) render the colours and lines a one-bit printer cannot print as they are).
+  Equal warnings are listed once; warnings from page templates
   are included. `to_pdf(strict: true)`, or `strict` at class level, raises `Stationery::WarningsError`
   (with `#warnings`) instead of writing a PDF that produced any; `to_pdf(strict: false)` opts one
   render out again.
+- After a render, `document.page_count` is how many pages it laid out: a tagged file's page
+  dictionaries are packed into object streams, where a search of its bytes does not find them.
+
+### Printing
+
+A PDF can say how it wants to be printed. For a page that is the medium itself (a label, a card, a
+pre-printed form) the defaults of a print dialog are the wrong ones: "fit to page" prints a
+100 × 60 mm label at 94 %.
+
+```ruby
+class ShelfLabel < Stationery::Document
+  page size: :label_100x50, margin: "3mm"
+  print scaling: :none, copies: 2, pick_tray_by_size: true, duplex: :simplex
+end
+
+ShelfLabel.new.to_pdf(print: { copies: 1 })           # laid over the hints of the class
+ShelfLabel.new.to_pdf(print: { duplex: nil })         # without one of them
+ShelfLabel.new.to_pdf(print: nil)                     # without any (false does the same)
+```
+
+| Option | Values | Written as |
+| --- | --- | --- |
+| `scaling:` | `:none`, `:default` | `/PrintScaling` `/None`, `/AppDefault` |
+| `copies:` | an Integer of 1 or more | `/NumCopies` |
+| `pick_tray_by_size:` | `true`, `false` | `/PickTrayByPDFSize` |
+| `duplex:` | `:simplex`, `:long_edge`, `:short_edge` | `/Duplex` `/Simplex`, `/DuplexFlipLongEdge`, `/DuplexFlipShortEdge` |
+| `pages:` | a Range of page numbers from 1, or a list of them: `1..3`, `[1..1, 3..4]`, `2..` | `/PrintPageRange` |
+| `dialog:` | `:on_open` | `/OpenAction << /S /Named /N /Print >>` |
+
+- The first five are entries of the catalog's `/ViewerPreferences` (ISO 32000-1, 12.2, table 150),
+  beside the `/DisplayDocTitle` of a tagged document. `dialog: :on_open` asks the viewer to open its
+  print dialog when the file is opened, as `window.print()` does for a page, without JavaScript.
+- `print` at class level adds to what the class inherits, and `to_pdf(print:)` to what the class
+  declares. A `nil` takes a hint away (`print copies: nil` in a subclass).
+- Every option is checked where it is written, the class body or the call of `to_pdf`, and raises
+  `ArgumentError` naming what it takes: `print scaling: is :none or :default, not :fit`. Ranges that
+  overlap are refused.
+- `pages:` counts from 1, as the file does, and is written in page order. How many pages there are is
+  known when the document is rendered: a range is cut at the last page (`2..` and `2..99` both end
+  there) and one that starts after it is left out, because a viewer drops a range that names a page
+  the document does not have.
+- `/ViewerPreferences` is allowed under PDF/A and PDF/UA. The print dialog is not an action PDF/A
+  has: `dialog: :on_open` with `conformance :pdf_a2b` or `:pdf_a3b` raises
+  `Stationery::ConformanceError` (ISO 19005-2/3, 6.5.1; veraPDF rule 6.5.1-2). PDF/UA-1 alone takes it.
+- The hints are written by every render: `incremental:`, signed and encrypted ones too.
+- `print` in a class body is this declaration. Inside `view_template` and every other method of a
+  document it is still `Kernel#print`.
+- `Inspector#print_preferences` reads them back as `print` takes them, `pages` as a list of ranges,
+  and `have_print_preference(scaling: :none)` and `assert_print_preference` assert them.
+
+They are hints: a viewer follows the ones it knows, and whoever prints can overrule them in the
+dialog. The table says what each viewer does and how that is known. Nothing in it was tried in a
+running viewer: "documented" is what the vendor's PDF reference says, "source" what the viewer's
+source code did when it was read on 2026-09-28, "reported" what a user wrote in the issue named.
+
+| Viewer | `scaling:` | `copies:` | `duplex:` | `pages:` | `pick_tray_by_size:` | `dialog:` |
+| --- | --- | --- | --- | --- | --- | --- |
+| Acrobat, Acrobat Reader | sets the dialog (documented) | sets the dialog, 2 to 5 (documented) | sets the dialog (documented) | sets the dialog (documented) | sets the dialog (documented) | opens the dialog (reported, [pdf.js 11442](https://github.com/mozilla/pdf.js/issues/11442)) |
+| Chrome, Edge (PDFium) | preset of the print preview (source) | preset of the print preview (source) | preset of the print preview (source) | not read (source) | not read (source) | starts printing (source) |
+| Firefox (pdf.js) | read, not used by the viewer (source; [bug 1243580](https://bugzilla.mozilla.org/show_bug.cgi?id=1243580)) | read, not used (source) | read, not used (source) | read, not used (source) | read, not used (source) | starts printing (source) |
+| Preview (macOS) | not tested | not tested | not tested | not tested | not tested | not tested |
+| Evince, Okular (poppler) | not tested | not tested | not tested | not tested | not tested | not tested |
+
+### Monochrome
+
+A thermal label printer (203 or 300 dpi), a receipt printer or an e-paper display prints black or
+nothing. Whatever else the PDF holds, the driver or the printer turns into dots of its own choosing:
+grey text comes out speckled, a light rule or background vanishes or turns into a dot pattern, and a
+line thinner than one dot prints or not depending on where it lands. `monochrome` makes those
+choices where they can be seen, before anything is printed:
+
+```ruby
+class ShelfLabel < Stationery::Document
+  page size: [mm(100), mm(60)], margin: mm(4)
+  monochrome dpi: 203                               # report what a 203 dpi printer cannot print as it is
+end
+
+ShelfLabel.new.to_pdf(monochrome: { snap: true })  # change it instead, for this render
+ShelfLabel.new.to_pdf(monochrome: false)           # as it was, byte for byte
+```
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `dpi:` | `203` | the printer's dots per inch: one dot is 72/dpi pt (0.355 pt at 203 dpi, 0.24 pt at 300) |
+| `snap:` | `false` | change colours and thin lines instead of reporting them |
+| `threshold:` | `0.5` | under `snap:`, a fill whose tone is darker is painted black, a lighter one is not painted |
+| `dither:` | `:floyd_steinberg` | how a bitmap becomes dots: `:floyd_steinberg`, `:ordered` (an 8 × 8 Bayer pattern) or `:threshold` (cut at half) |
+
+- **Colours.** Every colour that is not black or white, and anything painted at an `opacity:` below 1,
+  is a `Warnings::NotMonochrome` naming the colour and what painted it: `text`, `a rule` (a `rule`,
+  an underline, a strikethrough: a filled rectangle 3 pt thick or less), `a background` (any other
+  fill), `a border or line` (any stroke), `a gradient` or `an image`, once per colour, kind and page:
+  `text in #888888 on page 1 is not black or white`. `strict` raises on them. It sees whatever is
+  painted, by an element, an SVG or a `canvas { }` block alike.
+- **`snap: true`.** Text, rules, borders and lines are painted black, except white ones, which stay
+  white (white text on a black box). A fill is painted black when its tone is darker than
+  `threshold:` and left out when it is lighter; the tone is the colour's luma (ITU-R BT.601), an
+  opacity laid over white paper (black at 0.3 is a tone of 0.7). A gradient is black or left out
+  by the average tone of its stops. Opacity is taken away. Nothing is reported.
+- **Line widths.** A stroke or a rule thinner than a dot (`width × the scale of a transform`) is a
+  `Warnings::ThinLine` and is left as it is; with `snap: true` it is widened to a dot.
+- **The dot grid.** Outside any transform, a filled rectangle (a rule, a background, an underline)
+  and a stroke made of horizontal and vertical lines (a border, a table's cell borders, a line) are
+  put on the printer's grid, counted from the top left corner of the page: their edges on whole dots
+  and their widths whole numbers of dots, so a hairline is as wide on every label. A curve, a rounded
+  corner, a slanted line and anything under a transform keeps its geometry.
+- **Images.** A PNG, a lossless WebP or a JPEG is greyed (a transparent pixel is white paper),
+  resampled to the dots it covers at `dpi:` and dithered, and embedded as a one-bit DeviceGray image
+  (`/BitsPerComponent 1`): what prints is the pattern chosen here, not the driver's. A JPEG is decoded
+  for it in Ruby, no larger than the dots need; one of a kind that is not decoded (lossless,
+  arithmetic-coded, hierarchical, 12-bit) is embedded as it is and reported (`an image in JPEG 640x480`).
+- `monochrome` at class level is inherited and adds to what the class inherits; `monochrome false`
+  takes it away. `to_pdf(monochrome:)` takes `true`, `false` or options laid over the class's.
+- Monochrome renders keep PDF/A and PDF/UA: the one-bit image is DeviceGray, which the sRGB output
+  intent covers (checked with veraPDF, PDF/A-3b and PDF/UA-1).
+- `Inspector#colors` lists what a PDF paints with, so a spec can hold it: `expect(pdf).to
+  have_pdf_colors("#000000")`.
+
+What it does not do: it does not dither a lossless, arithmetic-coded, hierarchical or 12-bit JPEG, does not look at form
+fields (their widget draws them, not the page), does not put dashes, line caps or curves on the grid,
+and does not make small text bolder. It changes nothing without `monochrome`. The rules live in
+`Stationery::Monochrome::Rules` and `Monochrome::Grid`, apart from the PDF canvas, and `to_png` and
+`to_zpl` apply the same ones (see below).
+
+### Pictures of a render: to_png
+
+`to_png` paints the pages `to_pdf` lays out on pixels instead, in Ruby, with nothing to install: a
+preview, a picture to look at in a spec or a pull request, or what a one-bit printer will print.
+
+```ruby
+pngs = Invoice.new(invoice).to_png            # => ["\x89PNG…", …], one String per page, 96 dpi
+Invoice.new(invoice).to_png("invoice.png")    # one page: invoice.png; several: invoice-1.png, invoice-2.png, …
+Invoice.new(invoice).to_png(dpi: 144, pages: 1)             # pages: a number, a Range or an Array of them
+ShelfLabel.new.to_png(monochrome: { dpi: 203, snap: true }) # one bit to a dot, 1-bit PNG
+```
+
+- **What is drawn**: text from the outlines of its glyphs (TrueType, CFF, WOFF; synthetic bold and
+  oblique, letter spacing, rise, shaped runs), fills and strokes with their caps, joins (miter limit
+  10) and dashes, even-odd and nonzero fills, clips, transforms and rotations, opacity, SVG linear and
+  radial gradients, PNG, WebP and JPEG images, headers, footers, page templates (a background layer under
+  the page) and page numbers. A colour picture is 24-bit RGB on white, anti-aliased; a text's origin,
+  a stroke's horizontal and vertical edges and an upright image's edges are put on the pixel grid as
+  poppler puts them, so it is close to `pdftoppm -r <dpi>` of the same PDF: the examples differ in
+  0.0 to 0.5% of their pixels at 72 dpi, in the hinting of a few glyphs and the edges of images.
+- **What is not**: a lossless, arithmetic-coded, hierarchical or 12-bit JPEG, which is not decoded, is drawn as a
+  grey box with a cross and reported (`Warnings::SkippedImage`); form fields draw nothing (their
+  widget is the PDF viewer's); links, bookmarks and tagging are not visible anyway.
+- **Monochrome.** `monochrome:` takes what `to_pdf` takes, and the class's `monochrome` applies
+  unless `monochrome: false` is given. The picture is drawn at the monochrome `dpi:` (a `dpi:` given
+  to `to_png` replaces it), a pixel in or out by its centre with no anti-aliasing, and written as a
+  1-bit PNG. The rules are those of the PDF (colours reported or snapped, thin lines, the dot grid,
+  images dithered at the dots they cover); a page with grey left on it (a colour reported and kept
+  without `snap:`) is dithered as images are. An upright image is drawn dot for dot as the one-bit
+  image the PDF embeds, with its corner on the nearest dot: the PDF leaves the image's box where the
+  layout put it, and its size in dots is the image's own, where poppler stretches it by a dot when both
+  edges of the box round outwards. Black and white match `pdftoppm -mono` in all but 0.1 to 2% of the
+  dots; dithered areas differ dot by dot, since poppler halftones where stationery dithers.
+- **Options.** `dpi:` (96, or the monochrome dpi), `pages:`, `monochrome:`, `debug:` (the layout
+  rectangles), `strict:`, `shaper:` and `max_pages:` as `to_pdf` has them. What only a PDF has (`sign:`, `encrypt:`,
+  `conformance:`, `attachments:`, `print:`, `tagged:`, `page_labels:`, `xmp:`, `factur_x:`,
+  `incremental:`, `missing_glyphs:`, `object_streams:`) raises `ArgumentError` when it is passed, and is left alone when
+  the class declares it, so a signed or encrypted document still has pictures.
+- **Speed.** A 100 × 150 mm label at 203 dpi (800 × 1200 dots) takes about 30 ms, a one-page invoice
+  at 96 dpi about 0.1 s, a page of dithered photographs at 203 dpi about 0.7 s, a label with a
+  12-megapixel JPEG photo about 1 s (Ruby 3.4 with YJIT,
+  Apple M-series). Each page is kept as the list of what it was asked to draw until every page is
+  painted, then drawn and encoded one at a time, so a long document does not hold a bitmap per page.
+
+`Stationery::Raster` has the pieces: `Raster::Canvases` and `Raster::Canvas` record, `Raster::Painter`
+replays onto a `Raster::Surface` through `Raster::Scanner` (coverage), `Raster::Stroker` and
+`Raster::Flattener`, and `Raster::PNG` writes the file.
+
+### Label printers: to_zpl
+
+A thermal label printer (Zebra, and the many makes that emulate ZPL II) is driven in its own
+language, not PDF. `to_zpl` writes the document as ZPL: each page is drawn one bit to a dot, as
+`to_png(monochrome: …)` draws it, and sent as one graphic field, so the label is the layout `to_pdf`
+produces, in any font the document uses. One document class serves the preview on screen and the
+printer.
+
+```ruby
+class ShippingLabel < Stationery::Document
+  page size: "4in x 6in", margin: mm(4)
+  max_pages 1                               # a second page raises instead of printing a second label
+  monochrome dpi: 203
+end
+
+label = ShippingLabel.new(parcel)
+label.to_zpl                                # => "^XA^PW812^LL1218^LH0,0^FO0,0^GFA,…^XZ\n", one label per page
+label.to_zpl("label.zpl", dpi: 300, copies: 2)
+label.to_zpl(compression: :hex, pages: 1)   # plain hex, for printers that do not take Z64
+```
+
+How the ZPL reaches the printer is the application's business: a socket to port 9100, a print
+server, a browser print agent. For example, over the network:
+
+```ruby
+require "socket"
+TCPSocket.open("printer.local", 9100) { |socket| label.to_zpl(socket) }
+```
+
+- **What is written.** Per page `^XA`, `^PW` and `^LL` (the page's width and length in dots,
+  `Raster.pixels(points, dpi)`), `^LH0,0`, `^FO0,0`, one `^GFA` graphic field, `^FS`, `^PQ` (copies)
+  and `^XZ`, then a newline. The field's dots are 1 for black, each row padded to a byte with white.
+  `compression: :z64` (the default) deflates the rows with zlib and writes them in Base64, followed
+  by the CRC Zebra's software writes (CRC-16/XMODEM of the Base64 text, checked against a ZebraDesigner
+  print file); `:hex` writes them as plain hex, about 20 times larger.
+- **Always monochrome.** A label printer prints one bit, so `to_zpl` renders with the class's
+  `monochrome` settings when it declares them and with the defaults when it does not (`snap: false`,
+  `dither: :floyd_steinberg`): a colour is reported as `Warnings::NotMonochrome` and dithered, as
+  `to_png(monochrome: true)` shows it. `monochrome:` takes options laid over them (`{ snap: true }`);
+  `monochrome: false` raises.
+- **`dpi:`** is the printer's: 152, 203, 300 or 600 (6, 8, 12 or 24 dots a millimetre); anything else
+  raises `ArgumentError` naming them. It defaults to the class's `monochrome dpi:`, else 203, and
+  replaces it when given, so `to_zpl(dpi: 300)` and `to_png(monochrome: { dpi: 300 })` are the same
+  dots.
+- **`copies:`** is `^PQ`, by default the class's `print copies:`, else 1. **`pages:`** a page number,
+  a Range or an Array, in the order given; `target` a path or anything answering `write` (a socket).
+- **One label.** Content that does not fit the label goes to a next page, and every page is a label.
+  Declare `max_pages 1` (see Pages) and a document that needs a second page writes no ZPL:
+  `to_zpl` raises `Stationery::WarningsError` with `Warnings::TooManyPages`, strict or not, because
+  the harm of a second label is done when it prints, where no one reads a warning. `to_zpl(max_pages: nil)`
+  writes them all; `to_pdf` and `to_png` of the same document keep every page and warn, so the page
+  that spilled can be looked at.
+- `strict:`, `debug:`, `shaper:` and `max_pages:` are those of `to_pdf`; what only a PDF has raises, as for `to_png`.
+- **Speed.** A 4 × 6 in label takes about 25 ms at 203 dpi and 35 ms at 300 dpi (Ruby 3.4, Apple
+  M-series), and is 10 to 20 KB of ZPL.
+- The labels were read back and compared with `to_png` dot for dot, and rendered by
+  [Labelary](http://labelary.com/viewer.html), a ZPL viewer, identically. They were not printed on a
+  printer by the gem's specs.
+
+**Barcodes the printer draws.** A `barcode` is part of the picture unless it asks otherwise:
+`barcode "SX0042771903", native: true`, or `to_zpl(native: true)` for every barcode that does not
+say `native: false`. Such a barcode is left out of the graphic field and written after it as the
+printer's own command, where the picture had it, so the printer puts the bars on its own dot grid:
+
+```
+^FO146,874^BY4^BCN,124,N,N,N,N^FD>:SX>50042771903^FS             Code 128, its code sets named
+^FO65,197^BY3^BEN,113,N,N^FD400638133393^FS                       EAN-13, the printer adds the check digit
+^FO650,625^BQN,2,4^FDMM,B0034https://track.example/SX0042771903^FS  QR code, byte mode, level M
+^FO42,42^BXN,8,200,14,14,6,_,1^FDSX0042771903^FS                  Data Matrix (ECC 200), 14 × 14
+```
+
+- `^BY` is the module in whole dots, the height in dots, and data ZPL would read as a command is
+  escaped with `^FH`. A QR code's `^FO` is 10 dots above it, since `^BQ` draws that far below its
+  origin. A Data Matrix is asked for at its own size, so it takes the same square.
+- It stays in the picture when the printer could not draw it as it is: rotated or otherwise
+  transformed, clipped, lighter than half grey, a module over 10 dots, a QR code of UTF-8 text
+  (its ECI has no field in `^BQ`), or a Data Matrix holding `_` (the escape character `^BX` is given).
+- Rendered by Labelary, the Code 128 is the same dots as `to_png` draws; the EAN-13's guard bars come
+  out 13 dots longer, as the printer draws them; a QR code covers the same modules' square, its
+  modules chosen by the printer's own encoder (another mask); a Data Matrix of digits and capitals is
+  the same dots, one of other text another encodation in the same square. All decode (ZBar,
+  dmtxread) to the data.
+- Rules and boxes are not written as `^GB`: a box drawn natively would print over white text on it,
+  which the picture keeps.
+
+`stationery render label.rb --zpl --dpi 300` writes `label.zpl` (see [CLI](#cli)).
 
 ### Encryption
 
@@ -498,8 +851,11 @@ and across page breaks: a paragraph continued on the next page stays one `P`.
   `BlockQuote`, and give images their `alt`. In `html`, `<img alt="">` is decoration as `alt: false`
   is (an `<img>` without the attribute is a description missing). Markdown has no way to say so:
   `![](photo.png)` is a description missing, and decoration goes through `html` or `image`.
-- Headers, footers and page templates are pagination artifacts; backgrounds, borders and rules drawn
-  outside any element are layout artifacts.
+- Headers, footers and page templates are pagination artifacts, but for their links: a `link:` one
+  paints (`text(link:)`, markup, `html`, `markdown`, `box(link:)`) is a `Link` of the `Document`
+  holding its text and its annotation, read after the content of its page, in the order header,
+  footer, page templates. The rest of the region stays an artifact. Backgrounds, borders and rules
+  drawn outside any element are layout artifacts.
 - `metadata lang:` writes the catalog's `/Lang`; the title is shown instead of the file name.
 - Every document carries an XMP packet (`/Metadata`, uncompressed) mirroring the Info dictionary:
   `dc:title`, `dc:creator`, `dc:description`, `dc:subject`, `dc:language`, the `xmp:` dates and
@@ -512,8 +868,22 @@ and across page breaks: a paragraph continued on the next page stays one `P`.
   (`1`, then `3` skips `2`). Going back up is free (`3`, then `1`). Headings are read in the order of
   the structure tree, inside sections, lists, table cells, columns and floats; those of headers,
   footers and page templates are artifacts and do not count.
-- A missing `lang` is a `Warnings::MissingLanguage`. All three are warnings, so `strict` catches them,
-  and `conformance :pdf_ua1` raises on the first two.
+- A link annotation that belongs to no `Link` element is a `Warnings::UntaggedLink` (`target`,
+  `place`, `page`): a link in the header row a table repeats on its next pages, which is an artifact
+  (`place` is `:artifact`), and `canvas.link` without a `tag:` (`:canvas` in the body, `:header`,
+  `:footer` or `:page_template` on the canvas of one). Every `link:` is tagged, in the body and in
+  headers, footers and page templates; on a canvas of the body, pass the `Link` element that holds
+  what the link draws: `canvas.link(x, y, w, h, url, tag: element)` after
+  `canvas.tag(element) { … }`.
+- A missing `lang` is a `Warnings::MissingLanguage`. All four are warnings, so `strict` catches them,
+  and `conformance :pdf_ua1` raises on the first three.
+- A tagged render packs its structure elements, and every other object that is not a stream, into
+  deflated object streams (`/Type /ObjStm`, 200 objects each) 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 is 115 KB instead of
+  501 KB. Streams, the `/Encrypt` dictionary and a signature dictionary stay out; PDF/A-2, PDF/A-3 and
+  PDF/UA-1 allow them. `object_streams false` at class level, or `to_pdf(object_streams: false)`,
+  writes the classic table for a reader that cannot read them; `to_pdf(object_streams: true)` packs
+  an untagged render too.
 - Untagged documents (the default) are written exactly as before.
 
 Check the tree in tests with `have_structure` and `have_tagged_content` (see [Testing](#testing)):
@@ -561,8 +931,10 @@ mislabelled: `ArgumentError` for options that contradict the level, `Stationery:
   every link annotation a description (`/Contents`: the URL, or the target page). A figure without
   `alt:` or with a blank one raises (7.3); mark decoration with `alt: false`, or `<img alt="">` in
   `html`. A heading level that is skipped raises (7.4.2): the first heading is `heading: 1`, and a
-  heading is at most one level below the heading before it. PDF/A alone asks for neither.
-  Encryption is allowed.
+  heading is at most one level below the heading before it. A link annotation outside the structure
+  tree raises (7.18.5): a link in the header row a table repeats, or `canvas.link` without a `tag:`.
+  Every other link is tagged, those of headers, footers and page templates too.
+  PDF/A alone asks for none of the three. Encryption is allowed.
 - Combined, the XMP packet also describes the `pdfuaid` schema to PDF/A (`pdfaExtension:schemas`).
 - Interactive form fields are allowed: their appearances draw with embedded fonts and paths, every
   field has a `/TU`, and `NeedAppearances` and ZapfDingbats are left out. Only a field made without
@@ -570,16 +942,52 @@ mislabelled: `ArgumentError` for options that contradict the level, `Stationery:
   standard Helvetica.
 - A character no font has raises at every level, naming the character and the family: it draws as
   `.notdef`, which text may not reference under PDF/A (6.2.11.8) or PDF/UA (7.21.8). Add a font or
-  `font_fallbacks` that covers it. Whitespace a font lacks draws as a blank and is accepted.
+  `font_fallbacks` that covers it, or let the render draw a stand-in with `missing_glyphs: :replace`
+  (below). Whitespace a font lacks draws as a blank and is accepted.
 - Without `conformance` nothing changes: the output is byte for byte what it was.
 
+A name in a script the fonts do not cover (a customer in Tokyo on an invoice archived as PDF/A) is
+where the raise turns up in practice. Applications rescued it and rendered again without the claim:
+
+```ruby
+begin
+  InvoicePdf.new(invoice).to_pdf
+rescue Stationery::ConformanceError => e
+  logger.warn(e.message)
+  InvoicePdf.new(invoice).to_pdf(conformance: nil)   # mislabelled no more, but no longer PDF/A
+end
+```
+
+`missing_glyphs: :replace` keeps the claim instead: a character no font has is drawn as the first
+of U+FFFD (�), U+25A1 (□) and `?` that the font drawing it has, inside the `Span` whose `ActualText`
+is the character, so the text still extracts, copies and reads aloud as written and nothing
+references `.notdef`. The stand-in has its own advance, so lines are measured as they are drawn.
+
+```ruby
+class InvoicePdf < Stationery::Document
+  conformance :pdf_a3b, missing_glyphs: :replace   # :raise is the default
+end
+
+InvoicePdf.new(invoice).to_pdf(conformance: :pdf_a3b, missing_glyphs: :replace) # per render
+```
+
+The `Warnings::MissingGlyph` stays (its `stand_in` is the character drawn, and `strict` still
+raises on it), so what was replaced is on record. A font that has none of the three, which a
+symbol font may not, still raises and says so. veraPDF passes 2b, 3b and ua1 with each of the
+three stand-ins, in body text, headers and page templates, form field values and shaped text.
+Without `conformance` the option changes nothing, and with `:raise` neither.
+
 `bundle exec rake verify:conformance` renders `examples/invoice.rb` as PDF/A-3b, and
-`examples/report.rb`, `examples/form.rb`, `examples/article.rb` (floats) and `examples/newsletter.rb`
-(columns) as PDF/A-3b plus PDF/UA-1, and validates them with
-[veraPDF](https://verapdf.org) through Docker (`verapdf/cli`); CI runs it on every push. Validate
-your own documents the same way:
+`examples/report.rb`, `examples/form.rb`, `examples/article.rb` (floats), `examples/newsletter.rb`
+(columns) and `examples/accessible_report.rb` (figures, a table with header cells) as PDF/A-3b plus
+PDF/UA-1, the report once more with a link in its footer, and validates
+them with
+[veraPDF](https://verapdf.org): a `verapdf` on the PATH when there is one (`brew install verapdf`),
+else through Docker (`verapdf/cli`); CI runs it on every push. Validate your own documents the same
+way:
 
 ```sh
+verapdf --format text -v --flavour 3b invoice.pdf
 docker run --rm -v "$PWD:/data:ro" verapdf/cli --format text -v --flavour 3b /data/invoice.pdf
 ```
 
@@ -756,9 +1164,10 @@ StatementPdf.new(account).to_pdf { |chunk| response.stream.write(chunk) }
 
 Peak resident memory of one render in a fresh process, and the megabytes still alive when
 pagination ends (`bundle exec rake memory`; Apple M2 Max, Ruby 3.4.2 +YJIT, on a busy machine:
-two runs of the same render peak up to a fifth apart, what is alive repeats):
+two runs of the same render peak up to a fifth apart, what is alive repeats; the text documents
+were measured on 0.11.0, the tables on 0.12.0):
 
-| Document | Pages | | Before | Now | `incremental: true` |
+| Document | Pages | | 0.10 | Now | `incremental: true` |
 |---|---:|---|---:|---:|---:|
 | Headings and paragraphs | 1,000 | peak | 391 MB | 111 MB | 108 MB |
 | | | alive | 216 MB | 17 MB | 14 MB |
@@ -768,13 +1177,63 @@ two runs of the same render peak up to a fifth apart, what is alive repeats):
 | | | alive | 222 MB | 44 MB | 11 MB |
 | | 5,189 | peak | 1,643 MB | 614 MB | 446 MB |
 | | | alive | 1,080 MB | 180 MB | 20 MB |
-| One table of 33,000 rows | 1,000 | peak | 901 MB | 653 MB | 648 MB |
-| | | alive | 494 MB | 28 MB | 25 MB |
-| One table of 165,000 rows | 5,000 | peak | 3,792 MB | 2,952 MB | 2,955 MB |
-| | | alive | 2,437 MB | 65 MB | 49 MB |
+| One table of 33,000 rows | 1,000 | peak | 901 MB | 174 MB | 174 MB |
+| | | alive | 494 MB | 26 MB | 23 MB |
+| One table of 165,000 rows | 5,000 | peak | 3,792 MB | 584 MB | 586 MB |
+| | | alive | 2,437 MB | 40 MB | 25 MB |
+
+What is left is the document as it was built: every node but a table cell's exists before the
+first page is painted. A table with a column without a width resolves its column widths from every
+cell, and keeps the widths, not the cell's text: a cell's node is built when a page reaches its row and let go with the page
+(the table of 165,000 rows holds 105 MB when its columns are resolved, its cells and their
+text, where it held 913 MB). In a tagged render the `TR`, `TH` and `TD` of a row are built
+when a page paints it, and the structure tree holds them until the file is written: the
+same table tagged peaks at 2.2 GB.
+
+A table whose every column has a width (`widths:` in points or fractions) measures no cell for
+its columns. Given its rows as an Enumerator, lazy or not, such a table reads them as pages
+reach them, and holds the rows of the page being filled and the one after them, none before
+its first page:
 
-What is left is the document as it was built: every node exists before the first page is
-painted, and a table resolves its column widths from every cell.
+```ruby
+rows = [%w[Order Customer Total]].each + Order.find_each.lazy.map { |o| [o.number, o.customer, o.total] }
+table(rows, header: true, widths: [80, 0.5, 90]) do |t|
+  t.row(0).weight = :bold
+  t.columns(2).align = :right
+  t.zebra(from: 1, color: "#F4F4F4")
+end
+```
+
+- The header rows, `zebra`, `split_rows`, cells spanning columns and selections by index from
+  the start (`t.row(0)`, `t.rows(1..)`, `t.columns(…)`) work as they do for an Array, applied to
+  each row as it is read. A proc or component cell is built then, in the text style the table
+  was given in.
+- What needs the end of the table raises `ArgumentError`: a row counted from the end
+  (`t.row(-1)`, `t.rows(1..-2)`) when it is selected, and a cell spanning rows or a row with more
+  columns than widths when it is read.
+- Anything that needs every row reads them all first: a table in a `row`, in a box with
+  `break_inside: :avoid`, or beside a float is measured whole, as an Array is.
+- An Enumerator with a column without a width is read when the table is built, as before: a
+  flexible column needs every row's width first. An Array is read as it always was.
+
+A price list with every width given, a header row and zebra stripes, `incremental: true`
+(`PAGES=3031 DOCUMENTS=streamed,listed FORMS=incremental bundle exec rake memory`, then
+`PAGES=30303`, same machine; and the objects the render allocates):
+
+| Rows | Pages | Rows given as | Peak | Alive when built | Alive when paginated | Objects |
+|---:|---:|---|---:|---:|---:|---:|
+| 100,000 | 3,031 | an Enumerator | 81 MB | 9 MB | 18 MB | 70.0 million |
+| | | an Array | 485 MB | 155 MB | 20 MB | 69.3 million |
+| 1,000,000 | 30,303 | an Enumerator | 130 MB | 9 MB | 47 MB | 710 million |
+| | | an Array | 2,758 MB | 1,474 MB | 64 MB | 702 million |
+
+Streamed, the rows cost the same at any length; what grows is what the file still needs of
+every page until it is written (47 MB alive after 30,303 pages), and the peak with it. A
+streamed table allocates a little more (reading an Enumerator one row at a time costs a few
+objects a row). A tagged render keeps the `TR`,
+`TH` and `TD` of every painted row in the structure tree until the file is written, streamed or
+not: streaming leaves out only the rows no page has reached, so the same 100,000 rows tagged
+peak at 989 MB streamed and 1,230 MB as an Array.
 
 Controllers gain `render pdf:` and `send_pdf`:
 
@@ -839,13 +1298,57 @@ The gem has no Rails dependency; the Railtie loads only inside a Rails app.
 stationery render app/pdfs/invoice_pdf.rb                # writes app/pdfs/invoice_pdf.pdf
 stationery render invoice.rb --out - > invoice.pdf       # PDF to stdout
 stationery render pdfs.rb --class InvoicePdf --strict    # pick one; fail on layout warnings
+stationery render invoice.rb --png                       # also invoice-1.png, … beside the PDF
+stationery render report.rb --png-only --pages 1,3-4 --dpi 144
+stationery render label.rb --zpl --dpi 300               # writes label.zpl for a label printer
 ```
 
 `render` loads the file and renders the `Stationery::Document` it defines. A
 document whose `initialize` needs arguments renders from `def self.preview`,
 which returns an instance built with sample data. Layout warnings print to
-stderr; `--strict` exits 1 instead of writing. `stationery help` lists the
-commands.
+stderr; `--strict` exits 1 instead of writing. `--zpl` writes ZPL instead of a
+PDF (see [Label printers](#label-printers-to_zpl)), at `--dpi` 152, 203 (the
+default), 300 or 600. `stationery help` lists the commands.
+
+`--png` writes a picture of each page beside the PDF with `to_png` (see
+[Pictures of a render](#pictures-of-a-render-to_png)), pure Ruby with nothing to
+install, named after the PDF with the number of the page, and prints one line
+per file (`wrote invoice-1.png (page 1, 794 x 1123 px)`), so an agent that
+rendered a document can open what it made. `--dpi` is 96 by default (an A4 page
+is 794 × 1123 px), `--pages` takes `2` or `1,3-4`, and `--png-only` writes the
+pictures without the PDF.
+
+```sh
+stationery inspect invoice.pdf                           # what is on each page, as text
+stationery inspect invoice.rb                            # render it first, with its warnings
+stationery inspect invoice.pdf --json                    # Inspector#layout as JSON
+```
+
+`inspect` prints what is on each page for an agent that cannot read a picture,
+and for a diff between two renders: the file's metadata, conformance claims,
+print hints, attachments and signatures, the outline, then each page with its
+size, its text lines (x, baseline y, font, size), images, links and form fields
+with their rectangles in points from the top-left corner, the structure tree of
+a tagged PDF and the warnings of the render. A section with nothing in it is
+left out, and the dates are, so two renders of one document print the same.
+It is `Inspector#layout` (see [Testing](#testing)) and needs the `pdf-reader`
+gem.
+
+```text
+examples/invoice.rb
+  pages     1
+  title     Invoice
+
+Page 1  595.3 x 841.9 pt
+  Text (x, baseline y, font, size, text)
+      44.0   65.5  OpenSans-Bold      22  Invoice INV-2026-042
+      44.0  115.6  OpenSans-Bold       9  Invoice date
+     134.0  115.6  OpenSans-Regular    9  26 September 2026
+  Images (x, y, width x height, pixels)
+     437.9   40.0  113.3 x 34  240 x 72 px
+  Links (x, y, width x height, target)
+     329.2  596.5  65.6 x 11.6  mailto:hello@acme.test
+```
 
 ```sh
 stationery fonts list                                    # packs, licenses, what is in vendor/fonts
@@ -860,6 +1363,36 @@ already present are kept unless `--force`. `--from` takes a directory or a
 `.tar.gz` holding the same files (still SHA-checked). In Rails,
 `bin/rails generate stationery:fonts noto_sans` does the same.
 
+```sh
+stationery examples                                      # the examples in the gem, what each shows
+stationery examples invoice                              # the path of examples/invoice.rb there
+stationery examples invoice --source                     # its code
+```
+
+`examples` lists the documents under `examples/` of the installed gem with the
+first sentence of their header comment. With a name it prints the path of that
+file, to read, copy or hand to `stationery render`.
+
+```sh
+stationery skill install                                 # the skill for the agents it finds, else Claude Code
+stationery skill install --target claude --project       # into ./.claude/skills/stationery
+stationery skill install --dir ~/agent-skills            # into any skills directory
+stationery skill status                                  # current, outdated or missing, per agent
+stationery skill print                                   # SKILL.md and its files, as one document
+```
+
+`skill install` writes the skill for coding agents that ships with the gem: a
+`SKILL.md` and the reference and recipe files beside it, written from this
+README and the examples for the version installed, with that version in its
+front matter. `--target` is `claude` (`~/.claude/skills`), `codex`
+(`~/.codex/skills`), `agents` (`~/.agents/skills`, read by OpenCode and others)
+or `all`; without it the skill goes to each of them whose directory is there,
+and to Claude Code when none is. `--project` writes under the current directory
+instead of the home directory. A skill named `stationery` that the gem did not
+write is kept unless `--force`. `skill status` says for each agent whether the
+skill there is current, outdated (written for an older version: install it
+again) or missing.
+
 ## Fonts and images
 
 Fonts are TrueType (`.ttf`) or OpenType/CFF (`.otf`, name-keyed or
@@ -924,7 +1457,9 @@ a figure space, a narrow no-break space, …) is drawn as a blank of the
 character's conventional width, never as `.notdef`. Any other glyph no font
 has is drawn as the family's `.notdef` and reported as a
 `Warnings::MissingGlyph` counting each drawn occurrence (so `strict` raises
-on it, and a `conformance` level raises `ConformanceError`). The characters
+on it, and a `conformance` level raises `ConformanceError` unless it is
+declared with `missing_glyphs: :replace`, which draws the first of U+FFFD,
+U+25A1 and `?` the font has instead; see [PDF/A and PDF/UA](#pdfa-and-pdfua)). The characters
 themselves travel as the `ActualText` of a `Span` around the glyphs, so the
 text still extracts, copies and reads aloud as written. Fallback covers every text element,
 table cell, list marker, table of contents entry and page template text;
@@ -987,6 +1522,17 @@ before embedding it, alpha included; a JPEG is embedded byte for byte, so
 resize it before you embed it (an ActiveStorage variant per drawn size,
 preprocessed, keeps a render to a download).
 
+A JPEG's pixels are decoded in Ruby only where pixels are needed, for
+`to_png` and a `monochrome` render; a PDF embeds its bytes. Baseline,
+extended and progressive JPEGs are decoded (every chroma subsampling,
+restart intervals, grey, RGB, YCbCr, CMYK and YCCK, CMYK turned into RGB)
+to the pixels libjpeg-turbo gives them, and a photo drawn small at a half, a
+quarter or an eighth of its size (libjpeg's scaled IDCT). A lossless,
+arithmetic-coded, hierarchical or 12-bit JPEG, or one of more than 33 megapixels, is not:
+a picture draws it as a crossed box and a monochrome PDF embeds it as it is,
+each with a warning. The EXIF orientation is not applied, as the PDF does
+not apply it either.
+
 ### Complex scripts: the shaper hook
 
 Stationery places glyphs itself: one per character, the font's ligatures and single substitutions,
@@ -1046,7 +1592,8 @@ synthetic oblique, a superscript or letter spacing. Glyphs the shaper placed are
 not a character maps to them. Where the ToUnicode map cannot give the text (glyphs out of logical
 order, several glyphs for one cluster, a glyph that already stands for another text, glyph 0) the
 glyphs are shown in a `Span` whose `ActualText` is the characters in logical order. Glyph 0 is
-reported as a `Warnings::MissingGlyph`, like any other.
+reported as a `Warnings::MissingGlyph`, like any other, and under `conformance` with
+`missing_glyphs: :replace` it is drawn as the font's stand-in at the stand-in's advance.
 
 The limits of a hook:
 
@@ -1062,18 +1609,63 @@ The limits of a hook:
 - Hyphenation and the breaking of a word wider than the line cut the text as written; the pieces are
   shaped as separate words.
 - Vertical advances are not read: text runs horizontally.
-- A reader that takes `ActualText` for the text (the gem's `Inspector`) gets it as written. poppler
-  (`pdftotext` 26.09) and MuPDF (1.28) run their own reordering over it and return a right-to-left
-  stretch reversed. pdf-reader's own `Page#text` drops a `Span` whose first glyph has no advance (a
-  mark drawn first); the `Inspector` does not.
+- Extracted text depends on the reader: the gem's `Inspector` and PDFium get a right-to-left stretch
+  as written, poppler and MuPDF reversed (see the table below). pdf-reader's own `Page#text` drops a
+  `Span` whose first glyph has no advance (a mark drawn first); the `Inspector` does not.
 
 [`examples/shaping/harfbuzz_shaper.rb`](https://github.com/zoolutions/stationery/blob/main/examples/shaping/harfbuzz_shaper.rb)
 is an adapter for HarfBuzz through the [`harfbuzz-ruby`](https://github.com/ydah/harfbuzz) gem
 (`gem "harfbuzz-ruby"`, `require "harfbuzz"`; not the older `harfbuzz` gem, which answers to the same
 `require`), about a hundred lines to copy into an application; stationery does not depend on it. It
-was run with harfbuzz-ruby 1.1.0 and HarfBuzz 14.5.0 against Noto Sans Arabic and draws joined,
-right-to-left Arabic with its marks and with left-to-right digits inside it. It cuts a stretch into
-runs of one direction by its letters alone, not by the Unicode bidirectional algorithm.
+was run with harfbuzz-ruby 1.1.0 and HarfBuzz 14.5.0 against Noto Sans Arabic, Amiri and Noto Sans
+Hebrew and draws joined, right-to-left Arabic with its marks and with left-to-right digits inside it.
+It cuts a stretch into runs of one direction by its letters alone, not by the Unicode bidirectional
+algorithm.
+The base direction of a stretch is its first letter's, so a line of an Arabic paragraph that starts
+with a number stays right to left.
+[`examples/shaping/rtl_letter.rb`](https://github.com/zoolutions/stationery/blob/main/examples/shaping/rtl_letter.rb)
+is a letter in Arabic set with it (`ARABIC_FONT=NotoNaskhArabic-Regular.ttf ruby -Ilib
+examples/shaping/rtl_letter.rb`); its booking number, in Latin letters from Inter, sits in a `row`
+beside its Arabic label, since stretches of two fonts on one line are placed left to right.
+
+What comes out of a shaped PDF depends on who reads it, and no way of writing right-to-left text
+is read as written by every extractor. Seven texts (Arabic, Hebrew, Arabic with digits in it,
+Arabic with its marks, an Arabic word in a Latin sentence, a justified paragraph, a line that wraps)
+were rendered three ways and read back: **A**, what the gem writes, a `Span` around the stretch
+with its text in logical order as `ActualText` (ISO 32000-1, 14.9.4); **B**, a `Span` for every
+cluster, in visual order; **C**, no `Span` for a glyph the ToUnicode map gives its text, in visual
+order, and one per cluster for the others. The cells count the texts that came back as written:
+
+| Arabic font | | `Inspector` | PDFium | PDFKit | pdf.js | poppler | MuPDF |
+|---|---|---|---|---|---|---|---|
+| Amiri (a glyph per letter) | **A** | 7 of 7 | 7 of 7 | 6 of 7 | 4 of 7 | 0 of 7 | 0 of 7 |
+| | B | 0 of 7 | 0 of 7 | 0 of 7 | 0 of 7 | 4 of 7 | 5 of 7 |
+| | C | 0 of 7 | 1 of 7 | 6 of 7 | 4 of 7 | 4 of 7 | 5 of 7 |
+| Noto Sans Arabic (a letter is its shape and its dots) | **A** | 7 of 7 | 6 of 7 | 1 of 7 | 1 of 7 | 0 of 7 | 0 of 7 |
+| | B | 0 of 7 | 0 of 7 | 0 of 7 | 0 of 7 | 1 of 7 | 1 of 7 |
+| | C | 0 of 7 | 0 of 7 | 1 of 7 | 1 of 7 | 1 of 7 | 1 of 7 |
+
+- PDFium (153.0.7999, what Chrome reads with, through pypdfium2 5.13) and the gem's `Inspector`
+  return `ActualText` as it is: A reads as written. Without it (C) PDFium returned the words of a
+  right-to-left line in reverse order.
+- poppler (`pdftotext` 26.09) and MuPDF (`mutool` 1.28.5) reorder what they read, `ActualText`
+  included: A comes back reversed, B and C in Amiri as written, but for Arabic with digits or
+  marks and, in poppler, a justified paragraph.
+- pdf.js (pdfjs-dist 6.3.289) and PDFKit (macOS 27, what Preview reads with) returned the same for
+  A and C, which differ in nothing but `ActualText`: they read the glyphs through the ToUnicode
+  map and reorder them. A cluster of several glyphs comes back with its text once per glyph, so a
+  letter with a mark is doubled, and so is every dotted letter of the Noto Arabic families (Sans,
+  Naskh and Kufi draw a letter as two glyphs). Only `ActualText` carries the text of such a font.
+- The Hebrew text (Noto Sans Hebrew) is the same in both halves of the table.
+- veraPDF 1.30.2 passes all 42 renders as PDF/UA-1, so the rules of the standard do not choose.
+- Acrobat, Preview itself and screen readers were not tested.
+
+The gem keeps A: it is what the specification describes, the one PDFium reads as written, and
+the only one that holds with a font whose glyphs are not letters. None of the three is read as
+written by poppler or MuPDF and by PDFium.
+[`examples/shaping/extraction_matrix.rb`](https://github.com/zoolutions/stationery/blob/main/examples/shaping/extraction_matrix.rb)
+renders the texts, holds B and C as experiments and writes the table again, with what to install
+at its head.
 
 ## Testing
 
@@ -1106,6 +1698,8 @@ RSpec.describe InvoicePdf do
   it { is_expected.to have_no_warnings }
   it { is_expected.to have_pdf_language("en") } # the catalog /Lang from `metadata lang:`
   it { is_expected.to have_page_labels(%w[i ii 1 2]) } # from `page_labels`
+  it { is_expected.to have_print_preference(scaling: :none, copies: 2) } # from `print`
+  it { is_expected.to have_pdf_colors("#000000") } # every colour it paints with, from `monochrome`
   it { is_expected.to have_attachment("factur-x.xml", mime: "text/xml", relationship: :alternative) }
   it { is_expected.to have_conformance(:pdf_a3b) } # the level claimed in XMP, from `conformance`
   it { is_expected.to have_factur_x(profile: :en16931) } # the e-invoice XML, named in XMP and embedded
@@ -1133,6 +1727,8 @@ class InvoicePdfTest < Minitest::Test
     assert_no_pdf_warnings pdf
     assert_pdf_language pdf, "en"
     assert_page_labels pdf, %w[i ii 1 2]
+    assert_print_preference pdf, scaling: :none, copies: 2
+    assert_pdf_colors pdf, ["#000000"]
     assert_pdf_attachment pdf, "factur-x.xml", mime: "text/xml"
     assert_pdf_conformance pdf, :pdf_a3b
     assert_factur_x pdf, profile: :en16931
@@ -1149,7 +1745,8 @@ titles. The RSpec matchers compose like the built-ins: `.and` / `.or`, and insid
 `all`, `include` or `match`. For anything else, `Stationery::Testing::Inspector.new(subject)`
 exposes `text`, `page_texts`, `page_count`, `links`, `internal_links`,
 `image_count`, `bookmarks`, `metadata`, `xmp` (the packet), `xmp_values` (`{ "dc:title" => …, "dc:creator" => […] }`),
-`lang`, `page_labels`, `attachments`, `conformance` (`[:pdf_a3b, :pdf_ua1]`), `factur_x`
+`lang`, `page_labels`, `print_preferences` (`{ scaling: :none, pages: [1..3] }`), `colors`
+(`["#000000", "#FF0000"]`), `attachments`, `conformance` (`[:pdf_a3b, :pdf_ua1]`), `factur_x`
 (`{ profile:, filename:, version:, xml: }`), `signatures` (`[{ field:, name:, reason:, location:,
 signed_at:, subfilter:, byte_range:, signer:, valid:, timestamp: }]`, the timestamp `nil` or
 `{ time:, tsa:, valid: }`), `warnings`, `tagged?`,
@@ -1159,6 +1756,12 @@ read from its marked content: `[type, "text"]`, `[type, [children]]` (its own te
 between the children, as for a `P` holding a `Link`) or `[type]` when empty; a
 `Figure` reads as its alt text.
 
+`colors` is every colour the page content and the form XObjects it draws set with `g`, `rg` and `k`
+(and their stroking forms), once each and sorted, as `"#RRGGBB"` (CMYK converted without a profile),
+with `"shading"` for a gradient and `"image"` for a bitmap that is not one bit of grey; a one-bit grey
+image, as `monochrome` embeds, paints black and white only and adds nothing. Opacity and form
+fields are not read. `have_pdf_colors("#000000")` and `assert_pdf_colors` hold the whole list.
+
 `text` and `page_texts` are the text of the page content as pdf-reader lays it out, line by line. A
 `Span` with `ActualText` (a stretch a shaper reordered, characters no font has) reads as that text,
 once, whatever glyphs it shows.
@@ -1173,6 +1776,29 @@ of every widget that is not hidden, in the state the widget is in, and never a b
 text is what it always was, and the failure of `have_pdf_text` over a text that a field shows says
 so.
 
+`Inspector#layout` is what is on each page and what the file says of itself, as plain data in a
+stable order: what `stationery inspect` prints (see [CLI](#cli)), for a spec that asks where
+something landed. Places are in points from the top-left corner of the page, as the gem's API
+speaks, rounded to a tenth; a text line's `y` is its baseline.
+
+```ruby
+layout = Stationery::Testing::Inspector.new(InvoicePdf.new(invoice)).layout
+layout[:pages].first[:text].first
+# => { x: 44.0, y: 65.5, font: "OpenSans-Bold", size: 22.0, text: "Invoice INV-2026-042" }
+layout[:pages].first.keys  # => [:number, :label, :width, :height, :text, :images, :links, :fields]
+layout.keys                # => [:metadata, :conformance, :tagged, :print, :outline, :attachments,
+                           #     :signatures, :structure, :warnings, :pages]
+```
+
+A text line is a run of one font and size on one baseline, so a word set in bold is a line of its
+own; lines read top to bottom, then left to right. An image is `{ x:, y:, width:, height:, pixels:
+[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:` and, for a button, the `state:` that turns
+it on. `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.
+
 ## Why not Prawn, Chrome or Typst?
 
 - **Prawn** is an imperative cursor API: every document does its own layout
@@ -1225,26 +1851,28 @@ events attached is the most useful thing to put in an issue.
 prawn-table, and with [sghtmltopdf](https://github.com/waka/sghtmltopdf) 0.5.1, an
 HTML-to-PDF engine written in Rust, given HTML/CSS twins of the same documents. Every
 engine embeds the same Open Sans TTF files (`benchmark/`, not part of CI). Apple M2 Max,
-Ruby 3.4.2 +YJIT, 28 September 2026, warm caches, the best of three runs:
+Ruby 3.4.2 +YJIT, 29 September 2026 (0.12.0), warm caches, the best of three runs:
 
 | Document | Engine | Best render | Renders/s | Objects allocated | PDF bytes | Pages |
 |---|---|---:|---:|---:|---:|---:|
-| Invoice (`examples/invoice.rb`) | Stationery | 13.1 ms | 70.1 | 39,562 | 26,599 | 1 |
-| | Prawn | 18.3 ms | 45.2 | 88,558 | 33,034 | 1 |
-| | sghtmltopdf | 3.4 ms | 259.4 | 53 | 36,693 | 1 |
-| Table, 1,500 rows × 5 columns, repeating header | Stationery | 395 ms | 2.45 | 2,596,598 | 133,754 | 46 |
-| | Prawn | 1,373 ms | 0.71 | 6,901,807 | 2,689,487 | 40 |
-| | sghtmltopdf | 96 ms | 9.99 | 53 | 369,338 | 45 |
-| Cover photo and six illustrated sections | Stationery | 9.0 ms | 99.8 | 45,866 | 41,531 | 3 |
-| | Prawn | 29.7 ms | 30.9 | 102,967 | 55,391 | 2 |
-| | sghtmltopdf | 6.7 ms | 136.8 | 53 | 43,031 | 2 |
-
-sghtmltopdf is the fastest: 3.9x Stationery on the invoice, 4.1x on the table and 1.3x on
-the photo document. That is native code against Ruby, and its 53 objects are the binding's:
-the engine allocates outside the Ruby heap. Stationery is 1.4x, 3.5x and 3.3x faster than
-Prawn and writes the smallest files of the three (28%, 64% and 3% smaller than
-sghtmltopdf's). Stationery compresses content streams; Prawn does not by default, hence its
-larger files. Page counts differ where the engines' line heights and table padding do.
+| Invoice (`examples/invoice.rb`) | Stationery | 11.3 ms | 79.7 | 27,531 | 26,601 | 1 |
+| | Prawn | 17.6 ms | 49.0 | 88,558 | 33,034 | 1 |
+| | sghtmltopdf | 3.2 ms | 293.8 | 53 | 36,693 | 1 |
+| Table, 1,500 rows × 5 columns, repeating header | Stationery | 205 ms | 4.46 | 1,276,408 | 133,756 | 46 |
+| | Prawn | 1,299 ms | 0.74 | 6,901,819 | 2,689,487 | 40 |
+| | sghtmltopdf | 94 ms | 10.05 | 53 | 369,338 | 45 |
+| Cover photo and six illustrated sections | Stationery | 6.8 ms | 136.3 | 25,977 | 41,533 | 3 |
+| | Prawn | 26.9 ms | 31.0 | 102,961 | 55,391 | 2 |
+| | sghtmltopdf | 6.6 ms | 140.2 | 53 | 43,031 | 2 |
+
+sghtmltopdf is the fastest on text and tables: 3.5x Stationery on the invoice and 2.2x on the
+table, and level with it on the photo document (6.6 against 6.8 ms). That is native code against
+Ruby, and its 53 objects are the binding's: the engine allocates outside the Ruby heap. Stationery
+is 1.6x, 6.3x and 4.0x faster than Prawn and writes the smallest files of the three (28%, 64%
+and 3% smaller than sghtmltopdf's). Stationery compresses content streams; Prawn does not by
+default, hence its larger files. Against 0.11.0, the same three renders allocate 30% to 51% fewer
+objects and take 14%, 48% and 24% less time. Page counts differ where the engines' line heights
+and table padding do.
 "Best render" is the fastest single render, the figure other work on the machine disturbs
 least; renders per second is the average over five seconds.
 
@@ -1261,14 +1889,31 @@ 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.
+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
+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).
 
 Time depends on the machine, so CI holds what does not: `bundle exec rake metrics`
-renders six fixed documents and compares the objects each render allocates, its
+renders fourteen fixed documents and compares the objects each render allocates, its
 page count and its bytes with `benchmark/baseline.json` (allocations may grow 3%,
 bytes 1%, pages not at all). A change that moves them on purpose records a new
 baseline with `bundle exec rake metrics:update` and says why in the commit.
 
+| Document | What it holds |
+|---|---|
+| `invoice`, `flyer`, `form` | The examples of those names: a table with a footer, images and drawings, form fields |
+| `table` | 1,500 rows × 5 columns with a repeating header, 46 pages |
+| `text`, `text_hyphenated`, `text_streamed` | Ten pages of headings and paragraphs: as they are, justified and hyphenated, and written to a block |
+| `article` | Floats: `examples/article.rb` |
+| `newsletter` | `columns`: `examples/newsletter.rb` |
+| `webp` | A lossless WebP of 320 × 240 px, decoded in the render that is measured |
+| `html` | `html` with a stylesheet, inline styles, a floated image, a table, lists and two columns, five pages |
+| `pdf_ua` | A tagged report under `conformance :pdf_ua1`, six pages |
+| `text_incremental` | The text document with a footer, rendered with `incremental` to a block |
+| `text_shaped` | The text document through a `shaper` written in Ruby, which answers the font's own glyphs |
+
 `bundle exec rake memory` reports what long documents hold while they render
 (`PAGES=5000` for more than its 1,000 pages): the peak resident set size of a render in
 a fresh process, and what is alive when building, pagination and writing end. It
@@ -1283,9 +1928,11 @@ Fonts: no variable fonts (including CFF2) and no WOFF2 (it needs Brotli; convert
 nothing and scripts that need contextual shaping (Arabic, Indic, Thai) draw glyph by glyph unless the
 application brings a shaper (`shaper`, see [the shaper hook](#complex-scripts-the-shaper-hook): the gem
 shapes none of them itself), and colour or emoji glyphs no font
-in the chain has are drawn as `.notdef` and reported. Text runs left to right: a shaper orders the glyphs
+in the chain has are drawn as `.notdef` and reported (under a conformance level they raise, or are drawn
+as a stand-in with `missing_glyphs: :replace`). Text runs left to right: a shaper orders the glyphs
 within a stretch of one font and style, nothing reorders stretches or lines (CJK text wraps between
-ideographs, but there is no vertical layout); hyphenation
+ideographs, but there is no vertical layout), and poppler and MuPDF extract shaped right-to-left text
+reversed (see [the matrix](#complex-scripts-the-shaper-hook)); hyphenation
 patterns are bundled for English, German and Swedish only (a soft hyphen works in any language),
 and justification only widens spaces.
 
@@ -1295,7 +1942,7 @@ and reported, text inside a `clipPath` does not clip, and the shapes of a clip p
 path, so overlapping shapes wound in opposite directions cancel where they overlap.
 Images are JPEG, PNG (non-interlaced) and lossless WebP (not lossy or animated WebP, and no more
 than 33 megapixels) and never fetched from a URL; a JPEG is embedded at its
-source resolution (only PNG and WebP can be downscaled), so an oversized one is reported, not resized. `html` reads a fixed subset of CSS (colours, sizes, weights, alignment, margins, padding, table
+source resolution (only PNG and WebP can be downscaled), so an oversized one is reported, not resized; a lossless, arithmetic-coded, hierarchical or 12-bit JPEG, or one of more than 33 megapixels, is not decoded for `to_png`, `to_zpl` or `monochrome`. `html` reads a fixed subset of CSS (colours, sizes, weights, alignment, margins, padding, table
 borders and widths, page breaks; see [What CSS is read](#what-css-is-read)), not a layout
 engine's worth: no `display`, positioning, `font-family`, `auto` or negative margins or selectors
 with combinators, and floats for images only, with their `margin` around them.
@@ -1309,20 +1956,33 @@ height balanced for it and the columns after it, so one that ends above a block
 split may stay shorter than the column after it. It has columns of one width, nothing spanning
 them (end the block, write the full-width content, start another) and no column break of its
 own; a spacer that lands at the top of a column keeps its height. Text
-wraps around floated images and boxes, along their rectangles, never along a shape; beside a float
-a table, a row, `columns` and a box with a background, a border or a size of its own are blocks of
-the width that is left, all the way down: a box is painted after the float written before it, so
-one that kept the full width would paint its background over the float (see
-[Floats](#floats)). Link and form-widget rectangles stay in page space inside `rotate`
+wraps around floated images and boxes, along their rectangles, never along a shape; the text
+after floats cut by a page break goes to the next page with the float that moved, never beside
+those that stayed; beside a float
+a table, a row, `columns` and a box with a size of its own are blocks of the width that is left,
+all the way down, where a box with a background wraps: a table resolves its column widths from
+its width, a row shares its width between its columns and `columns` divides it, and none of them
+can be laid out again at another width from some row on, which widening below the float would
+take (see [Floats](#floats)). A table reads its rows as pages reach them only from an Enumerator
+with a width for every column, and then refuses what needs its end (a row counted from the end, a
+cell spanning rows); in a `row`, in a box with `break_inside: :avoid` or beside a float it is read
+whole first (see [Large documents](#large-documents)). Link and form-widget rectangles stay in page space inside `rotate`
 and `transform`, and `shadow:` is stacked rectangles, not a blur.
 
-PDF: PDF/A-2b, PDF/A-3b and PDF/UA-1 only (no PDF/A-1, no level A or U, no PDF/UA-2, no PDF/X) and
-no JavaScript. A render carries one signature (`/ETSI.CAdES.detached`, RSA or EC with SHA-256):
+PDF: PDF/A-2b, PDF/A-3b and PDF/UA-1 only (no PDF/A-1, no level A or U, no PDF/UA-2, no PDF/X),
+no JavaScript and no action but links and the print dialog (`print dialog: :on_open`). Under PDF/UA-1 a
+link in the header row a table repeats on its next pages, and `canvas.link` without a `tag:`, raise: they
+are outside the structure tree. A render carries one signature (`/ETSI.CAdES.detached`, RSA or EC with SHA-256):
 no long-term validation data (PAdES B-LT), no second signature and no signing
 of a file that already exists, all of which need incremental updates.
 Form fields are set in the document's fonts, but text typed into one is drawn by the viewer:
 characters outside the glyphs the field kept (ASCII and Latin-1) use the viewer's own font.
 
+Pictures and labels: `to_png` and `to_zpl` draw no form fields (their widget is the viewer's), and
+`to_zpl` sends each page as one graphic field, with only barcodes as the printer's own commands (no
+`^GB` rules or boxes, no printer fonts). The labels were compared with `to_png` and rendered by a ZPL
+viewer, not printed by the gem's specs.
+
 ## License
 
 MIT. The PDF writer, TrueType subsetter and image decoders are derived from