docs(35): diagnose UAT gaps G-35-1 and G-35-8
This commit is contained in:
146
.planning/debug/mail-layouts-unstyled.md
Normal file
146
.planning/debug/mail-layouts-unstyled.md
Normal file
@@ -0,0 +1,146 @@
|
||||
---
|
||||
status: diagnosed
|
||||
trigger: "UAT gap G-35-8: logo doesn't appear, only kind of proper layout is System layout (logo doesn't show, Aktywuj konto on activate email doesn't seem to be a button, totally unstyled), other layouts sucks, I expect beautiful and working out of box layouts after this phase."
|
||||
created: 2026-11-13T00:00:00Z
|
||||
updated: 2026-11-13T16:05:00Z
|
||||
goal: find_root_cause_only
|
||||
---
|
||||
|
||||
## Current Focus
|
||||
|
||||
bug_class: Bohrbug (deterministic; reproduced outside the SPA with a scratch render, every run)
|
||||
hypothesis: CONFIRMED — the Phase 35 plumbing works (logoUrl var, brand CSS, button partial), but no shipped content consumes it: no layout prints {{ .logoUrl }}, plugin templates use plain Markdown links instead of the button partial, and the default + plugin layouts are bare stubs without Winter's wrapper/header/card/footer structure.
|
||||
test: scratch render of golem15.user::mail.activate across user/system/default/minimal layouts with a Brand carrying LogoURL
|
||||
expecting: logo URL count 0 and `class="button` count 0 in all layouts (observed); button partial call renders a styled button (observed)
|
||||
next_action: return ROOT CAUSE FOUND (diagnose-only mode)
|
||||
|
||||
reasoning_checkpoint:
|
||||
hypothesis: "Logo/buttons/structure are missing because the shipped layout and template files never reference logoUrl, the button partial, or the wrapper/header/footer classes the brand CSS styles — not because of preview, URL or CSS-delivery failures."
|
||||
confirming_evidence:
|
||||
- "grep: logoUrl appears in no .htm layout in postcard, sm-user-plugin or sm-paymentgateway-plugin; only in docs and test-only overrides"
|
||||
- "scratch render: 0 logo occurrences, 0 class=button in all 4 layouts; brand CSS with saved colour present"
|
||||
- "same render with {{ partial \"button\" ... }} produces class=\"button button-primary\""
|
||||
- "plugin layouts are `<div class=\"layout-user|layout-paymentgateway\">{{ .Content }}</div>` (stubs from phases 07-03/18-04); default.htm is `<div class=\"content-body\">` and 35-01 forbade touching it"
|
||||
falsification_test: "Adding `{{ if .logoUrl }}<img src=\"{{ .logoUrl }}\">{{ end }}` to a layout and rendering with the same Brand must show the logo URL; if it did not, the wiring would be at fault. brand_smoke_test 'logo' subtest already shows it does."
|
||||
fix_rationale: "Ship finished layouts (Winter default port with header/logo + footer; logo in system) and switch plugin CTAs to the button partial — addresses missing consumers, which is the root cause; plumbing needs no change."
|
||||
blind_spots: "Did not drive the actual SPA preview with an admin session (used the same postcard render path directly); did not test real mail clients for <style>-only CSS (inlining gap is from Winter parity + known client behaviour, not observed here)."
|
||||
candidate_causes:
|
||||
- "code (framework): built-in layouts lack logo slot/header/footer; default layout bare; no CSS inliner"
|
||||
- "code (plugins): templates use Markdown links; layouts are stubs"
|
||||
- "config/environment: logo URL base / public file / CSP / sandbox — eliminated"
|
||||
- "data: demo DB has customized user layout + activate overrides (masks file fixes during verification, not a cause)"
|
||||
and_gate: "yes — an out-of-box finished mail needs (a) a layout with structure and logo slot AND (b) templates calling the button partial AND (c) brand CSS for those classes (present); real-client rendering additionally needs (d) CSS inlining. Each missing piece alone produces part of the symptom."
|
||||
|
||||
## Symptoms
|
||||
|
||||
expected: Mail preview renders the template inside a polished, working layout out of the box: branding logo shows, CTA links (e.g. "Aktywuj konto" in user activate) render as styled buttons, every shipped layout (system and plugin layouts like user, paymentgateway) looks finished.
|
||||
actual: Logo does not appear (system and plugin layouts). "Aktywuj konto" is a plain link, not a button. Only the System layout looks somewhat proper; plugin layouts (user, paymentgateway) are unstyled.
|
||||
errors: none reported
|
||||
reproduction: sm-demo-app at http://127.0.0.1:8097/smbackend -> mail templates editor -> preview golem15.user::mail.activate (and paymentgateway templates); branding colours + logo saved beforehand.
|
||||
started: Phase 35 UAT (first time this feature exists)
|
||||
extra: test-send text body "Cześć **[Name]**.\n\n[Aktywuj konto]([Link])\n\nKod: [Code]" — template body is markdown with a link.
|
||||
|
||||
## Eliminated
|
||||
|
||||
- hypothesis: sandboxed preview iframe (sandbox="") or the admin CSP blocks the logo image / inline styles
|
||||
evidence: sandbox="" does not block images or <style>; admin CSP has no img-src/style-src/default-src; no COEP/CORP; brand CSS demonstrably present in output. The logo <img> is simply absent from the rendered HTML.
|
||||
timestamp: 2026-11-13T15:40Z
|
||||
|
||||
- hypothesis: logo URL is not resolved (file not public, no public_url/app.url, wrong partition key)
|
||||
evidence: brand row has logo_file_id 556, is_public; computed URL returns 200 image/png; no "mail branding logo" warning in go.log
|
||||
timestamp: 2026-11-13T15:42Z
|
||||
|
||||
- hypothesis: logoUrl is not passed to layouts during preview (preview data wiring)
|
||||
evidence: Editor.render -> m.options(ov.Brand) sets opts.logoURL; renderParts passes "logoUrl" to text and HTML wrappers (templates.go:620,630); test overrides that print it get the URL (brand_smoke_test)
|
||||
timestamp: 2026-11-13T15:43Z
|
||||
|
||||
- hypothesis: plugin layouts don't receive the brand CSS
|
||||
evidence: user.htm and paymentgateway.htm both contain <style>{{ .brandCss }}{{ .css }}</style>; repro output contains the compiled brand CSS with the saved #2974d6
|
||||
timestamp: 2026-11-13T15:45Z
|
||||
|
||||
- hypothesis: postcard cannot render buttons (no button partial / unstyled)
|
||||
evidence: built-in button partial renders class="button button-primary" and brand.css.tmpl styles .button-primary/.positive/.negative with brand colours
|
||||
timestamp: 2026-11-13T15:47Z
|
||||
|
||||
## Evidence
|
||||
|
||||
- timestamp: 2026-11-13T15:30Z
|
||||
checked: knowledge base (.planning/debug/knowledge-base.md) and resolved sessions
|
||||
found: no knowledge-base.md; resolved sessions unrelated (avatar bucket, category content, etc.)
|
||||
implication: no known-pattern candidate
|
||||
|
||||
- timestamp: 2026-11-13T15:32Z
|
||||
checked: modules/postcard/assets/{default,system,minimal}.htm
|
||||
found: none of the three built-in layouts references {{ .logoUrl }}. default.htm body is only `<div class="content-body">{{ .Content }}</div>` (no wrapper table, no header, no footer, class content-body has no CSS rule in brand.css.tmpl). system.htm has the Winter wrapper/content/body/inner-body/content-cell tables + subcopy partial but no header row/logo and no footer row. minimal.htm is bare body.
|
||||
implication: logo can never appear in any built-in layout; default layout has no card/header/footer structure so it looks unstyled
|
||||
|
||||
- timestamp: 2026-11-13T15:33Z
|
||||
checked: grep logoUrl across postcard, docs, admin, sm-user-plugin, sm-paymentgateway-plugin
|
||||
found: logoUrl only exists as render var (templates.go:620,630), in README/docs examples (`{{ if .logoUrl }}<img ...>{{ end }}`) and in test-only layout overrides (brand_smoke_test.go:220,329). No shipped .htm layout uses it.
|
||||
implication: the logo plumbing (store.go -> Brand.LogoURL -> opts.logoURL -> layout var) is wired, but the consumer (a layout that prints it) was never shipped. Tests prove the variable reaches a layout only via test overrides.
|
||||
|
||||
- timestamp: 2026-11-13T15:35Z
|
||||
checked: ../sm-demo-app/plugins/golem15/user/views/mail/layouts/user.htm and paymentgateway/views/mail/layouts/paymentgateway.htm (identical to ../sm-user-plugin, ../sm-paymentgateway-plugin)
|
||||
found: both are bare: `<style>{{ .brandCss }}{{ .css }}</style>` + `<div class="layout-user">{{ .Content }}</div>` / `<div class="layout-paymentgateway">`. No wrapper/inner-body tables, no header/logo, no footer. Classes layout-user / layout-paymentgateway have no CSS rule anywhere. user.htm text wrap is `-- {{ .Content }} --`.
|
||||
implication: plugin layouts only get the brand CSS element rules (body bg #f5f8fa, p/a/h colours) — content sits flush on the grey page background with no white card, header or footer: "unstyled"
|
||||
|
||||
- timestamp: 2026-11-13T15:36Z
|
||||
checked: user activate.htm / activate-en.htm / restore / invite templates
|
||||
found: CTA is plain Markdown link `[Aktywuj konto]({{ .Link }})`; no `{{ partial "button" ... }}` call. layout = "user".
|
||||
implication: goldmark renders a plain <a>; brand CSS styles <a> only with link colour; nothing makes it a button
|
||||
|
||||
- timestamp: 2026-11-13T15:40Z
|
||||
checked: admin/src/components/form/fields/MailPreviewField.vue + modules/boardwalk/boardwalk.go SetSecurityHeaders
|
||||
found: preview iframe is `sandbox=""` + srcdoc. Admin CSP = "frame-ancestors 'none'; base-uri 'none'; object-src 'none'; script-src 'self'; form-action 'self'; frame-src 'none'" — no default-src/img-src/style-src. No COEP header anywhere; uploads send no CORP.
|
||||
implication: sandbox/CSP do not block <img> or inline <style> in the srcdoc preview
|
||||
|
||||
- timestamp: 2026-11-13T15:42Z
|
||||
checked: demo DB (docker sm-demo-pg) system_mail_brand_settings, system_files id 556; curl of the computed logo URL
|
||||
found: brand row 1 saved (button_primary_bg #2974d6, logo_file_id 556 -> 72368e60b987f6aab7c025.png, is_public t). URL from attach.AbsolutePublicURL(app.url + storage.uploads.public_path_prefix + partition key) = http://127.0.0.1:8097/storage/app/uploads/public/723/68e/60b/72368e60b987f6aab7c025.png -> HTTP 200 image/png. go.log has no "mail branding logo" warning.
|
||||
implication: logo URL resolution works; Brand.LogoURL is populated for preview and send
|
||||
|
||||
- timestamp: 2026-11-13T15:45Z
|
||||
checked: scratch repro (scratchpad/mailrepro) — postcard.NewCatalog + Register(sm-user-plugin views) + NewMailer with an OverrideSource returning Brand{LogoURL: <above>, ButtonPrimaryBg #2974d6}; send golem15.user::mail.activate in file layout (user), system, default, minimal
|
||||
found: for all four layouts the HTML contains the compiled brand CSS (#2974d6 present) but 0 occurrences of the logo URL and 0 `class="button`. user layout body = `<div class="layout-user"><p>Cześć <strong>Jan</strong>.</p><p><a href="...">Aktywuj konto</a></p><p>Kod: 123456</p></div>`. system layout = Winter wrapper/inner-body card + subcopy, no header/logo, no footer.
|
||||
implication: reproduces all three symptoms deterministically outside the SPA (Bohrbug); preview path is not at fault
|
||||
|
||||
- timestamp: 2026-11-13T15:47Z
|
||||
checked: same repro with body `{{ partial "button" "url" .Link "body" "Aktywuj konto" }}` in the user layout
|
||||
found: renders `<table class="action">...<a href="..." class="button button-primary" target="_blank">Aktywuj konto</a>` and brand CSS has .button/.button-primary rules with the brand colour
|
||||
implication: button support exists and is styled; the CTA is a plain link only because the plugin templates don't call the partial
|
||||
|
||||
- timestamp: 2026-11-13T15:50Z
|
||||
checked: git show v0.6.4:modules/postcard/{partials.go,templates.go}; sm-user-plugin/go.mod, sm-paymentgateway-plugin/go.mod
|
||||
found: partials.go absent in v0.6.4; v0.6.4 execHTML parses with no FuncMap (no `partial`). Both plugins `require git.golem15.com/golem15/summercms v0.6.0`.
|
||||
implication: plugin templates can only adopt `{{ partial "button" }}` together with a require bump to the first tag containing phase 35; on <= v0.6.4 the call fails to parse at send ("function \"partial\" not defined")
|
||||
|
||||
- timestamp: 2026-11-13T15:52Z
|
||||
checked: .planning/phases/35-.../35-01-PLAN.md
|
||||
found: Task "Assets: port Winter's system layout and the four partials ... default.htm is not touched" with a gate `git diff a024280 --stat -- modules/postcard/assets/default.htm prints nothing`. Task 5 logo test uses "a layout using {{ .logoUrl }}" (test-only override, brand_smoke_test.go:220,329). Task 5 <done> claims "Saving Branding restyles every mail and shows the logo". Plugin layouts never in any phase-35 plan's files list.
|
||||
implication: the phase delivered the logo slot and partials as plumbing; no shipped layout or plugin template was updated to consume them, and verification checked the plumbing via test overrides, not out-of-box output
|
||||
|
||||
- timestamp: 2026-11-13T15:54Z
|
||||
checked: WinterCMS reference examples/golem15-wintercms-starter/modules/system/views/mail + classes/MailManager.php + plugins/golem15/user/views/mail/activate.htm
|
||||
found: Winter ships layout-default (wrapper + {% partial 'header' %} with subject + inner-body card + {% partial 'footer' %} "(c) year appName") and layout-system, partials header/footer/button/panel/promotion/subcopy/table. Winter user activate.htm uses `{% partial 'button' url=link type='positive' body %}Confirm account{% endpartial %}` and no plugin layout (default). MailManager::renderTemplate inlines CSS with TijsVerkoyen CssToInlineStyles (layout option disable_auto_inline_css). Winter brand settings have no logo.
|
||||
implication: postcard ported system layout and 4 partials but not Winter's default layout or header/footer partials; Go user templates dropped Winter's button partial; postcard never inlines CSS (only a <style> block) — fine for the browser preview, a parity gap for real mail clients
|
||||
|
||||
- timestamp: 2026-11-13T15:56Z
|
||||
checked: git history of plugin layouts; other plugins' mail
|
||||
found: sm-user-plugin layouts/user.htm from 63d6d04 (phase 07-03), paymentgateway layout from dee26dd (phase 18-04) — stubs predating Branding/partials. user.htm text wrap is `-- {{ .Content }} --`. 54 paymentgateway templates use layout paymentgateway with `[Zobacz zamówienie]({{ .orderUrl }}): {{ .orderUrl }}`. sm-mfa-plugin and sm-quizzes-plugin templates have no layout -> postcard default (bare div). KindBrand preview (Branding page) also renders in the default layout.
|
||||
implication: every out-of-box path except an explicit system-layout choice lands in a bare wrapper
|
||||
|
||||
- timestamp: 2026-11-13T15:58Z
|
||||
checked: demo DB system_mail_layouts / system_mail_templates
|
||||
found: golem15.user::mail.layouts.user is_custom=t (overridden during UAT test 5, no logoUrl); golem15.user::mail.activate is_custom=t (layout user). Other layouts not customized.
|
||||
implication: when verifying a fix on sm-demo-app, these two overrides must be reset or the new file versions won't show (drift notice instead)
|
||||
|
||||
## Resolution
|
||||
|
||||
root_cause: |
|
||||
(1) Logo: no shipped layout prints {{ .logoUrl }}. The variable is wired end to end (store.go builds an absolute URL that serves 200; mailer.options/Editor.render set opts.logoURL; renderParts passes "logoUrl" to both wrappers), but postcard's default/system/minimal and the plugin layouts user/paymentgateway never use it, there is no header partial, and brand.css.tmpl has no logo rule. Plan 35-01 tested the logo only through test-only layout overrides and pinned default.htm as untouched. The sandbox, CSP and URL resolution were ruled out.
|
||||
(2) CTA not a button: sm-user-plugin activate/restore/invite (+ -en) use the Markdown link [Aktywuj konto]({{ .Link }}), and the 54 paymentgateway templates use [Zobacz zamówienie]({{ .orderUrl }}): {{ .orderUrl }}. The Go port dropped Winter's {% partial 'button' %}. postcard's built-in button partial works and is styled with the brand colours, but no plugin calls it, and plugins can't until they require a framework tag with phase 35 (they require v0.6.0, and v0.6.4 has no partial func).
|
||||
(3) Unstyled plugin/default layouts: user.htm and paymentgateway.htm are stubs from phases 07-03 and 18-04 (<div class="layout-*">{{ .Content }}</div>). Neither class has a CSS rule, and neither layout has a wrapper, inner-body card, header or footer. The brand CSS only styles elements and Winter's wrapper classes, so the content sits flush on the grey body background. postcard's default.htm (used by mfa, quizzes and the Branding preview) is just as bare (<div class="content-body">), because only Winter's system layout was ported, not Winter's default layout with its header/footer partials. System looks "kind of proper" because it alone carries the Winter card structure, though it has no header/logo/footer and its content cell has zero horizontal padding.
|
||||
(4) Contributing, real sends only: postcard places the CSS in a <style> block and never inlines it (Winter runs CssToInlineStyles). The browser preview is fine, but mail clients that ignore or strip head styles will show unstyled mail even after the layouts are fixed.
|
||||
fix: (diagnose-only; see missing items in return)
|
||||
verification:
|
||||
files_changed: []
|
||||
Reference in New Issue
Block a user