stationery 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7df6bdee0612f0952d1fb587f64720fb78d976e77b7327292dd261b5afbe14d7
-  data.tar.gz: 9c9c800f4c4a5aea772df63676eeb5936a3282828eec401494256d1691cae30b
+  metadata.gz: f9ff43b2013eb330ebc103525c440bb5e4cfdaf0d05364baf47fd329c48ad11a
+  data.tar.gz: 718ede92892d3c7c0cdc556708880a2ba53f559611b872cfcb8ac946adb59908
 SHA512:
-  metadata.gz: ea8fa33394b8f68a0316d0bba056e97d48bee53db8ffd4b8addb9aea023b0d492f42c34884408d0771c136993bcc1249eb2064bfbe0f11cecb00aa52bc1561e0
-  data.tar.gz: dc14973b6ca838dd0be5651dc0cb51b404e8c0e3fe5958ad1edcac3dad9026ad6a66a13c21d15bb01483412a651a9aafad655c047d9c73868405d123608d1daa
+  metadata.gz: b3a4a85b185b0f06e195a15f81773c86d79086e32e923b1c21c2d39ee528375fd5b75be1581fc3d8180e530071d653939674804c973896d0edb3b57fffbde9fa
+  data.tar.gz: fd368b63884a129cd0e6f03507da714891c79b81b6a1aeadde9cfeafc4987824d7cd525c2f86aa3eba397f432a14516429bc697b61177056a790a602d85369ae

data/CHANGELOG.md

@@ -1,6 +1,119 @@
 # Changelog
 
