activemail 1.2.3 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7db4250b0c1551e5d419e5f6c22a6001253c0f8531e616f35ec03ac327ffa6d
-  data.tar.gz: 9e514b570fca4bf16afb4110cb9ee3d10713306626e93f3a3fc435d729b7bef3
+  metadata.gz: 3dc3ba94cb3bbe53858813d40a054636f6b445a39fa7c52fcd0a8839e1fb6af0
+  data.tar.gz: 0a9f87dd6be3ed968f7a24d0110e0a59d52074d0a582ee8dd69ee430bf126784
 SHA512:
-  metadata.gz: 28ace5f87d6884920b5f99072306d693b7fcb61b7ee0c1162b8d498c33a67a5b54f63ef1e61277d92523ebc1433fc281254d959ed88e914c2ccc60157c19ac25
-  data.tar.gz: 67e448df315fae10c0faa563da2e0c7c5da4af21f03e0e801ed8018f44e981dcd9e1a881dd3038dd637a4a30a40ce40973ad178dd181ff4b6358d6d6438b5635
+  metadata.gz: 71a238775cdcfee13478fded9dee238e7abc374bd481ff0a8e4995616f329d6490efe939b0fc4bd4d8ae4fb8ab2b8622f44b162aa89c94fb1152570d0f1a8a9b
+  data.tar.gz: ef6f072e79dd25da4149fd47db1abbc33b0c97afd198835c97d36b5f1624e23e2245affef488fc931b323ba3e1a9842a45f3177c4b14abf1740d9121d351da42

data/CHANGELOG.md

