docs(35): decision note for mail CSS inlining with go-premailer

- go-premailer pinned at v1.38.0, facts checked, MVS changes and the
  indirect modules tidy adds, rejected alternatives
- supersedes D-10's inlining claim and lifts 35-01's default.htm gate;
  Branding gains a site name with the mail.from fallback
- STACK.md Supporting Libraries row
This commit is contained in:
Jakub Zych
2026-11-13 20:55:30 +01:00
parent 093529d45c
commit dcd0ae5338
2 changed files with 42 additions and 0 deletions

View File

@@ -0,0 +1,41 @@
# Decision: finished built-in mail layouts and CSS inlining through github.com/vanng822/go-premailer
**Date:** 2026-11-13
**Status:** Accepted
**Context:** Phase 35 UAT gap G-35-8 (35-UAT.md, test 8, severity major), debug session `.planning/debug/mail-layouts-unstyled.md`, Jakub's decision of 2026-11-13 (framework only; the plugin layouts and templates follow after the framework tag), plan 35-06
## What this supersedes
- **D-10's inlining claim.** 35-CONTEXT D-10 says the Branding colours "compile into the brand CSS slot that postcard already inlines". postcard never inlined: it placed the brand CSS and `mail.css` in the layout's style block and nothing more, so mail clients that drop style blocks showed unstyled mail. From this decision on, postcard inlines the CSS at render (below).
- **35-01's "default.htm unchanged" gate.** Plan 35-01 kept `modules/postcard/assets/default.htm` byte-identical (a bare `content-body` block). That gate is lifted: the default layout is now WinterCMS's default layout (wrapper, header with the logo or the name, white card, copyright footer), built on two new built-in partials, `header` and `footer`.
- **D-10's Branding fields.** Branding gains a **Site name** (`site_name` column, `postcard.Brand.SiteName`). Empty, it falls back to the display name of `mail.from` (`Acme` for `Acme <no-reply@acme.test>`). Layouts get it as `{{ .siteName }}`, next to `{{ .year }}`, the current year.
## Decision
- **`github.com/vanng822/go-premailer` pinned at exactly v1.38.0**, package `premailer`, with its default options: `RemoveClasses` false (class attributes stay, so plugin CSS hooks and the leftover style rules still match), `CssToAttributes` true (CSS widths and heights are mirrored to `width`/`height` attributes, as mail clients expect), `KeepBangImportant` false.
- **Where it runs.** In postcard's render path (`renderParts`), so the admin preview, the test send and real sends get the same HTML: after the layout's HTML wrapper has rendered and passed `validateHTML`, the HTML goes through `NewPremailerFromString(...).Transform()`, and the result is checked by `validateHTML` again. The plain-text part is never touched.
- **What it does.** It collects the rules of the document's style elements (the brand CSS, the layout's own CSS and `mail.css`), applies them to the matching elements by specificity, removes the style elements, and puts the rules it cannot inline (media queries, pseudo-classes such as `:hover`, selectors with `*`) back in one style element in the head, marked `!important`. The DOCTYPE line is kept.
- **Error fallback.** An inliner error (or a panic inside it, recovered) never stops mail: the un-inlined HTML is sent with its style block, and a warning keyed `inline:<layout code>` is logged at most once per warn interval (D-14 spirit).
- **Opt-out, with WinterCMS's option name.** A file layout opts out with the header key `disable_auto_inline_css` (`true`, `1` or `yes`, any case); a database layout with the boolean column `disable_auto_inline_css` of `system_mail_layouts` (migration `202611130003_mail_layout_disable_auto_inline_css`), edited by a switch on the layout form's CSS tab. An opted-out layout keeps only its style block. The built-in layouts all inline. This matches `MailManager::renderTemplate` in WinterCMS, which runs CssToInlineStyles unless the layout's `disable_auto_inline_css` option is set.
## Facts checked (2026-11-13)
- **Versions and dates.** `go list -m -versions` lists v1.38.0 as the latest tag. proxy.golang.org reports v1.38.0 published 2026-11-04T18:13:54Z (origin `https://github.com/vanng822/go-premailer`, tag `refs/tags/v1.38.0`, commit `98a25222c9ea2827cfc13dd8f162976703574435`), nine days before this decision and past the 7-day cooldown; v1.37.0 was published 2026-10-02, so releases come roughly monthly. Module sum `h1:nYXopG+L6lcRV6dEAemLLE71bihun3gxgfNJZ9iYm1Q=`, go.mod sum `h1:6Jcm7sYO8ON3J/IIlox2fWq+YPgGopwx7VbETlZRZtY=`, both verified against the checksum database by `go mod download`.
- **Licence and maintainer.** MIT (`LICENSE`: Copyright (c) 2015 Nguyen Van Nhu); maintained by its author since 2015. pkg.go.dev listed 246 importing packages at planning time.
- **Its requirements.** `github.com/PuerkitoBio/goquery` v1.13.0, `github.com/inbucket/html2text` v1.0.0, `github.com/vanng822/css` v1.0.1, `golang.org/x/net` v0.62.0 (and `github.com/stretchr/testify` for its own tests). Its go.mod says `go 1.26.0`; this repository is at go 1.27.0.
- **What MVS changes here** (dry run of `go get` and `go mod tidy` on a scratch copy of go.mod): `golang.org/x/net` v0.58.0 to v0.62.0, `golang.org/x/crypto` v0.57.0 to v0.58.0, `golang.org/x/text` v0.42.0 to v0.43.0, `golang.org/x/term` v0.46.0 to v0.47.0, and the indirect `golang.org/x/sys` v0.48.0 to v0.49.0 and `golang.org/x/sync` v0.23.0 to v0.24.0.
- **Modules `go mod tidy` adds as indirect.** `github.com/PuerkitoBio/goquery` v1.13.0, `github.com/andybalholm/cascadia` v1.3.4, `github.com/inbucket/html2text` v1.0.0, `github.com/vanng822/css` v1.0.1, and through html2text's table rendering `github.com/olekukonko/tablewriter` v1.0.7, `github.com/olekukonko/errors` v1.1.0, `github.com/olekukonko/ll` v0.0.9, `github.com/fatih/color` v1.18.0, `github.com/mattn/go-colorable` v0.1.14, `github.com/mattn/go-isatty` v0.0.20 and `github.com/ssor/bom` v0.0.0-20170718123548-6386211fdfcf. `github.com/gorilla/css` v1.0.1 was already in the module graph.
- **Fit check** (the default layout with the brand CSS and a media query in `mail.css`, before the go.mod change, through a scratch modfile): the DOCTYPE line was kept, class attributes were kept, the button link carried `background-color:#d66829` in its style attribute, the media query stayed in a style element, and the output passed `validateHTML`.
## Consequences
- The framework go.mod requires `github.com/vanng822/go-premailer v1.38.0`; only `modules/postcard/inline.go` imports it. Every binary that links postcard links it, goquery, cascadia, html2text and tablewriter.
- **Follow-up for consumers.** Applications and plugins that build against this checkout with a `replace` (sm-demo-app, sm-user-plugin, sm-paymentgateway-plugin and others) need `go mod tidy` to get the new go.sum lines; until then `go build` and `go test` in them report missing go.sum entries. Their trees are not changed in 35-06; the bump comes after the framework tag.
- The style block of an inlined message holds only the leftover rules, not the brand CSS and `mail.css`. Tests and tools that read the style block for the brand CSS read the style attributes instead, or use a layout that opts out.
- A CSS value an administrator writes is copied into style attributes. `validateHTML` runs on the inlined HTML, so a `javascript:`, `vbscript:` or `data:` address that reaches an attribute fails the render as before (and a failing override falls back to the file version, D-14).
## Rejected alternatives
- **An in-house inliner on `golang.org/x/net/html` with douceur and cascadia.** No new top-level module, but postcard would own selector specificity, cascade order, `!important`, media-query leftovers and the attribute mirroring, with their edge cases.
- **`github.com/aymerick/douceur/inliner`.** Unmaintained since 2016.
- **No inlining.** The UAT gap stays for every client that drops style blocks (several webmail clients and Outlook variants).