-## 0.1.0 (unreleased)
+## 0.3.0 (2026-09-27)
+
+The Limitations page, shortened: TrueType collections, WOFF, ligatures, splittable
+`min_height:` boxes, SVG gradients, text and stylesheets, and encryption.
+
+- SVG: `linearGradient` and `radialGradient` fills (`fill="url(#id)"`, also in `style`), with stops, `href`/`xlink:href` inheritance, `objectBoundingBox` and `userSpaceOnUse` units and `gradientTransform`, drawn as PDF axial/radial shadings clipped to the shape. Approximations: `reflect`/`repeat` spreads are drawn as `pad` (reported in `unsupported`), stop opacity is the first stop's for the whole gradient, and a gradient stroke is drawn in the gradient's middle colour. A reference to a missing gradient paints its fallback colour or nothing and is reported as `url(#id)`. `Canvas#shade` paints a shading dictionary inside a path.
+- SVG: `text` and `tspan` (`x`/`y`/`dx`/`dy`, first value each; `font-family`, first family the font book knows — registered, bundled or an installed pack — else the document's default; `font-size`, `font-weight`, `font-style`, `text-anchor`, `fill`, `opacity`, transforms), drawn through the document's fonts so they subset and extract like any text. Whitespace collapses as in browsers. Glyphs stay upright: a transform moves the baseline origin and scales the size uniformly, so rotated or skewed text is approximated; `dominant-baseline` is ignored and a gradient fill uses its middle colour. `Layout::Svg` takes `context:`, `SVG::Document#draw` takes `book:` and `family:`, and `FontBook#known?` tells whether a family resolves without substitution.
+- SVG: `<style>` stylesheets (plain or CDATA) as Illustrator and Inkscape export them. Selectors: element, `.class` (`.a.b`), `#id`, `element.class`, comma lists and `*`; rules with combinators (`g path`, `a > b`, …) are ignored and reported once as `style selectors: …`. Cascade: presentation attributes, then rules by specificity (id > class > element, later wins on ties), then inline `style`. Rules style shapes, text (`font-*`) and gradient stops (`stop-color`, `stop-opacity`); `display: none` skips an element and its children, `visibility: hidden` skips it (a `visible` child draws). `class` takes several classes.
+
+- Encryption with the standard security handler: `to_pdf(encrypt: { owner_password:, user_password:, permissions:, algorithm: })` or `encrypt …` at class level (`to_pdf(encrypt: nil)` opts out). AES-256 (R6, default), AES-128 (R4) and RC4-128 (R3); every string and stream, document info included, is encrypted.
+
+- Standard ligatures from the font's GSUB `liga` feature (LigatureSubst lookups, also behind Extension lookups), **on by default**: "office" in Open Sans draws the ffi ligature, so widths of affected words change slightly. `ligatures: false` on `text`/`text_style` or in `default_text` opts out; any `letter_spacing` turns them off. Text extraction and copy still yield the source characters (ToUnicode maps a ligature glyph to all of them). Fonts without `liga` ligatures, such as the bundled Inter, are unaffected.
+
+### Fonts
+
+- TrueType collections (`.ttc`): `font_family "Brand", regular: "Brand.ttc#0", bold: "Brand.ttc#2"` picks a face by a `#N` suffix (face 0 without one); each face is parsed, cached, subset and embedded on its own. `TrueType.new(data, index:)`, `TrueType.collection?` and `TrueType.faces`; an index out of range raises `ArgumentError` naming the face count.
+- WOFF 1.0 web fonts (`.woff`): `font_family "Web", regular: "Brand.woff"`. Tables are inflated with zlib into an in-memory sfnt (`Fonts::WOFF.unpack`), then measured, subset and embedded like the `.ttf`. WOFF2 is still rejected: it needs Brotli, so convert to `.ttf` or `.woff`.
+
+- `box(min_height:)` and `column(min_height:)`: a height floor that, unlike `height:`, still splits across pages. The first fragment keeps as much of the floor as the page holds and the next carries the rest, so a row of equal-height cards or an empty signature area can span a page break. Passing both `height:` and `min_height:` raises `ArgumentError`.
+
+## 0.2.0 (2026-09-27)
+
+Everything from the three planned milestones ("works out of the box", "typography and layout",
+"documents, Rails and testing") shipped together.
+
+### Breaking changes
+
+- **Behaviour change:** boxes taller than a page now continue on the next page instead of overflowing; pass `break_inside: :avoid` for the old behaviour. A box that fits on a page still moves there whole; `break_inside: :auto` splits it at any page break. `box(decoration: :slice | :clone)` chooses whether padding repeats at a cut; borders are left open and rounded corners cut square.
+- Pair kerning from the font's `kern` table, **on by default**: measured widths shift slightly (kerned lines only get narrower), so wrapping and right-aligned positions can move by a fraction of a point. `kerning: false` on `text`/`text_style` or in `default_text` restores unkerned output. Pairs across a style or font change are not kerned.
+
+### Fonts
+
+- Inter (OFL) is bundled: documents render without any `font_family`; `font_family "Inter"` needs no paths; `Stationery.bundled_fonts`. An unknown family name without paths raises.
+- Font packs: `stationery fonts list` and `stationery fonts install noto_sans liberation_serif [--into DIR] [--force] [--from PATH]` copy pinned, SHA-256-verified Noto Sans/Serif/Sans Mono, Liberation Sans/Serif/Mono and Inter files (plus their OFL license) into `vendor/fonts/<pack>/`, atomically and offline-capable. `font_family "Noto Sans"` with no paths finds an installed pack through `Stationery.font_paths`, as does an unregistered family name at render time. Ruby API `Stationery::Fonts.install`/`catalog`/`paths`, Rails generator `stationery:fonts`, and `rake fonts:verify`. No runtime downloads.
+- Per-character font fallback: `font_fallbacks "Noto Sans Symbols", ...` (inherited by subclasses). A character missing from the text's family is drawn from the first fallback that has it, then bundled Inter; spaces, joiners and combining marks stay with their base. Glyphs no font has are reported as `MissingGlyph` warnings counted per drawn occurrence. `Font#glyph?` is memoised per character.
+- GPOS pair kerning: the `kern` feature's PairPos lookups (formats 1 and 2, also behind Extension lookups) take precedence over the `kern` table, so GPOS-only fonts such as Inter are kerned too.
+- OpenType fonts with CFF outlines (`.otf`), name-keyed and CID-keyed: embedded whole as a CIDFontType0 (`FontFile3 /OpenType`), CID-keyed text written as CIDs with the font's ROS. Variable CFF2 fonts are rejected with a named reason.
+- CFF fonts are subset: undrawn glyphs become a bare `endchar` (glyph ids, charset, FDSelect, Private DICTs and Subrs kept), embedded as `FontFile3 /CIDFontType0C` with a subset tag.
+
+### Text
+
+- `align: :justify` on `text`, `text_style` and table cells: wrapped lines are stretched to the full width by widening their spaces (kerning is kept); the last line, lines ending in a newline and lines without spaces stay left-aligned. Link areas widen with the stretched text.
+- `html` and `markdown` elements: ActionText/Trix HTML and CommonMark (GFM tables and strikethrough) rendered as paragraphs, headings, lists, blockquotes, code blocks, rules, tables and images with inline bold/italic/underline/strike/code/links/sub/sup. `styles:` deep-merges per-block defaults, `images:` resolves image sources (or `base_path:`), missing/remote images are skipped with a `SkippedImage` warning and never fetched, `bookmarks: true` outlines h1–h3. Parsers load on first use.
+- Markup decodes all 252 HTML 4 named entities (`&mdash;`, `&euro;`, `&hellip;`, …); the table loads on first use.
+- Internal: `Stationery::Rich` block model (paragraphs, headings, lists, quotes, code, rules, tables, images; inlines with marks) with lenient `HTML.parse` (implied end tags, browser whitespace collapsing, Trix/ActionText output) and CommonMark-subset `Markdown.parse` (GFM tables and strikethrough, reference links). Loaded on demand; `html`/`markdown` elements follow.
+- Internal: `Fonts::GlyphRun` carries per-glyph advance adjustments (Tj/TJ emission) for upcoming kerning and justification; output unchanged.
+
+### Layout
+
+- `ul` / `ol` / `li` lists: drawn (disc, circle, square) or text bullets (dash, any String), decimal / alpha / roman / Proc numbering, `start:` and `suffix:`, aligned bodies, nested lists with depth-cycled bullets, and items that split across pages keeping the marker with their first line.
+- `box(break_inside:)` and `column(break_inside:)`.
+- Rows split across pages like boxes, every column at the same break; a column that ends early continues as an empty fragment so backgrounds stay aligned. `row(break_inside:)`.
+- `keep_with_next` now moves with a following node that avoids breaking inside and would not start on the page.
+- `wrap` element: children at their own widths, wrapping onto rows; splits between rows.
+- `box(link:)` makes the whole box clickable; `box(outset:)` bleeds its background past its edges.
+- `keep_with_next:` accepts a number of points of following content to keep.
+- `group(align:)`.
+- Fixed-width children of a flow (`box(width:)`) are measured, split and paginated at their own width, not the flow's.
+- Layout: `split` takes `fresh:` on every node; a flow passes it on to the child that starts a fresh page.
+
+### Tables
+
+- Table cells span columns and rows: `{ content:, colspan:, rowspan: }`, placed as in HTML; a table only splits between rows no rowspan crosses.
+- A table row taller than the page continues on the next page below the repeated header, its cells cut at the page bottom; `table(split_rows: true)` cuts any row that reaches the page bottom rather than moving it whole.
+- Table cells accept procs built with the DSL (`-> { image logo }`) and components.
+- Faster tables: cell padding is normalised once per cell, and PDF numbers are trimmed without a regexp (about 13% off a 1,500-row table render).
+
+### Pages and structure
+
+- `header` and `footer` regions that reserve page space, with `height:`, `gap:` and `on:` (`:all`, `:first`, `:rest`, `:odd`, `:even`, a page number, a range or a proc); later declarations win. A `page_template`'s `page.content_box` now excludes their space. `Page#margin_box`.
+- `header`/`footer` `on: :last`: the paginator checks whether the rest of the content fits above a taller last-page region, adding a page when it only fits a normal one.
+- Named anchors and internal links: `anchor:` on `text`, `box`, `group` and `table`, a standalone `anchor` element, and `link: "#name"` / `<a href="#name">` / `box(link: "#name")` written as PDF `/Dest` GoTo links. Unknown targets are dropped with an `UnresolvedLink` warning; duplicate names warn with `DuplicateAnchor`.
+- Bookmarks and document outline: `bookmark:` on `text`, `box`, `group` and `table` (a title, or `{ title:, level:, open: }`) and a standalone `bookmark` element write a nested PDF `/Outlines` tree; the document opens with the outline panel. Bookmarks in page templates are ignored.
+- `table_of_contents` element: one linked row per bookmark with its title indented by level, a dotted/solid leader and a right-aligned page number filled in after pagination (`levels:`, `leader:`, `indent:`, `gap:`, `number_width:`, text style). Paginates across pages.
+
+### Drawing
+
+- SVG: path (every command, including arcs), rect, circle, ellipse, line, polyline, polygon and g, with fill, stroke, caps, joins, fill-rule, opacity, inline styles, transforms and `currentColor`. `svg` element.
+- SVG: elements that cannot be drawn (`text`, `use`, …) are listed in `SVG::Document#unsupported` and reported as an `UnsupportedSvg` warning.
+- Canvas: `rounded_rect` and `clip` take per-corner radii (`[top_left, top_right, bottom_right, bottom_left]`, scaled down to fit like CSS); `rounded_rect(dash:)`.
+- `to_pdf(debug: true)` outlines every layout rectangle (boxes, padding, columns, flow slots, cells, positioned boxes, images, the page content box), colour-coded by kind; `debug: %i[cell …]` outlines only those kinds.
+
+### Warnings
+
+- An unregistered family name draws with the first registered family (else bundled Inter) and reports an `UnknownFamily` warning once.
+- `Stationery::Warnings`: one collector per render, deduplicated, with `#message` on every entry (`Overflow`, `MissingGlyph`, `UnknownFamily`, `UnsupportedSvg`, `SkippedImage`, `UnresolvedLink`, `DuplicateAnchor`). `document.warnings` now includes warnings raised while page templates draw.
+- Strict mode: `to_pdf(strict: true)` or class-level `strict` raises `Stationery::WarningsError` when a render produced warnings.
+
+### Rails
+
+- Rails: a Railtie adds `render pdf: document` (`filename:`, `disposition:`) and `config.stationery` (`renderer`, `font_paths`); `Stationery.font_paths`. A `spec:rails` lane tests it against Rails 8 without adding a dependency.
+- Rails: PDF previews like ActionMailer previews. `Stationery::Preview` subclasses in `spec/pdfs/previews` or `test/pdfs/previews` render at `/rails/stationery/previews` (`?debug=1` when the document supports it); `config.stationery.preview_paths` and `show_previews` (development by default). `rake spec:rails` no longer overwrites the main suite's coverage report.
+
+### Tooling
+
+- Documentation site at https://stationery.zoolutions.llc, a docs-kit app under `docs/` (not part of the gem): getting started, every element with its options, layout rules, pages and regions, links and bookmarks, fonts, images and SVG, Rails, testing, the CLI, warnings, a cookbook built from `examples/`, performance, limitations and this changelog, rendered from the README and CHANGELOG where they overlap.
+- `stationery` executable with a command registry; `stationery render FILE [--out PATH|-] [--class NAME] [--strict] [--debug]` renders the Document a Ruby file defines (through `self.preview` when it needs arguments) and reports pages and bytes.
+- `require "stationery/rspec"` matchers (`have_pdf_text`, `have_pdf_text_on_page`, `have_page_count`, `have_pdf_link`, `have_image_count`, `have_bookmark`, `have_no_warnings`) and `require "stationery/minitest"` assertions, built on `Stationery::Testing::Inspector`. Needs `pdf-reader` in the test group.
+- Examples: `examples/report.rb` (multi-page annual report: header/footer regions, contents, bookmarks, lists, tables, a split callout, internal links, SVG icons), `examples/letter.rb` (one-page letter with a vector letterhead) and `examples/packing_slip.rb` (landscape, 120-row table with split rows, canvas barcode), each covered by an integration spec and rendered in CI by `rake examples`.
+- `rake bench`: reproducible benchmarks against Prawn + prawn-table (one-page invoice, 1,500-row table) and a StackProf profile script under `benchmark/`.
+
+### Performance
+
+- Layout caches: container nodes (box, row, flow, wrap, list item) memoise their height per width; table cells remember their height per width and their natural and minimum widths across the fragments of a split table; tables memoise row heights and column metrics; table row boundaries are found in one pass. Fonts memoise style resolution and advance/kerning totals per string, and runs already split for fallback are not split again. Output is byte-identical. A 1,500-row table renders ~26x faster (17.9 s → 0.68 s, 186M → 4.5M allocations), the invoice example 1.3x faster (77k → 33k allocations).
+- `benchmark/profile.rb` profiles in wall mode by default (`MODE=cpu|object`).
+
+### Fixes
+
+- Fixed: table cells restyled through a selection after the table had been measured kept their old style.
+- Fixed: fonts without an OS/2 v2 table (including every subset) crashed on a nil cap height.
+- `PDF::Writer` raises when a reserved object is never set instead of writing `null`.
+- Gemspec ships every file under `lib/` and `exe/` when built without git, not only `.rb`.
+
+## 0.1.0 (2026-09-26)
 
 - PDF writer with Flate streams, per-page resources and link annotations.
 - TrueType fonts: cmap 4/12, glyph subsetting, Type0/CIDFontType2 embedding with ToUnicode, synthetic bold and oblique.

data/README.md

@@ -3,7 +3,9 @@
 Pure-Ruby PDF documents built from Phlex-style components. Describe the page
 with rows, columns, boxes, tables, text and images; a box-layout engine
 measures, places and paginates them; a small PDF writer embeds subsetted
-TrueType fonts and JPEG/PNG images.
+TrueType and OpenType fonts, JPEG/PNG images and SVG drawings.
+
+**Documentation: [stationery.zoolutions.llc](https://stationery.zoolutions.llc)**
 
 - **No runtime dependencies.** Standard library only.
 - **No native extensions and no other processes.** No Prawn, no headless
@@ -17,20 +19,28 @@ gem "stationery"
 
 Ruby 3.4 or newer.
 
+## Quick start
+
+```ruby
+class Hello < Stationery::Document
+  def view_template = text("Hello, world", size: 24, weight: :bold)
+end
+
+File.binwrite("hello.pdf", Hello.new.to_pdf)
+```
+
+No fonts to configure: Inter ships inside the gem and is used until you
+declare a `font_family`.
+
 ## A document
 
 ```ruby
 class InvoicePdf < Stationery::Document
   page size: :a4, margin: [40, 44, 56, 44]
-  font_family "Inter", regular: "fonts/Inter-Regular.ttf", bold: "fonts/Inter-Bold.ttf"
-  default_text font: "Inter", size: 9, color: "#1F2937"
+  default_text size: 9, color: "#1F2937"          # bundled Inter; font_family "Brand", regular: "…" for your own
   metadata title: "Invoice"
 
-  page_template do |page|
-    box(at: [44, page.height - 34], width: page.content_box.width) do
-      text "Page #{page.number} of #{page.count}", size: 7, align: :right
-    end
-  end
+  footer { |page| text "Page #{page.number} of #{page.count}", size: 7, align: :right }
 
   def initialize(invoice)
     super()
@@ -60,28 +70,110 @@ 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/invoice.rb` is a complete, runnable invoice: `ruby -Ilib examples/invoice.rb`.
+`examples/` has a complete, runnable invoice, annual report, letter and packing slip; `bundle exec rake examples`
+renders them all, or render one with `stationery render examples/report.rb`.
 
 ## Elements
 
 | Element | What it does |
 |---|---|
 | `text(string, **style)` | A paragraph. Plain strings are literal. |
-| `text(string, markup: true)` | Reads `<b> <i> <u> <strikethrough> <sub> <sup> <br> <color rgb=""> <font size="" name=""> <link href="">`. |
+| `text(string, markup: true)` | Reads `<b> <i> <u> <strikethrough> <sub> <sup> <br> <color rgb=""> <font size="" name=""> <link href="">`; decodes numeric and HTML 4 named entities. |
 | `text { b "Total"; plain " due" }` | Styled runs in Ruby. Take a block argument (`{ \|t\| t.b @x }`) to keep your own `self`. |
-| `box(padding:, background:, border:, radius:, width:, height:, overflow:, at:) { }` | A container. Moves to the next page whole. `overflow: :truncate` or `:shrink_to_fit` for fixed heights. `at: [x, y]` pins it to a page position. |
-| `row(gap:, align:) { column(width:) { } }` | Columns side by side. `width:` is points, a fraction (`0.5`), `:auto` or `nil` (equal share). |
-| `table(rows, widths:, width:, header:, cell:) { \|t\| }` | Tables. 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. |
+| `box(padding:, background:, border:, radius:, width:, height:, min_height:, overflow:, at:, link:, outset:, break_inside:, decoration:) { }` | 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). |
+| `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. |
+| `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. |
 | `image(path_or_io, width:, height:, fit:, align:)` | JPEG or PNG, aspect preserved. |
+| `svg(source_or_path, width:, height:, color:, align:)` | Vector icons and drawings; `currentColor` takes `color:`. 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). |
+| `wrap(gap:, row_gap:, align:) { }` | Children side by side at their own widths, wrapping onto new rows (chips, tags). |
+| `ul(style:, gap:, indent:, marker_gap:, marker_color:) { li "…" }` | Bulleted list. `style:` is `:disc`, `:circle`, `:square`, `:dash` or any String; unstyled nested lists cycle disc → circle → square. Any node added inside (not only `li`) becomes an item. Items split across pages; the marker stays with the first line. |
+| `ol(format:, start:, suffix:, gap:, indent:, marker_gap:, marker_color:) { }` | Numbered list. `format:` is `:decimal`, `:alpha`, `:upper_alpha`, `:roman`, `:upper_roman` or a Proc `(n) -> String`; `suffix:` defaults to `"."`. Markers right-align so bodies line up. |
+| `li(string, **style)`, `li(gap:) { }` | A list item: a paragraph, or a block of any elements (including nested lists). |
 | `rule(height:, color:)`, `spacer(height)`, `page_break` | Dividers and spacing. |