@@ -5,6 +5,110 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2026-10-19
+
+Behaviour changes to review before upgrading: see [UPGRADING.md](UPGRADING.md).
+
+### Added
+
+- `container_gutter` spacing token (16px) and `$am-container-gutter`: the first
+  and last column of a row carry it as an outer, border-box, inlined padding;
+  nested columns do not repeat it.
+- `<title>` in the layout head, set to the message subject (new
+  `layouts/activemail/_document_head` partial).
+- Quality rules, on by default and disableable: `title`, `anchor_href`,
+  `placeholder` (`BuiltinRules::PLACEHOLDER`), `unsupported_color`,
+  `text_entities`.
+- `Quality::Configuration#allow_declined` and the `allow_declined:` option of
+  `Guard#violations`, `Guard#valid?`, `assert_email_quality` and
+  `be_a_valid_email`.
+- `Quality::Configuration#rule_exemptions` (by preview name or `preview#email`) and
+  the `skip:` option of `Guard#violations`, `Guard#valid?`, `assert_email_quality`
+  and `be_a_valid_email`: exempt a preview from named rules, built-in or custom,
+  without disabling them for every preview.
+- `mso-padding-alt` on the button cell so Outlook keeps the padding.
+- Below the container width, stacked columns take the container gutter on both
+  sides in clients that keep media queries.
+
+### Changed
+
+- A nested `<columns>` ghost cell and `max-width` are computed against the
+  content box of the enclosing columns (their share minus their padding)
+  instead of the container.
+- The MSO ghost cell of a column wraps it in its own `<table><tr>` (the `<th>`
+  used to sit directly in a `<td>`).
+- Conditional comments use `<!--[if mso]>` instead of `<!--[if mso | IE]>`.
+- `<button>` and `<cta>`: the fill and the radius live on the cell only; the
+  `<a>` carries `display:inline-block`, the body font and a `1.25` line height.
+  The dark-mode fill targets the cell.
+- `<center>` renders a `<center align="center" class="float-center">` and no
+  longer rewrites its children.
+- A mailer that declines to send (`NullMail`) is a `declined` violation unless
+  allowed.
+- The generated layouts render the same `_document_head`, `_head` and `_footer`
+  partials as the gem layout.
+- With Premailer the parsed framework CSS is cached per stylesheet fingerprint
+  (a FIFO of 16) instead of being re-parsed for every email.
+
+### Removed
+
+- The `.columns.first.last` SCSS rule: a lone column now takes both container
+  gutters through `.first` and `.last`.
+
+## [2.0.0] - 2026-10-16
+
+Breaking release: see [UPGRADING.md](UPGRADING.md).
+
+### Fixed
+
+- Emails rendered by a real Rails app shipped without the framework CSS: the
+  stylesheet lookup probed `config.assets` (an `OrderedOptions` that answers
+  every `respond_to?` with `nil`) and the `<link>` fallback was stripped by
+  Premailer. Assets are now read from the actual Sprockets environment/manifest
+  or Propshaft load path.
+- Propshaft hosts no longer risk a boot crash on `assets.precompile`.
+- `<raw>` content is no longer transformed when the layout re-rendered the view,
+  and an author's literal `###RAW0###` is left intact.
+- The word "doctype" in content and `&nbsp;`-like characters inside `<style>`
+  are no longer rewritten.
+- Numeric attributes are parsed in strict base 10 (`"010"` was read as 8).
+- `<cta>`, `<info-box>`, `<spacer>` and `<block-grid>` keep `id`, `aria-*`,
+  `data-*` and the author's `style`.
+- Column widths only count sibling columns (a sibling `<p>` skewed them).
+- The secondary button and info-box tokens now reach the stylesheet and dark
+  mode (1.1.0 announced it, but the SCSS ignored them).
+- `.h-line`, `.block-grid.up-N`, `.menu`, `.expander` had no CSS.
+- `render_all` refuses an `output_dir` outside the app and only deletes its own
+  files (it used to `rm_rf` the whole directory).
+- The responsive breakpoint follows `container_width` instead of a fixed 596px.
+- Code annotations are registered for the real `inky-*` extensions.
+
+### Changed
+
+- One transpilation and one inlining pass per email, hooked on
+  `ActionMailer::Base#render_to_body`; text parts, attachments and
+  non-ActiveMail emails are untouched.
+- `activemail_inline_styles(*paths)` embeds host stylesheets too and raises
+  `ActiveMail::StylesheetNotFound` instead of warning.
+- `<button>` and `<cta>` share one bulletproof, token-styled, inlined rendering.
+- SCSS uses the module system (`@use`/`@forward`, `sass:color`, `sass:math`).
+- Transpilation is linear in the document size (200 nested rows: ×3.7,
+  2,000 raw blocks: ×35) and reuses a memoized `Core`.
+- `Quality::Guard` is extensible with `Quality::Rule` and gains
+  `translation_missing`, `single_root`, `text_part_present`, `text_part_plain`.
+- `Quality` gains `locales`, `formats`, `around_each` and `output_filters`.
+- Errors share the `ActiveMail::Error` base class.
+
+### Removed
+
+- `ActiveMail::Inliner::Interceptor` and `config.register_inline_interceptor`.
+- `ActiveMail::CompiledStylesheet` (replaced by `ActiveMail::AssetPipeline`).
+- The `<inky>` tag.
+- `IGNORED_ON_PASSTHROUGH`, `combine_attributes`, `pass_through_attributes`,
+  `bulletproof_button_table` and `BUTTON_PADDING`.
+- `stylesheet_link_tag` from the layouts.
+- The manual `workflow_dispatch` release trigger.
+
 ## [1.2.3] - 2026-10-09
 
 ### Changed
@@ -61,8 +165,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `<button>` and `<cta>` share a `bulletproof_button_table` scaffold; `<cta>`
   drops its hardcoded `4px` radius in favor of the `radius` token.
 - The corner radius is now applied by default on `.button`/`.cta` (the opt-in
-  `.radius` class is gone); `.button.secondary`/`.cta.secondary` mirror the
-  secondary color/border tokens.
+  `.radius` class is gone).
 
 ### Removed
 
@@ -138,5 +241,7 @@ toolkit for Rails.
 - Rails `>= 7.1` (tested up to 8.1).
 - Nokogiri `>= 1.16`.
 
+[2.1.0]: https://github.com/AdVitam/activemail/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/AdVitam/activemail/compare/v1.2.3...v2.0.0
 [1.0.1]: https://github.com/AdVitam/activemail/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/AdVitam/activemail/releases/tag/v1.0.0

data/README.md

@@ -35,14 +35,14 @@ renders consistently from Apple Mail to Outlook (Word engine) to Gmail mobile.
 - **Automatic CSS inlining** via a pluggable adapter (premailer by default, roadie
   optional, or your own).
 - **Generators** to install, eject views/styles, and scaffold components.