View File

@@ -49,6 +49,7 @@ This extends `.planning/research/go-ecosystem.md` (2026-09-16 GitHub-API-verifie
| `github.com/markbates/goth` (core plus providers google, facebook, github, azureadv2; never gothic) | v1.82.0 | OAuth 2.0 client for social sign-in in sm-sociallogin-plugin | Decided in .planning/notes/2026-10-20-sociallogin-goth.md (Phase 19.5 D-02); plugin-only, the framework go.mod does not require it. |
| `github.com/chromedp/chromedp` | v0.21.0 (Oct 11, 2026; pinned exactly, newer tags deliberately not used) | Optional raw-versus-rendered comparison of the SEO site audit in sm-seo-plugin, driving an operator-installed Chrome or Chromium (`golem15.seo.crawl_chrome_path`) | Decided in .planning/notes/2026-10-28-chromedp-rendered-crawl.md (Phase 33 D-70, P33-55); pure Go, no cgo or Node; plugin-only, the framework go.mod does not require it. |
| `github.com/gen2brain/webp` | v0.6.4 (Jul 1, 2026; pinned exactly, with `github.com/ebitengine/purego` v0.10.1) | WebP variants of attachment thumbnails (`modules/lagoon/attach/webp`, quality 80), encoded in a conga job of sm-journal-plugin | Decided in .planning/notes/2026-10-28-webp-gen2brain.md (Phase 33 D-85, P33-42); no cgo: the system libwebp through purego, else libwebp transpiled to Go (wasm2go). Only binaries that import the sub-package link it, and they are dynamically linked against glibc unless built with `-tags nodynamic`. |
| `github.com/vanng822/go-premailer` | v1.38.0 (Nov 4, 2026; pinned exactly) | Inline mail CSS onto elements at render (postcard, preview, test send and sends), WinterCMS's CssToInlineStyles step, with a per-layout `disable_auto_inline_css` opt-out | Decided in .planning/notes/2026-11-13-mail-layouts-css-inlining.md (Phase 35, G-35-8, supersedes D-10's inlining claim); MIT; imported only by modules/postcard; brings goquery, cascadia, html2text and tablewriter as indirect modules and raises golang.org/x/net to v0.62.0. |
| `github.com/jimsmart/grobotstxt` | v1.0.3 | Google-faithful robots.txt matching (longest match, allow wins ties, `*` and `$`, matching line) for the robots.txt tester and the noindex-blocked warning in sm-seo-plugin | Decided in .planning/notes/2026-10-27-robots-txt-grobotstxt.md (Phase 32 D-99); plugin-only, the framework go.mod does not require it. |
| `charm.land/lipgloss/v2` | v2.0.6 | Console styles, layout and tables (bonfire palette, diary console handler) | Decided in .planning/notes/2026-10-21-console-charm-stack.md (Phase 19.8 D-02); imported only by modules/bonfire and modules/diary |
| `charm.land/bubbletea/v2` | v2.1.0 | Runtime for the live spinner, process and progress views | Decided in .planning/notes/2026-10-21-console-charm-stack.md (Phase 19.8 D-02); imported only by modules/bonfire and modules/diary |