-| `group(keep_together: true) { }` | Keep a block on one page. |
+| `group(keep_together: true, align:) { }` | Keep a block on one page. |
+| `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. |
+| `html(source, styles:, gap:, images:, base_path:, bookmarks:)` | Rich text from HTML (ActionText/Trix, CMS output): paragraphs, headings, lists, quotes, code, rules, tables, images, inline marks and links. See [HTML and Markdown](#html-and-markdown). |
+| `markdown(source, styles:, gap:, images:, base_path:, bookmarks:)` | The same from CommonMark (plus GFM tables and strikethrough). |
 
 Text style options: `font`, `size`, `weight` (`:regular`, `:bold`), `style` (`:italic`), `color`,
-`letter_spacing`, `underline`, `strikethrough`, `link`, `opacity`, `align`, `leading`.
+`letter_spacing`, `underline`, `strikethrough`, `link`, `opacity`, `kerning` (default `true`), `ligatures` (default `true`), `align` (`:left`, `:center`, `:right`, `:justify`), `leading`.
+`align: :justify` stretches the spaces of wrapped lines to the full width; the last line, lines
+ending in a newline and lines without spaces stay left-aligned (tabs are never stretched).
 Colours are `"#RRGGBB"`, `"RRGGBB"`, `"#RGB"`, `[r, g, b]` (0-255) or `[c, m, y, k]` (0-100).
 
+### HTML and Markdown
+
+`html` and `markdown` render user content with the elements above; their parsers load on first use.
+
+```ruby
+def view_template
+  html @post.body.to_s,                                   # ActionText
+       images: ->(src) { blob_path_for(src) },            # path, IO or nil (skipped with a warning)
+       styles: { h1: { size: 22 }, a: { color: "#0F766E" }, code: { font: "JetBrains Mono" } }
+  markdown File.read("NOTES.md"), base_path: "docs", bookmarks: true
+end
+```
+
+- Images come from `images:` (called with the `src`) or from files under `base_path:`; sources that
+  resolve nowhere, point outside `base_path` or are remote URLs are skipped with a `SkippedImage`
+  warning. Nothing is ever fetched over the network.
+- `styles:` is deep-merged into the defaults: `h1`–`h6` (`scale:` of the text size, or `size:` in
+  points; bold, `keep_with_next`), `p`, `a` (colour, underline), `code` (`font:`; register a
+  monospace family for inline and block code, otherwise the text font is used), `pre` and
+  `blockquote` (box options), `hr` (rule options), `table` (`cell:` options, `header:` text style),
+  `li` (text style) and `img` (`max_width:`).
+- `gap:` spaces the blocks (default 6); `bookmarks: true` adds h1–h3 to the PDF outline.
+
+### Links, bookmarks and table of contents
+
+A link target starting with `#` jumps to a named anchor in the same PDF; anything else is a URL.
+
+```ruby
+text "See the totals", link: "#totals"
+text %(Back to the <a href="#intro">introduction</a>), markup: true
+box(link: "#appendix") { text "Appendix" }
+
+text "Introduction", anchor: "intro"      # also box(anchor:), group(anchor:), table(rows, anchor:)
+box(anchor: "totals") { text "Totals" }
+anchor "appendix"                         # standalone; moves to the next page with what follows it
+text "Appendix", size: 16
+```
+
+An anchor on content that splits across pages points at its first page. A link to an unknown anchor
+is dropped and reported as an `UnresolvedLink` warning; a name defined twice keeps the first and reports
+a `DuplicateAnchor`. Anchors drawn by page templates resolve to the first page.
+
+`bookmark:` adds an entry to the PDF outline (the viewer's bookmarks sidebar) pointing at where the
+content paints. Levels nest under the nearest shallower entry above them; `open: true` shows an entry's
+children expanded.
+
+```ruby
+text "Introduction", size: 18, bookmark: "Introduction"            # level 1
+box(bookmark: { title: "Scope", level: 2, open: true }) { ... }    # also group(bookmark:), table(rows, bookmark:)
+bookmark "Appendix", level: 1                                       # standalone; moves with what follows it
+text "Appendix", size: 16
+```
+
+A document with bookmarks opens with the outline shown. A bookmark whose content never paints (cut off
+by a fixed-height box) is left out; bookmarks inside page templates are ignored.
+
+`table_of_contents` lists the bookmarks with the page each one landed on, one clickable row per entry.
+It reads the outline when layout starts, so bookmarks declared after it are included.
+
+```ruby
+text "Contents", size: 18
+table_of_contents                     # every level, dotted leaders
+table_of_contents(levels: 1..2, leader: :line, indent: 16, size: 9, color: "#374151")
+```
+
+Options: `levels:` (a Range, or an Integer maximum depth), `leader:` (`:dots`, `:line` or `nil`),
+`indent:` per level (points), `gap:` between rows and before the number, `number_width:` (defaults to
+the width of "0000") plus any text style. Numbers are right-aligned in a fixed slot and filled in after
+pagination, so a long contents list paginates without reflowing. An entry whose target never paints
+keeps its title, with no number and no link.
+
 ## Components
 
 Components have Phlex's lifecycle (`around_template`, `before_template`,
@@ -104,26 +196,285 @@ render Callout.new(color: "#F3F4F6") { text "Amount due" }
 - `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).
+- `header` and `footer` reserve space at the top and bottom of the page; the body flows between them:
+
+  ```ruby
+  header(gap: 8) do |page|
+    row do
+      text "ACME"
+      text "Page #{page.number} of #{page.count}", align: :right
+    end
+  end
+  footer(on: :rest) { text "Confidential", size: 7, align: :center }
+  header(on: :first) {} # no header on page 1
+  ```
+
+  `on:` takes `:all` (default), `:first`, `:rest`, `:odd`, `:even`, `:last`, a page number, a range or
+  `->(number) { … }`; later declarations win for the pages they match, and an empty block removes the
+  region there. `gap:` (default 8) is extra space between the region and the body. Without `height:` a
+  region is measured once, on the first page that uses it; pass `height:` when its content varies per
+  page. The footer is bottom-aligned. A region taller than its space is still drawn and listed in
+  `document.warnings`; regions that leave no room for the body raise `ArgumentError`. With `on: :last`
+  (say, a taller footer with totals) the paginator checks whether the rest fits above it; content that
+  fits a normal page but not the last one continues onto an extra page.
+- With a header or footer, a `page_template`'s `page.content_box` excludes their space (it is the
+  body's area).
 - Content taller than a page is placed anyway; `document.warnings` lists every overflow.
+- 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
+  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.
+
+### Encryption
+
+```ruby
+class InvoicePdf < Stationery::Document
+  encrypt owner_password: "s3cret", permissions: [:print] # every render
+end
+
+InvoicePdf.new(invoice).to_pdf(encrypt: { user_password: "1234", owner_password: "s3cret",
+                                          permissions: %i[print copy] }) # override for one render
+InvoicePdf.new(invoice).to_pdf(encrypt: nil) # plain
+```
+
+- `owner_password:` is required (`ArgumentError` when missing or empty); it opens the file with every
+  right. `user_password:` defaults to `""`: the file opens without a prompt, but viewers enforce the
+  permissions.
+- `permissions:` is a subset of `%i[print modify copy annotate fill_forms extract_accessible assemble
+  print_high]` (default: all).
+- `algorithm:` picks the standard security handler. `:aes_256` (default, PDF 2.0 / Acrobat X+);
+  `:aes_128` for older viewers; `:rc4_128` only for legacy readers that need it.
+- Every string and stream is encrypted, the document info included.
+
+### Debugging
+
+`to_pdf(debug: true)` outlines every layout rectangle on top of the content: boxes (red, padding dashed),
+row columns (blue), flow slots (grey, dotted), table cells (green, padding dashed), positioned boxes (pink),
+images (teal) and the page content box (cyan). Pass an Array to outline only some kinds:
+
+```ruby
+Invoice.new.to_pdf("invoice.pdf", debug: %i[cell cell_padding])
+```
 
 ## Rails
 
 ```ruby
-require "stationery/rails" # adds send_pdf to controllers
+# Gemfile
+gem "stationery", require: "stationery/rails"
+```
+
+Controllers gain `render pdf:` and `send_pdf`:
+
+```ruby
+def show
+  render pdf: InvoicePdf.new(@invoice), filename: "invoice.pdf" # disposition: "attachment" to download
+end
+
+def download = send_pdf(InvoicePdf.new(@invoice), filename: "invoice.pdf", disposition: "attachment")
+```
+
+`render pdf:` only accepts a document; anything else raises `ArgumentError`.
+Configure in `config/application.rb`:
+
+| Key | Default | |
+| --- | --- | --- |
+| `config.stationery.renderer` | `true` | `false` skips `render pdf:` (keeps another gem's, e.g. wicked_pdf's) |
+| `config.stationery.font_paths` | `["vendor/fonts"]` | directories under `Rails.root` added to `Stationery.font_paths` when they exist |
+| `config.stationery.preview_paths` | `["spec/pdfs/previews", "test/pdfs/previews"]` | directories under `Rails.root` searched for `*_preview.rb` |
+| `config.stationery.show_previews` | `Rails.env.development?` | mounts the preview routes |
+
+### Previews
+
+Like ActionMailer previews: a class ending in `Preview` under
+`spec/pdfs/previews` (or `test/pdfs/previews`), one public method per sample
+document.
+
+```ruby
+# spec/pdfs/previews/invoice_pdf_preview.rb
+class InvoicePdfPreview < Stationery::Preview
+  def paid = InvoicePdf.new(Invoice.paid.first)
+  def overdue(params) = InvoicePdf.new(Invoice.find(params.fetch("id", Invoice.overdue.first.id)))
+end
+```
+
+Open `/rails/stationery/previews` for the list; each one renders inline at
+`/rails/stationery/previews/invoice_pdf/paid`. Query parameters reach methods
+that take an argument (`?id=42`); `?debug=1` passes `debug: true` to `to_pdf`
+when the document supports it. Preview files are re-`load`ed on every request,
+so edits show up on refresh.
+
+The gem has no Rails dependency; the Railtie loads only inside a Rails app.
+
+## CLI
 
-def show = send_pdf(InvoicePdf.new(@invoice), filename: "invoice.pdf")
+```sh
+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
 ```
 
+`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.
+
+```sh
+stationery fonts list                                    # packs, licenses, what is in vendor/fonts
+stationery fonts install noto_sans liberation_serif      # into vendor/fonts/<pack>/
+stationery fonts install noto_sans --into app/fonts --force
+stationery fonts install liberation_sans --from ~/Downloads/liberation-fonts-ttf-2.1.5.tar.gz  # offline
+```
+
+`fonts install` downloads pinned files over HTTPS, checks every SHA-256
+before writing anything, and writes the license next to the fonts. Files
+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.
+
 ## Fonts and images
 
-Fonts are TrueType (`.ttf`) files. Only the glyphs a document uses are
-embedded, with a ToUnicode map so text copies and searches correctly. A style
-without its own file (bold, italic) is synthesised. There is no built-in
-font: declare at least one `font_family`.
+Fonts are TrueType (`.ttf`) or OpenType/CFF (`.otf`, name-keyed or
+CID-keyed) files, WOFF 1.0 web fonts (`.woff`, unwrapped in memory), or
+faces of a TrueType collection (`.ttc`): a `#N` suffix
+on the path picks face N, counted from 0 (face 0 without a suffix):
+
+```ruby
+font_family "Brand", regular: "Brand.ttc#0", bold: "Brand.ttc#2"
+```
+ Only the glyphs a document uses are embedded (a CFF font
+keeps its glyph numbering and subroutines; unused glyphs are blanked), with a
+ToUnicode map so text copies and searches correctly. A style without its own
+file (bold, italic) is synthesised.
+
+Inter (regular, bold, italic, bold italic; SIL Open Font License) is bundled
+and used when a document declares no family. `font_family "Inter"` with no
+paths selects it explicitly, and `Stationery.bundled_fonts` lists what ships.
+Font files are read lazily, on first use, never when the gem is required.
+
+More families come as font packs, installed into your app at development
+time (commit them; nothing is downloaded at runtime):
+
+| Pack | Family | License |
+|---|---|---|
+| `inter` | Inter (copied from the gem) | OFL 1.1 |
+| `noto_sans`, `noto_serif`, `noto_sans_mono` | Noto Sans, Noto Serif, Noto Sans Mono | OFL 1.1 |
+| `liberation_sans`, `liberation_serif`, `liberation_mono` | Liberation Sans, Serif, Mono (metric-compatible with Arial, Times New Roman, Courier New) | OFL 1.1, Reserved Font Name "Liberation" |
+
+`Stationery.font_paths` lists the directories searched for installed packs;
+the Railtie adds `vendor/fonts` (and `config.stationery.font_paths`) when it
+exists. With the pack's directory there, the family name is enough:
+
+```ruby
+font_family "Noto Sans"                                                # found in Stationery.font_paths
+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")`.
+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
+checks its SHA-256s.
+
+A character the text's family has no glyph for is drawn from the first
+family in `font_fallbacks` that has it, then from bundled Inter, in the same
+weight and style (synthesised when the family lacks the face):
+
+```ruby
+class Report < Stationery::Document
+  font_family "Brand", regular: "Brand-Regular.ttf"
+  font_family "Noto Sans Symbols", regular: "NotoSansSymbols-Regular.ttf"
+  font_fallbacks "Noto Sans Symbols"
+
+  def view_template = text("Next → ☃")
+end
+```
+
+Spaces, joiners, variation selectors and combining marks stay with the
+character before them. A 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). Fallback covers every text element,
+table cell, list marker, table of contents entry and page template text;
+direct `canvas.text` calls draw with the font they are given.
+
+Text is pair-kerned from the font's GPOS `kern` feature (PairPos lookups,
+including class-based pairs and Extension lookups), falling back to the
+legacy `kern` table (`kerning: false` on an element or in `default_text`
+turns it off). Pairs that straddle a style or
+font change are not kerned. Kerning only tightens in practice, so a kerned
+line is never wider than the same line unkerned.
+
+Standard ligatures (fi, fl, ffi, …) come from the font's GSUB `liga` feature
+(LigatureSubst lookups, also behind Extension lookups) and are on by default;
+`ligatures: false` on an element or in `default_text` turns them off. Only
+`liga` applies, not `clig` or `dlig`. Ligatures form within a run of one
+style and font, never across a line break, and letter spacing turns them off.
+The PDF's ToUnicode map sends a ligature glyph back to all of its
+characters, so copied and extracted text still reads "office". Fonts
+without a `liga` feature (such as the bundled Inter) are unaffected.
 
 Images are JPEG (grey, RGB, CMYK) and PNG (every colour type, alpha as a soft
 mask). Parsed fonts and images are cached per process.
 
