diff --git a/.planning/notes/2026-11-13-mail-layouts-css-inlining.md b/.planning/notes/2026-11-13-mail-layouts-css-inlining.md new file mode 100644 index 00000000..07e79bb9 --- /dev/null +++ b/.planning/notes/2026-11-13-mail-layouts-css-inlining.md @@ -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 `). 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:` 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). diff --git a/.planning/research/STACK.md b/.planning/research/STACK.md index 09d82011..3625cbbe 100644 --- a/.planning/research/STACK.md +++ b/.planning/research/STACK.md @@ -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 |