-- **Opt-in quality layer**: a Guard (size, `role`, `alt`, `lang`), preview
+- **Opt-in quality layer**: a Guard (size, `role`, `alt`, `lang`, `title`, links, placeholders), preview
   renderer, Minitest assertions + RSpec matcher, and a `render_all` rake task.
 
 ## Installation
 
 ```ruby
 # Gemfile
-gem 'activemail', '~> 1.0'
+gem 'activemail', '~> 2.1'
 ```
 
 ```bash
@@ -55,7 +55,8 @@ framework stylesheet. It works zero-config; customize only what you want.
 
 Name a mailer view `welcome.html.inky` (or compose with another engine:
 `welcome.html.inky-erb`, `.inky-slim`, `.inky-haml`) and it is transpiled on
-render. CSS is inlined automatically before delivery.
+render. Each email is transpiled and its CSS inlined exactly once, when the
+mailer renders it (view and layout together).
 
 ## Configuration
 
@@ -70,15 +71,12 @@ ActiveMail.configure do |config|
   # CSS inliner: :premailer (default), :roadie, :null, or a custom
   # ActiveMail::Inliner::Base subclass/instance.
   config.inliner = :premailer
-  # Set false if another inliner (e.g. premailer-rails) already runs on mailers;
-  # `config.inliner = :null` also fully short-circuits ActiveMail's interceptor.
-  config.register_inline_interceptor = true
 
   # Design tokens (see below).
   config.tokens.color :primary, '#2a9d8f'
 
   # Custom components (see "Custom components").
-  config.register_component 'cta', ActiveMail::Components::Cta
+  config.register_component 'divider', Divider
 end
 ```
 