+## Testing
+
+`stationery/rspec` and `stationery/minitest` read a rendered PDF back for
+assertions. They need the `pdf-reader` gem, which stationery itself does not
+depend on:
+
+```ruby
+# Gemfile
+group :test do
+  gem "pdf-reader"
+end
+```
+
+The subject is a document (rendered once), PDF bytes, a file path or an IO.
+
+```ruby
+# spec/spec_helper.rb
+require "stationery/rspec"
+
+RSpec.describe InvoicePdf do
+  subject(:pdf) { InvoicePdf.new(invoice) }
+
+  it { is_expected.to have_pdf_text("Invoice INV-7") }
+  it { is_expected.to have_pdf_text_on_page(2, /Total €[\d ,]+/) }
+  it { is_expected.to have_page_count(2) }
+  it { is_expected.to have_pdf_link("mailto:hello@acme.test") }
+  it { is_expected.to have_image_count(1) }
+  it { is_expected.to have_no_warnings }
+end
+```
+
+```ruby
+# test/test_helper.rb
+require "stationery/minitest"
+
+class InvoicePdfTest < Minitest::Test
+  include Stationery::Testing::Assertions
+
+  def test_prints_the_total
+    pdf = InvoicePdf.new(invoice)
+
+    assert_pdf_text pdf, "Invoice INV-7"
+    refute_pdf_text pdf, "DRAFT"
+    assert_page_count pdf, 2
+    assert_pdf_link pdf, /acme\.test/
+    assert_no_pdf_warnings pdf
+  end
+end
+```
+
+The matcher names carry a `pdf_` prefix so they never clash with Capybara's
+`have_text` and `have_link`. `have_bookmark` / `assert_bookmark` match outline
+titles. For anything else, `Stationery::Testing::Inspector.new(subject)`
+exposes `text`, `page_texts`, `page_count`, `links`, `internal_links`,
+`image_count`, `bookmarks`, `metadata` and `warnings`.
+
 ## Why not Prawn, Chrome or Typst?
 
 - **Prawn** is an imperative cursor API: every document does its own layout
