stationery 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9ff43b2013eb330ebc103525c440bb5e4cfdaf0d05364baf47fd329c48ad11a
-  data.tar.gz: 718ede92892d3c7c0cdc556708880a2ba53f559611b872cfcb8ac946adb59908
+  metadata.gz: dc2011ee51b715eb946943e60d0512157f2215acd871133433c6edf4f81bb9a9
+  data.tar.gz: a5a9c654b4c415ab77ba005eb228ba67fae05f87af1adeb39871ccb3353a00a3
 SHA512:
-  metadata.gz: b3a4a85b185b0f06e195a15f81773c86d79086e32e923b1c21c2d39ee528375fd5b75be1581fc3d8180e530071d653939674804c973896d0edb3b57fffbde9fa
-  data.tar.gz: fd368b63884a129cd0e6f03507da714891c79b81b6a1aeadde9cfeafc4987824d7cd525c2f86aa3eba397f432a14516429bc697b61177056a790a602d85369ae
+  metadata.gz: 239ad178900f1cce55589e1e6882fda2e713631df0a0d732945eefd0d8df762e9baa0a44efde7ea13fa643e6ee0dd038594886cd09cc14aac2cb0486ef88f05b
+  data.tar.gz: 0ac757cdf6a15a654c83b26fa80c5be99e20e9e28e09653c31c299627a5c46c5cfb3965cfa58e58c2c6ade241c3b86f07fbe37a761ad2738e09207ce0711c200

data/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 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

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
@@ -94,6 +94,11 @@ 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). |
 
@@ -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`,
@@ -249,6 +282,60 @@ InvoicePdf.new(invoice).to_pdf(encrypt: nil) # plain
   `: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),
@@ -447,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
 ```
 
@@ -465,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
 ```
@@ -473,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?
 
@@ -505,8 +600,7 @@ larger file. `PROFILE=1 bundle exec ruby -Ilib benchmark/profile.rb` prints the
 
 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
+(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/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.rb

@@ -7,6 +7,7 @@ module Stationery
   class Canvas
     include Text
     include Debug
+    include Marking
 
     CAPS = { butt: 0, round: 1, square: 2 }.freeze
     JOINS = { miter: 0, round: 1, bevel: 2 }.freeze
@@ -14,11 +15,14 @@ module Stationery
     attr_reader :page
 
     # `template: true` records anchors apart, for canvases page templates draw on.
-    def initialize(page, resources, template: false, debug: false)
+    # `tagging:` (a Tagging::Tree) marks content for a tagged PDF.
+    def initialize(page, resources, template: false, debug: false, tagging: nil)
       @page = page
       @resources = resources
       @template = template
       @debug = debug
+      @tagging = tagging
+      @marked = 0
     end
 
     def save
@@ -81,11 +85,22 @@ module Stationery
 
     # A clickable area opening `target`: a URL, or `#name` for an anchor in
     # this document. Annotation rectangles live in absolute, untransformed
-    # page space, so they ignore clips and path transforms.
-    def link(x, y, w, h, target)
+    # page space, so they ignore clips and path transforms. `tag:` is the
+    # Link element the annotation belongs to in a tagged PDF.
+    def link(x, y, w, h, target, tag: nil)
       target = target.to_s
       rect = [x, @page.height - y - h, x + w, @page.height - y].map { |v| num_value(v) }
-      @page.annotations << (target.start_with?("#") ? { rect:, dest: target[1..] } : { rect:, url: target })
+      annotation = target.start_with?("#") ? { rect:, dest: target[1..] } : { rect:, url: target }
+      @page.annotations << annotation
+      own(annotation, tag) if tag
+    end
+
+    # An interactive form field's widget (a Forms::Field) over the rectangle.
+    def widget(field, x, y, w, h, tag: nil)
+      rect = [x, @page.height - y - h, x + w, @page.height - y].map { |v| num_value(v) }
+      annotation = { rect:, widget: field }
+      @page.annotations << annotation
+      adopt(annotation, tag, rect) if tag
     end
 
     # Names the point `y` on this page as a link target.
@@ -94,9 +109,10 @@ module Stationery
     end
 
     # Leaves room for the page number `anchor` lands on; Structure fills it in
-    # and adds the `link:` area ([x, y, w, h]) when the anchor exists.
-    def number_slot(anchor, x:, baseline:, width:, style:, link: nil)
-      @page.slots << Page::Slot.new(anchor.to_s, x, baseline, width, style, link)
+    # and adds the `link:` area ([x, y, w, h]) when the anchor exists. `tags:`
+    # are the [link, number] elements they belong to in a tagged PDF.
+    def number_slot(anchor, x:, baseline:, width:, style:, link: nil, tags: nil)
+      @page.slots << Page::Slot.new(anchor.to_s, x, baseline, width, style, link, tags)
     end
 
     def num(value) = PDF::Serializer.number(num_value(value))
@@ -141,7 +157,7 @@ module Stationery
       ops = []
       ops << "/#{@page.use(:ExtGState, @resources.opacity(opacity))} gs" if opacity && opacity < 1
       yield ops
-      emit("q", *ops, "Q")
+      artifact { emit("q", *ops, "Q") }
     end
 
     def emit(*ops)

data/lib/stationery/document.rb

@@ -24,7 +24,7 @@ module Stationery
                       superclass.config.transform_values(&:dup)
                     else
                       { page: { size: :letter, margin: 36 }, families: {}, fallbacks: [], text: {}, metadata: {},
-                        templates: [], regions: [], strict: false }
+                        templates: [], regions: [], strict: false, tagged: false }
                     end
       end
 
@@ -55,6 +55,13 @@ module Stationery
         config[:strict] = value
       end
 
