stationery 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dabc4e22462e7af56f79f46c814ebb908ee12961948190ae2b73f2f8951478f7
-  data.tar.gz: 9ef6ee24bfa601829d8b51fb514254a55a9470afd98be1429b2935984f6605df
+  metadata.gz: dc2011ee51b715eb946943e60d0512157f2215acd871133433c6edf4f81bb9a9
+  data.tar.gz: a5a9c654b4c415ab77ba005eb228ba67fae05f87af1adeb39871ccb3353a00a3
 SHA512:
-  metadata.gz: 1e051af6e9e75e979f763b5bd47eed272fef23d754d1e11116abc890669679c71eee3a2a615305ef63c59f6c626ea3567eeba76a2a9407e81c929626e6ec6139
-  data.tar.gz: d7c7ffab364d4502a568c6496c10413b189bebf2003ffc433e014960fc29fe7cc948097eff9fd292e9e6108aeb5cc51c42ffdba5da18e71d99f2e951b94cfb26
+  metadata.gz: 239ad178900f1cce55589e1e6882fda2e713631df0a0d732945eefd0d8df762e9baa0a44efde7ea13fa643e6ee0dd038594886cd09cc14aac2cb0486ef88f05b
+  data.tar.gz: 0ac757cdf6a15a654c83b26fa80c5be99e20e9e28e09653c31c299627a5c46c5cfb3965cfa58e58c2c6ade241c3b86f07fbe37a761ad2738e09207ce0711c200

data/CHANGELOG.md

@@ -1,6 +1,105 @@
 # Changelog
 
-## 0.2.0 (unreleased)
+## 0.4.0 (2026-09-27)
+
+Interactive forms and tagged (accessible) PDF.
+
+- Tagged PDF: form fields are `Form` structure elements owning their widget annotations (`/OBJR` + `/StructParent`), so screen readers reach them in reading order.
+- Tagged (accessible) PDF: `tagged` at class level or `to_pdf(tagged: true)` writes a structure tree (`/StructTreeRoot` with a `/ParentTree`, `/MarkInfo`, `/StructParents` on pages) and marks every painted leaf as marked content (`/P <</MCID n>> BDC … EMC`). Text is `P`, or `H1`–`H6` with `text(…, heading: 1..6)`; images and SVG drawings are `Figure` with `/Alt` from `alt:` (`alt: false`: decorative) and a `/BBox`; `box(role: :section | :div | :blockquote | :note | :caption | :article | :part)` groups its content. A node split across pages stays one element with marked content on each page. Headers, footers and page templates are `/Pagination` artifacts, other decoration is a layout artifact. `metadata lang:` writes `/Lang` (and is kept out of the document info); a tagged document with a title sets `/DisplayDocTitle`. New warnings `MissingAlt` and `MissingLanguage` let `strict` catch accessibility gaps. Untagged output is byte-for-byte unchanged. `Canvas#tag`, `#structure` and `#artifact`, `Stationery::Tagging::{Tree, Element, Writer}`.
+- Tagged PDF structure for lists (`L` with `/ListNumbering` > `LI` > `Lbl` + `LBody`; drawn bullets are artifacts), tables (`Table` > `TR` > `TH` with `/Scope /Column` or `TD`, `/ColSpan`/`/RowSpan` attributes; one `Table` across pages, repeated header rows as artifacts), links (linked text is a `Link` inside its paragraph with the annotation's `/OBJR`; annotations get `/StructParent`; `box(link:)` groups its content in a `Link`) and `table_of_contents` (`TOC` > `TOCI` > `Link` + `Reference`). `html`/`markdown` tag headings `H1`–`H6` and block quotes. `Canvas#tag_runs`, `Canvas#link(…, tag:)`, `Layout::Flow.new(…, tag:)`, `Tagging::Element.new(…, attributes:)`.
+- Testing tagged PDFs: `Inspector#structure` reads the structure tree as nested arrays with each element's text taken from its marked content (`[[:Document, [[:H1, "Intro"], [:P, ["Read", [:Link, "the docs"], "now"]]]]]`), `Inspector#tagged?` and `#untagged_text`; matchers `have_structure` and `have_tagged_content`, assertions `assert_pdf_structure` and `assert_tagged_content`. `examples/report.rb` is tagged, with headings and a decorative icon. Empty table cells stay in the tree.
+- Interactive forms (AcroForm): `text_field` (multiline, `max_length:`, `comb:`, `read_only:`, `required:`) and `checkbox` (with `label:`) lay out like boxes or sit at `at: [x, y]`, also inside table cells. Each widget ships its own appearance stream (Helvetica / ZapfDingbats from the standard 14, listed in the AcroForm `/DR`), so forms render in every viewer; `NeedAppearances` is set so edits redraw. Dotted names (`"address.city"`) build parent fields; widgets sharing a name become one field's kids. Values are Unicode text strings and survive encryption. `Document#fields` returns `{ name => value }` after a render; `Canvas#widget` places a field widget; `to_pdf(debug: [:field])` outlines fields.
+- Forms: `radio` groups (radios sharing a name form one `/Btn` field with the radio flag; `/V` is the checked value), `select` combo boxes (`/Ch` with `/Opt`, `editable:` adds the Edit flag) and `signature_field` (an empty `/Sig` field drawn as a rule over its label). `examples/form.rb` is a one-page application form using every field type.
+- 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.
+- 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`.
+- **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.
+- 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.
+- `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.
+- `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.
+- 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).
+- `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.
+- 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.
+- 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: 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.
+- 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/`.
+- 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`).
+- 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`.
+- 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.
+- JPEG and PNG images, including alpha soft masks and palette transparency.
+- Canvas: rectangles, rounded rectangles, circles, lines, Bézier paths, clipping, opacity, text runs, images, links.
+- Text: inline markup, Ruby run builder, wrapping, alignment, leading, truncate and shrink-to-fit.
+- Layout: flow, box, row/column, table, image, rule, spacer, page break, group, canvas escape hatch; pagination with header rows, keep-together and keep-with-next.
+- Components with Phlex's lifecycle; documents with page settings, font families, default text, metadata and page templates.
+- `Stationery::Rails#send_pdf`.
+
+## 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.

