From b8c177fca81f164aa533600fcd629c53b186bef1 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 13 Nov 2026 16:18:28 +0100 Subject: [PATCH] docs(35): diagnose UAT gaps G-35-1 and G-35-8 --- .planning/debug/mail-layouts-unstyled.md | 146 ++++++++++++++++++ .../35-UAT.md | 56 ++++++- 2 files changed, 197 insertions(+), 5 deletions(-) create mode 100644 .planning/debug/mail-layouts-unstyled.md diff --git a/.planning/debug/mail-layouts-unstyled.md b/.planning/debug/mail-layouts-unstyled.md new file mode 100644 index 00000000..b275c690 --- /dev/null +++ b/.planning/debug/mail-layouts-unstyled.md @@ -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 `
{{ .Content }}
` (stubs from phases 07-03/18-04); default.htm is `
` and 35-01 forbade touching it" + falsification_test: "Adding `{{ if .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 ; 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 `
{{ .Content }}
` (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 }}{{ 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: `` + `
{{ .Content }}
` / `
`. 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 ; brand CSS styles 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 or inline