@@ -106,7 +104,11 @@ ActiveMail.tokens.color(:primary) # => "#2a9d8f"
 ```
 
 Defaults are neutral (a calm teal `primary`, near-black `text`, white
-`background`, …) and fully overridable. Under Sprockets the SCSS bridge is a
+`background`, …) and fully overridable. Optional tokens fall back to a base
+token: `primary_text`/`secondary_text` → `button_text`, `primary_border`/
+`secondary_border` → none, `info_box_background`/`_border`/`_text` →
+`background`/`border`/`text`. Ruby components and the stylesheet read the same
+resolved values. Under Sprockets the SCSS bridge is a
 preprocessed partial; under Propshaft run `rake activemail:tokens:export` to
 materialize a static `_activemail_tokens.scss`.
 
@@ -118,13 +120,25 @@ hooks (`.button`, `.cta`, `.callout`, `.spacer`, …), utilities, and dark mode.
 
 Override at three levels, cheapest first:
 
-1. **Tokens** (Ruby) — covers most theming.
+1. **Tokens** (Ruby) — covers most theming. Any framework variable can also be
+   configured from your own stylesheet with the Sass module system:
+
+   ```scss
+   // app/assets/stylesheets/emails/emails.scss
+   @use "activemail/activemail" with (
+     $am-button-secondary-color: #264653,
+     $am-breakpoint: 640px
+   );
+   ```
+
 2. **`bin/rails g activemail:styles`** — eject the SCSS partials into your app to
    edit them; your copies shadow the gem's.
 3. **`bin/rails g activemail:views`** — eject the default layout + partials
    (`app/views/layouts/activemail/*`); a same-named file in your app wins by
    Rails path precedence. Put your logo/header/footer here — those are the app's
-   identity, not the gem's.
+   identity, not the gem's. The `<head>` lives in `_document_head` (metas,
+   `<title>` set to the message subject, Outlook settings, inlined styles) and
+   is shared by the default layout and the generated one.
 
 Dark mode ships on: a `<style>` block keys off `prefers-color-scheme: dark` (Apple
 Mail/iOS) and Outlook's `[data-ogsc]`, with surfaces derived from your tokens.
@@ -132,9 +146,24 @@ Mail/iOS) and Outlook's `[data-ogsc]`, with surfaces derived from your tokens.
 ## CSS inlining
 
 Email clients (Gmail mobile, Orange.fr) strip `<style>`, so critical CSS must be
-inlined. ActiveMail registers an ActionMailer interceptor that runs the configured
-inliner on every outgoing HTML part — your `<style>` enhancement block (media
-queries, dark mode) is preserved.
+inlined. When a mailer renders an inky HTML template, ActiveMail transpiles the
+whole body (view + layout) and runs the configured inliner once. Text parts,
+attachments and non-ActiveMail emails are never touched; your `<style>`
+enhancement block (media queries, dark mode) is preserved. With Premailer the
+parsed framework CSS is cached per stylesheet, so it is parsed once, not once per
+email.
+
+The layout embeds the compiled stylesheets with `activemail_inline_styles`
+(Sprockets or Propshaft); pass your own on top of the framework's:
+
+```erb
+<%= activemail_inline_styles %>                  <%# framework only %>
+<%= activemail_inline_styles "emails/emails" %>  <%# your stylesheet @use-ing the framework %>
+```
+
+A missing or empty asset raises `ActiveMail::StylesheetNotFound`: an email is
+never sent unstyled. An inliner failure raises `ActiveMail::Inliner::Error`
+(the adapter's exception is kept as `#cause`).
 
 ```ruby
 config.inliner = :premailer   # default, hard dependency
@@ -157,11 +186,11 @@ Fluid-hybrid wrapper, capped at `container_width`, wrapped in an MSO ghost table
 ```
 
 ```html
-<!--[if mso | IE]><table role="presentation" align="center" width="600">...<![endif]-->
+<!--[if mso]><table role="presentation" align="center" width="600">...<![endif]-->
 <table class="container" align="center" style="width:100%;max-width:600px;margin:0 auto;">
   <tbody><tr><td>...</td></tr></tbody>
 </table>
-<!--[if mso | IE]></td></tr></table><![endif]-->
+<!--[if mso]></td></tr></table><![endif]-->
 ```
 
 ### `<row>` / `<columns>`
@@ -176,21 +205,39 @@ media-query enhancement.
 ```
 
 Column widths are computed as `container_width × large / column_count`, capped
-at `container_width`, **with no gutter model**: two `large="6"` columns sit
-edge-to-edge (300px + 300px in a 600px container). Add padding inside your
-columns for gutters, and keep the `large` sizes of a row summing to at most
-`column_count`, otherwise the ghost cells will wrap in Outlook.
+at `container_width`. A nested `<columns>` is sized against its enclosing column
+(a `large="6"` inside a `large="6"` is 150px in a 600px container). Keep the
+`large` sizes of a row summing to at most `column_count`, otherwise the ghost
+cells will wrap in Outlook.
+
+Gutters are border-box padding inlined on the columns: `gutter` (8px) on each
+side between two columns, and `container_gutter` (16px) on the outer edge of the
+first and last column, so content never touches the screen edge. A nested row
+adds no outer gutter. Both are spacing tokens
+(`config.tokens.spacing :container_gutter, '0px'` restores edge-to-edge columns)
+and SCSS variables (`$am-gutter`, `$am-container-gutter`).
 
 ### `<button>`
 
-Bulletproof button: the padding lives on the `<a>` so the whole control is
-clickable. Variant classes (`primary`, `expand`, …) are preserved.
+Bulletproof button styled inline from the tokens (`Tokens#button_style`): the
+padding lives on the `<a>` so the whole control is clickable (mirrored on the
+cell with `mso-padding-alt` for Outlook), the fill and radius sit on the cell
+only, and a variant border sits on the cell as well. `class="secondary"` selects the secondary variant;
+`expand` makes it full width; without `href` the label renders as a `<span>`.
 
 ```html
-<button href="#">Go</button>
+<button href="#" class="secondary">Go</button>
 ```
 
-`<button class="expand">` adds a centered link and an `.expander` cell.
+```html
+<table class="secondary button"><tbody><tr><td>
+  <table><tbody><tr>
+    <td style="background:#264653;border-radius:4px;mso-padding-alt:12px 24px;">
+      <a href="#" style="display:inline-block;text-decoration:none;padding:12px 24px;font-family:Arial, sans-serif;line-height:1.25;color:#ffffff;font-weight:bold;">Go</a>
+    </td>
+  </tr></tbody></table>
+</td></tr></tbody></table>
+```
 
 ### `<menu>` / `<item>`
 
@@ -222,17 +269,13 @@ clickable. Variant classes (`primary`, `expand`, …) are preserved.
 ### `<wrapper>`, `<h-line>`, `<center>`
 
 - `<wrapper class="header">` → `<table class="header wrapper" align="center" style="width:100%;">` with a `.wrapper-inner` cell.
-- `<h-line>` → a full-width single-cell table for a horizontal rule.
-- `<center>` adds `align="center"` and `.float-center` to its element children (and `.float-center` to nested menu items).
-
-### `<inky>`
-
-Renders a bare `<tr>`, useful inside hand-written tables.
+- `<h-line>` → a full-width single-cell table drawn as a 1px rule in the `border` color.
+- `<center>` renders a `<center align="center" class="float-center">` around its content and leaves the content untouched.
 
 ### `<raw>`
 
 Anything between `<raw>` and `</raw>` is passed through untouched (multi-line
-supported). Raw blocks cannot be nested.
+supported), including through the layout. Raw blocks cannot be nested.
 
 ```html
 <raw><% liquid_or_mso_conditional %></raw>
@@ -240,28 +283,28 @@ supported). Raw blocks cannot be nested.
 
 ### Token-driven built-ins: `<cta>` and `<info-box>`
 
-Brand-neutral, token-styled components shipped with the gem but **not registered
-by default** (so they never collide with your tags). Register them to use:
-
-```ruby
-config.register_component 'cta', ActiveMail::Components::Cta
-config.register_component 'info-box', ActiveMail::Components::InfoBox
-```
+Brand-neutral, token-styled components, registered by default.
 
 ```html
 <cta href="https://example.com">Go</cta>
 <cta href="#" class="secondary">Also go</cta>
 ```
 
-`<cta>` renders a bulletproof button using `tokens.color(:primary)` (or
-`:secondary` with `class="secondary"`); it raises if `href` is missing.
+`<cta>` renders exactly like `<button>` with a `cta` class; it raises if `href`
+is missing. `<info-box>` is a callout styled from the `info_box_*` tokens.
+
+Every component keeps the author's `class` and `style` (merged, never
+duplicated) and passes `id`, `aria-*`, `data-*` and other attributes through to
+its root element.
 
 ## Custom components
 
 Register your own tag with a class that inherits from
 `ActiveMail::Components::Base` and implements `#transform(node, inner)`. You get
-the matched Nokogiri node (full DOM access) and the already-transformed inner
-HTML; return the replacement markup string. The generator scaffolds one:
+the matched Nokogiri node (read its attributes) and `inner`, an opaque slot
+standing for the already-transformed children: interpolate it exactly once where
+the children belong, never parse or alter it (dropping or duplicating it raises
+`ActiveMail::Error`). Return the replacement markup string. The generator scaffolds one:
 
 ```bash
 bin/rails g activemail:component Divider
@@ -272,19 +315,21 @@ The generator namespaces the class as `Components::Divider` (under
 A minimal hand-written equivalent:
 
 ```ruby
-class Divider < ActiveMail::Components::Base
-  def transform(node, _inner)
-    klass = combine_classes(node, 'divider')
-    %(<table class="#{klass}" #{TABLE_RESET} style="width:100%;"><tbody><tr><td></td></tr></tbody></table>)
+class Divider < ActiveMail::Components::TableComponent
+  def transform(node, inner)
+    %(<table#{root_attributes(node, classes: 'divider', layout_style: 'width:100%;')} #{TABLE_RESET}><tbody><tr><td>#{inner}</td></tr></tbody></table>)
   end
 end
 
 ActiveMail.configuration.register_component('divider', Divider)
 ```
 
-Helpers available from `Base`: `combine_classes`, `combine_attributes`,
-`pass_through_attributes`, `class?`, `target_attribute`, `escape_attr`,
-`style_attribute`, `column_count`, `container_width`.
+`root_attributes` emits the merged `class`, the merged `style` and every
+pass-through attribute; override `consumed_attributes` to list the attributes
+your component reads itself (they are not passed through). `TableComponent`
+already consumes the `TABLE_RESET` attributes (`role`, `border`, …) of a layout
+table root; inherit from `Base` for any other root element. Other helpers:
+`class?`, `escape_attr`, `column_count`, `container_width`.
 
 Per-instance overrides (including replacing a built-in tag) are also possible:
 
@@ -314,9 +359,15 @@ class MailerTest < ActiveSupport::TestCase
   include ActiveMail::Quality::Minitest
 
   test 'welcome email is sound' do
-    assert_email_quality(rendered_html)
+    assert_email_quality(WelcomeMailer.welcome(user)) # a message, or an HTML string
   end
 end
+
+class EmailPreviewsTest < ActiveSupport::TestCase
+  include ActiveMail::Quality::Minitest
+
+  assert_quality_for_all_previews # one test per preview email and locale
+end
 ```
 
 ```ruby
@@ -326,19 +377,52 @@ require 'activemail/quality/rspec'
 expect(rendered_html).to be_a_valid_email
 ```
 
-The Guard checks byte size (Gmail clips ~102 KB), `role="presentation"` on every
-table, `alt` on every image, and `lang` on full documents — all thresholds
-configurable:
+The Guard checks byte size (Gmail clips ~102 KB), parse errors,
+`role="presentation"` on every table, `alt` on every image, `lang` on full
+documents, a single `<html>`/`<body>`, missing translations, a non-blank
+`<title>`, an `href` on every link, unresolved `{{placeholders}}`, CSS colors
+clients ignore (`rgb(… %)`, `hsl()`, `color-mix()`, `var()`), and — given a
+message — a plain text part free of HTML entities. A mailer that declines to
+send (`NullMail`) is a violation unless it is listed in `allow_declined`
+(`assert_email_quality(mail, allow_declined: true)` or
+`be_a_valid_email(allow_declined: true)` for one call). Built-in rules can be
+disabled and your own added; a single email can also be exempt from a rule
+(`assert_email_quality(html, skip: %i[img_alt])`, `be_a_valid_email(skip: …)`, or
+`rule_exemptions` below) while every other rule still applies to it. A name the
+guard does not know raises an `ArgumentError` before any preview renders; a
+disabled rule is a known name.
 
 ```ruby
+signature = ActiveMail::Quality::Rule.html(:single_signature) do |doc, _html|
+  'signature rendered twice' if doc.css('.signature').size > 1
+end
+
 ActiveMail::Quality.configure do |c|
   c.required_previews = %w[welcome_mailer#welcome]
-  c.guard = ActiveMail::Quality::Guard.new(max_bytes: 90_000)
+  c.allow_declined = %w[reminder_mailer#maybe_skipped] # previews allowed to return a NullMail
+  c.rule_exemptions = {                      # a preview name covers all its emails
+    'legacy_mailer' => %i[img_alt],
+    'welcome_mailer#welcome' => %i[single_signature]
+  }
+  c.guard = ActiveMail::Quality::Guard.new(max_bytes: 90_000, disable: %i[img_alt], rules: [signature])
+  c.locales = %i[fr en]                      # or ->(preview) { [...] }; each preview gets params[:locale]
+  c.formats = %i[html text]
+  c.around_each = lambda do |_preview, _email, _locale, &render|
+    ActiveRecord::Base.transaction { render.call; raise ActiveRecord::Rollback } # previews leave no data behind
+  end
+  c.output_filters = [[/\h{8}-\h{4}-\h{4}-\h{4}-\h{12}/, '<uuid>']] # applied to written files only
+  c.output_dir = 'tmp/email_previews'        # relative, inside Rails.root
 end
 ```
 
-`rake activemail:emails:render_all` renders every ActionMailer preview to disk
-for visual diffing and fails on any guard violation among `required_previews`.
+`Rule.html` blocks receive the parsed document and the raw HTML; `Rule.message`
+blocks receive the `Mail::Message`. Return `nil`, a message or an array of
+messages.
+
+`rake activemail:emails:render_all` renders every ActionMailer preview (each
+locale and format) to `output_dir` for visual diffing and fails on any guard
+violation among `required_previews`. It only replaces its own `.html`/`.txt`
+files.
 
 ## Email-client compatibility policy
 
@@ -356,7 +440,8 @@ Targets the real-world client landscape as of 2026:
 ## Programmatic use
 
 ```ruby
-ActiveMail::Core.new.transpile('<container><row><columns>Hi</columns></row></container>')
+ActiveMail.configuration.core.transpile('<container><row><columns>Hi</columns></row></container>')
+ActiveMail::Pipeline.call(source) # transpile + inline
 ActiveMail::Core.new(column_count: 24, container_width: 480).transpile(source)
 ```