data/README.md

@@ -70,7 +70,7 @@ 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 and packing slip; `bundle exec rake examples`
+`examples/` has a complete, runnable invoice, annual report, letter, packing slip and fillable form; `bundle exec rake examples`
 renders them all, or render one with `stationery render examples/report.rb`.
 
 ## Elements
@@ -80,11 +80,11 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `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="">`; 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:, 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. `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. |
+| `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:`. |
+| `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. |
@@ -94,11 +94,16 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `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. |
+| `text_field(name, value:, width:, height:, multiline:, max_length:, comb:, read_only:, required:, font_size:, border:, background:, radius:, at:)` | An interactive text input (AcroForm). `width:` is `:full` or points; dotted names (`"address.city"`) group fields. See [Forms](#forms). |
+| `checkbox(name, checked:, size:, label:, at:)` | An interactive check box, with an optional label drawn to its right. |
+| `radio(name, value, checked:, size:, label:, at:)` | One choice of a radio group: radios sharing `name` form one field whose value is the checked `value`. |
+| `select(name, options:, value:, width:, height:, editable:, at:)` | A drop-down (combo box); `editable: true` also accepts typed values. |
+| `signature_field(name, width:, height:, label:, at:)` | An empty signature field for the signer to fill, drawn as a rule over the label. |
 | `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`, `kerning` (default `true`), `align` (`:left`, `:center`, `:right`, `:justify`), `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).
@@ -174,6 +179,34 @@ the width of "0000") plus any text style. Numbers are right-aligned in a fixed s
 pagination, so a long contents list paginates without reflowing. An entry whose target never paints
 keeps its title, with no number and no link.
 