@@ -132,12 +483,31 @@ mask). Parsed fonts and images are cached per process.
   a browser per worker; stray processes and memory are the price.
 - **Typst** is excellent but a native extension and a second template language.
 
+## Performance
+
+`bundle exec rake bench` renders two documents with Stationery and with Prawn
+2.5 + prawn-table, both embedding the same Open Sans TTF files
+(`benchmark/`, not part of CI). Apple M2 Max, Ruby 3.4.2 +YJIT, 27 September 2026:
+
+| Document | Engine | Renders/s | Objects allocated | PDF bytes |
+|---|---|---:|---:|---:|
+| Invoice (1 page, `examples/invoice.rb`) | Stationery | 74.6 | 33,231 | 23,525 |
+| | Prawn | 45.4 (1.64x slower) | 88,558 | 33,034 |
+| Table, 1,500 rows × 5 columns, repeating header | Stationery | 1.47 (46 pages) | 4,462,820 | 233,389 |
+| | Prawn | 0.74 (40 pages; 1.99x slower) | 6,901,818 | 2,689,487 |
+
+Stationery compresses content streams; Prawn does not by default, hence the
+larger file. `PROFILE=1 bundle exec ruby -Ilib benchmark/profile.rb` prints the
+20 hottest frames of the table render under StackProf (wall mode; `MODE=cpu` or
+`MODE=object` for the others).
+
 ## Limitations
 
-No kerning or ligatures, no OpenType/CFF, TrueType collections, variable
-fonts or WOFF; no full justification; no SVG (paths are available on the
-canvas); no encryption, outlines, forms or tagged PDF; boxes and rows do not
-split across pages.
+No variable fonts (including CFF2) or
+WOFF2 (it needs Brotli; convert to `.ttf` or `.woff`); SVG covers the shapes icon sets use
+(no patterns or masks); no forms or
+tagged PDF. A box with a fixed `height:` never splits (use
+`min_height:` for a floor that can); a row splits only when every column can.
 
 ## License
 

data/exe/stationery

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "stationery/cli"
+
+exit Stationery::CLI.start(ARGV)