+      # Writes a tagged (accessible) PDF: a structure tree of headings,
+      # paragraphs and figures, and headers and footers marked as artifacts.
+      # Set `metadata lang:` and give images `alt:` text.
+      def tagged(value = true) # rubocop:disable Style/OptionalBooleanParameter
+        config[:tagged] = value
+      end
+
       # Encrypts every render with the standard security handler; see
       # PDF::Encryption::StandardSecurity for the options.
       def encrypt(**)
@@ -80,26 +87,29 @@ module Stationery
       end
     end
 
-    attr_reader :warnings
+    # `fields` is every form field's name and value from the last render.
+    attr_reader :warnings, :fields
 
     def page_options = self.class.config[:page]
     def metadata = self.class.config[:metadata]
 
-    def to_pdf(target = nil, strict: self.class.config[:strict], debug: false, encrypt: self.class.config[:encrypt])
+    def to_pdf(target = nil, strict: self.class.config[:strict], debug: false, encrypt: self.class.config[:encrypt],
+               tagged: self.class.config[:tagged])
       encryption = encrypt && PDF::Encryption::StandardSecurity.new(**encrypt)
+      tagging = Tagging::Tree.new if tagged
       warnings = Warnings.new
       book = Fonts::FontBook.new(self.class.config[:families], fallbacks: self.class.config[:fallbacks], warnings:)
       call(builder = Builder.new(book:, text: self.class.config[:text]))
       resources = Resources.new
-      regions = Regions.new(self.class.config[:regions], measure: region_measure(book))
-      paginator = Layout::Paginator.new(resources:, page: page_options, warnings:, debug:, regions:)
-      pages = paginator.paginate(builder.root)
-      PageTemplates.new(self, book:, resources:, debug:, regions:, warnings:).apply(pages)
-      outline = builder.outline.resolve(Structure.resolve(pages, warnings:, resources:, book:))
+      pages = paginate(builder.root, book:, resources:, warnings:, debug:, tagging:)
+      outline = builder.outline.resolve(Structure.resolve(pages, warnings:, resources:, book:, tagging:))
+      tagging&.audit(pages, warnings, lang: metadata[:lang])
       @warnings = warnings
+      @fields = Forms::AcroForm.values(pages)
       raise WarningsError, warnings if strict && warnings.any?
 
-      write(PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:).render, target)
+      assembler = PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:, tagging:, lang: metadata[:lang])
+      write(assembler.render, target)
     end
 
     # Used by page templates to build nodes into their own root.
@@ -120,6 +130,14 @@ module Stationery
 
     private
 
+    def paginate(root, book:, resources:, warnings:, debug:, tagging:)
+      regions = Regions.new(self.class.config[:regions], measure: region_measure(book))
+      paginator = Layout::Paginator.new(resources:, page: page_options, warnings:, debug:, regions:, tagging:)
+      paginator.paginate(root).tap do |pages|
+        PageTemplates.new(self, book:, resources:, debug:, regions:, warnings:, tagging:).apply(pages)
+      end
+    end
+
     def region_measure(book)
       page = Page.new(**page_options)
       lambda do |region, number|
@@ -129,7 +147,7 @@ module Stationery
     end
 
     def info
-      metadata.to_h do |key, value|
+      metadata.except(:lang).to_h do |key, value|
         [INFO_KEYS.fetch(key.to_sym) { key.to_sym }, value.is_a?(Array) ? value.join(", ") : value]
       end
     end

data/lib/stationery/elements/forms.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Interactive form fields. Each takes a name (dotted names group fields,
+  # "address.city") and lays out like a box, or at a fixed page position with
+  # `at: [x, y]`.
+  module Elements
+    # A text input. `width:` is :full or points; `multiline:`, `max_length:`,
+    # `comb:` (a cell count, or true with max_length:), `read_only:`,
+    # `required:`, `font_size:`, `border:`, `background:` and `radius:`.
+    def text_field(name, value: "", width: :full, height: 22, at: nil, **)
+      field_node(Forms::Field.new(:text, name, value: value.to_s, **), width:, height:, at:)
+    end
+
+    # A check box `size` points square, with an optional label to its right.
+    def checkbox(name, checked: false, size: 12, label: nil, at: nil, **)
+      field = Forms::Field.new(:checkbox, name, value: checked == true, **)
+      field_node(field, width: size, height: size, at:, label:)
+    end
+
+    # One choice of the radio group `name`; its `value` becomes the group's
+    # value when checked.
+    def radio(name, value, checked: false, size: 12, label: nil, at: nil, **)
+      field = Forms::Field.new(:radio, name, value: value.to_s, checked:, **)
+      field_node(field, width: size, height: size, at:, label:)
+    end
+
+    # A drop-down (combo box) of `options`; `editable: true` also accepts
+    # typed values.
+    def select(name, options:, value: nil, width: :full, height: 22, at: nil, **)
+      field = Forms::Field.new(:select, name, value: value&.to_s, options: options.map(&:to_s), **)
+      field_node(field, width:, height:, at:)
+    end
+
+    # An empty signature field for the signer to fill, drawn as a rule over
+    # the label.
+    def signature_field(name, width: :full, height: 40, label: "Signature", at: nil, **)
+      field = Forms::Field.new(:signature, name, label: label.to_s, **)
+      field_node(field, width:, height:, at:)
+    end
+
+    private
+
+    def field_node(field, width:, height:, at:, label: nil)
+      label &&= field_label(label)
+      node = Layout::Field.new(field, height:, width:, label:)
+      @_builder.add(at ? Layout::Positioned.new(node, x: at[0], y: at[1]) : node)
+    end
+
+    def field_label(label)
+      style = @_builder.style
+      Layout::Text.new([Text::Run.new(label.to_s, style)], context: @_builder.context(style))
+    end
+  end
+end