+### Forms
+
+Form fields are interactive widgets (an AcroForm) that lay out like boxes, or sit at a fixed page
+position with `at: [x, y]`. They work inside boxes, rows and table cells.
+
+```ruby
+text "Name"
+text_field "applicant.name", value: @applicant.name, required: true
+text_field "applicant.notes", multiline: true, height: 60
+text_field "applicant.pin", comb: 6                      # six cells; sets max_length
+select "applicant.country", options: %w[Sweden Norway Denmark], value: "Sweden"
+radio "plan", "basic", label: "Basic"                    # radios sharing a name form one group
+radio "plan", "pro", checked: true, label: "Pro"
+checkbox "terms", checked: false, label: "I accept the terms"
+signature_field "signature", label: "Signature of the applicant"
+```
+
+- Every widget carries its own appearance (drawn in Helvetica, ZapfDingbats for the check mark), so
+  the form looks the same in every viewer; `NeedAppearances` is set too, so viewers redraw edited
+  values. Values are Unicode (`/V`); the drawn appearance covers the Windows-1252 range.
+- Dotted names build the field hierarchy viewers show as groups; widgets sharing a name are one field
+  with several widgets. A name used as both a field and a group raises `ArgumentError`.
+- `read_only:`, `required:`, `multiline:`, `max_length:` and `comb:` set the matching field flags.
+- A radio group's value is its checked choice's `value` (`Off` when none is checked); a select box
+  lists its `options:` and draws the chosen `value`; a signature field is left unsigned for the signer.
+- `document.fields` returns `{ name => value }` for the last render (a check box's value is `true` or
+  `false`, an unchecked radio group's and a signature field's `nil`). Encrypted documents keep their fields fillable.
+
 ## Components
 
 Components have Phlex's lifecycle (`around_template`, `before_template`,
@@ -228,6 +261,81 @@ render Callout.new(color: "#F3F4F6") { text "Amount due" }
   (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.
+
+### Accessibility (tagged PDF)
+
+```ruby
+class ReportPdf < Stationery::Document
+  tagged                                   # or to_pdf(tagged: true) for one render
+  metadata title: "Q3 report", lang: "en-US"
+
+  def view_template
+    text "Quarterly report", size: 20, heading: 1
+    text "Revenue grew in every region."
+    image "chart.png", width: 300, alt: "Revenue by region, Q1 to Q3"
+    box(role: :note, padding: 8) { text "Figures are unaudited." }
+  end
+end
+```
+
+A tagged PDF carries a structure tree screen readers and reflowing viewers follow, in paint order
+and across page breaks: a paragraph continued on the next page stays one `P`.
+
+- `text` is a `P`; `heading: 1..6` makes it `H1`–`H6`.
+- `image`/`svg` are a `Figure` with `/Alt` from `alt:` and a bounding box; `alt: false` marks one
+  decorative (an artifact, not announced).
+- `box(role:)` groups its content: `:section` (`Sect`), `:div`, `:blockquote`, `:note`, `:caption`,
+  `:article` (`Art`), `:part`. Boxes without a role, rows, columns, groups and wraps add no element.
+- Lists are `L` (with `/ListNumbering` from the bullet shape or number format) > `LI` > `Lbl` (a text
+  marker; drawn bullets are artifacts) and `LBody`.
+- Tables are `Table` > `TR` > `TH` (header rows, `/Scope /Column`) or `TD`, with `/ColSpan` and
+  `/RowSpan`. A table split across pages stays one `Table`; its repeated header rows are artifacts.
+- Linked text is a `Link` inside its paragraph holding the link annotation (`/OBJR`, `/StructParent`);
+  `box(link:)` groups its content in a `Link`.
+- `table_of_contents` is `TOC` > `TOCI` > `Link` (the title and its annotation) and `Reference` (the
+  page number).
+- `html`/`markdown` tag headings `H1`–`H6` (with or without `bookmarks: true`) and block quotes
+  `BlockQuote`, and give images their `alt`.
+- Headers, footers and page templates are pagination artifacts; 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.
+- An image or drawing without `alt:` (`Warnings::MissingAlt`) and a missing `lang`
+  (`Warnings::MissingLanguage`) are warnings, so `strict` catches them.
+- Untagged documents (the default) are written exactly as before.
+
+Check the tree in tests with `have_structure` and `have_tagged_content` (see [Testing](#testing)):
+
+```ruby
+expect(ReportPdf.new).to have_tagged_content # tagged, and no text outside marked content
+expect(ReportPdf.new).to have_structure(
+  [[:Document, [[:H1, "Quarterly report"], [:P, "Revenue grew in every region."],
+                [:Figure, "Revenue by region, Q1 to Q3"], [:Note, [[:P, "Figures are unaudited."]]]]]]
+)
+```
+
+The PDF is not labelled PDF/UA (no XMP `pdfuaid` metadata), and nothing checks colour contrast or
+reading order you build out of positioned boxes (`box(at:)` joins the reading order where it paints).
+
 ### Debugging
 
 `to_pdf(debug: true)` outlines every layout rectangle on top of the content: boxes (red, padding dashed),
@@ -317,7 +425,14 @@ already present are kept unless `--force`. `--from` takes a directory or a
 ## Fonts and images
 
 Fonts are TrueType (`.ttf`) or OpenType/CFF (`.otf`, name-keyed or
-CID-keyed) files. Only the glyphs a document uses are embedded (a CFF font
+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.
@@ -379,6 +494,15 @@ 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.
 
@@ -410,6 +534,8 @@ RSpec.describe InvoicePdf do
   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 }
+  it { is_expected.to have_tagged_content } # a tagged PDF with every text tagged or an artifact
+  it { is_expected.to have_structure([[:Document, [[:H1, "Invoice"], [:P, "INV-7"]]]]) }
 end
 ```
 
@@ -428,6 +554,8 @@ class InvoicePdfTest < Minitest::Test
     assert_page_count pdf, 2
     assert_pdf_link pdf, /acme\.test/
     assert_no_pdf_warnings pdf
+    assert_tagged_content pdf
+    assert_pdf_structure pdf, [[:Document, [[:H1, "Invoice"], [:P, "INV-7"]]]]
   end
 end
 ```
@@ -436,7 +564,11 @@ 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`.
+`image_count`, `bookmarks`, `metadata`, `warnings`, `tagged?`, `untagged_text` and
+`structure` — a tagged PDF's structure tree as nested arrays, each element's text
+read from its marked content: `[type, "text"]`, `[type, [children]]` (its own text
+between the children, as for a `P` holding a `Link`) or `[type]` when empty; a
+`Figure` reads as its alt text.
 
 ## Why not Prawn, Chrome or Typst?
 
@@ -466,11 +598,10 @@ larger file. `PROFILE=1 bundle exec ruby -Ilib benchmark/profile.rb` prints the
 
 ## Limitations
 
-No ligatures, no TrueType collections, variable fonts (including CFF2) or
-WOFF; SVG covers the shapes icon sets use
-(no text, gradients, patterns, masks or CSS stylesheets); no encryption,
-forms or tagged PDF; fixed-height boxes, and rows holding one,
-never 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). 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/lib/stationery/builder.rb

@@ -4,7 +4,8 @@ module Stationery
   # Collects the nodes a component tree describes. Holds the container stack
   # (where the next node goes) and the text defaults in effect.
   class Builder
-    STYLE_KEYS = %i[size color weight style letter_spacing underline strikethrough link opacity kerning].freeze
+    STYLE_KEYS = %i[size color weight style letter_spacing underline strikethrough link opacity kerning
+                    ligatures].freeze
 
     # Collects a row's columns; anything that is not already a column box is
     # wrapped in one.

data/lib/stationery/canvas/debug.rb

@@ -8,7 +8,8 @@ module Stationery
     module Debug
       DEBUG_COLORS = {
         box: "#E11D48", padding: "#E11D48", column: "#2563EB", cell: "#16A34A", cell_padding: "#16A34A",
-        flow: "#9CA3AF", positioned: "#DB2777", image: "#0D9488", page: "#06B6D4", region: "#0EA5E9"
+        flow: "#9CA3AF", positioned: "#DB2777", image: "#0D9488", page: "#06B6D4", region: "#0EA5E9",
+        field: "#7C3AED"
       }.freeze
       DEBUG_DASHES = { padding: [2, 2], cell_padding: [2, 2], flow: [1, 2] }.freeze
 

data/lib/stationery/canvas/marking.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Stationery
+  class Canvas
+    # Marked content for tagged PDF. Without a Tagging::Tree every method
+    # just yields, so an untagged document's content streams stay as they were.
+    module Marking
+      def tagging? = !@tagging.nil?
+
+      # Paints the block as one marked-content sequence of `element` (a fresh
+      # MCID on this page), joining the element to the open structure. With no
+      # element the block is an artifact. `bbox` is [x, y, w, h] in top-left
+      # coordinates, kept as the element's layout bounding box.
+      def tag(element, bbox: nil, &)
+        return artifact(&) unless element
+        return yield unless structure?
+
+        element.attach(open_element)
+        element.place(pdf_box(*bbox)) if bbox
+        open_run(element)
+        begin
+          yield
+        ensure
+          close_run
+        end
+      end
+
+      # Marks what the block paints as consecutive sequences: the block gets a
+      # callable, `mark.(element) { … }`, that continues the open sequence when
+      # `element` is the one it marks and otherwise starts one for it. A nil
+      # element is `parent`; any other joins `parent` as a child (a Link
+      # inside its paragraph). Without a parent the block is an artifact.
+      def tag_runs(parent, &)
+        return artifact { yield PASS } unless parent
+        return yield PASS unless structure?
+
+        parent.attach(open_element)
+        current = nil
+        yield(lambda do |element = nil, &block|
+          element ||= parent
+          unless element.equal?(current)
+            close_run if current
+            element.attach(parent)
+            open_run(current = element)
+          end
+          block.call
+        end)
+      ensure
+        close_run if current
+      end
+
+      # Opens `element` (nil: none) as the parent of the elements painted in
+      # the block, without marking any content itself.
+      def structure(element)
+        return yield unless element && structure?
+
+        element.attach(open_element)
+        open_elements << element
+        begin
+          yield
+        ensure
+          open_elements.pop
+        end
+      end
+
+      # Paints the block as an artifact: content that is not part of the
+      # document's structure. `type:` (:pagination, :layout, :page) and
+      # `subtype:` (:header, :footer, :watermark) describe it.
+      def artifact(type: nil, subtype: nil, &)
+        return yield unless structure?
+
+        properties = { Type: type && capital(type), Subtype: subtype && capital(subtype) }.compact
+        emit(properties.empty? ? "/Artifact BMC" : "/Artifact #{PDF::Serializer.dump(properties)} BDC")
+        @marked += 1
+        begin
+          yield
+        ensure
+          close_run
+        end
+      end
+
+      PASS = ->(_element = nil, &block) { block.call }
+
+      private
+
+      # Records an annotation as an /OBJR of `element`, when that element is in the tree.
+      # Joins `element` to the open structure with `annotation` as its only
+      # content (a form field's widget): no marked content, just the /OBJR.
+      def adopt(annotation, element, bbox)
+        return unless structure?
+
+        element.attach(open_element)
+        element.place(bbox)
+        own(annotation, element)
+      end
+
+      def own(annotation, element)
+        return unless @tagging && element.attached?
+
+        annotation[:tag] = element
+        element.kids << Stationery::Tagging::ObjectRef.new(@page, annotation)
+      end
+
+      def open_run(element)
+        emit("/#{element.type} <</MCID #{@tagging.mark(@page, element)}>> BDC")
+        @marked += 1
+      end
+
+      def close_run
+        @marked -= 1
+        emit("EMC")
+      end
+
+      def structure? = @tagging && @marked.zero?
+      def open_elements = @open_elements ||= []
+      def open_element = open_elements.last || @tagging.root
+      def capital(value) = value.to_s.capitalize.to_sym
+
+      def pdf_box(x, y, w, h)
+        [x, @page.height - y - h, x + w, @page.height - y].map { |value| num_value(value) }
+      end
+    end
+  end
+end

data/lib/stationery/canvas/text.rb

@@ -7,15 +7,16 @@ module Stationery
       BOLD_STROKE = 0.03
 
       # Draws `string` with its baseline at (x, y) in top-left coordinates and
-      # returns its advance width.
+      # returns its advance width. Standard ligatures form unless `ligatures:`
+      # is false or letter spacing is set.
       def text(string, x:, y:, font:, size:, color: "#000000", letter_spacing: 0, rise: 0, opacity: nil,
                synthetic_bold: false, synthetic_oblique: false, underline: false, strikethrough: false,
-               kerning: false, word_spacing: 0)
+               kerning: false, ligatures: true, word_spacing: 0)
         return 0 if string.empty?
 
         color = Color.parse(color)
-        run = font.glyph_run(string, kerning:)
-        run = run.with_word_spacing(string, word_spacing, size) unless word_spacing.zero?
+        run = font.glyph_run(string, kerning:, ligatures: ligatures && letter_spacing.zero?)
+        run = run.with_word_spacing(word_spacing, size) unless word_spacing.zero?
         width = run.width(size, letter_spacing:)
         graphics(opacity:) do |ops|
           ops << color.fill