themes-coffee/BUILD_REPORT.md

# Coffee — Build Report (v0.1.0 pass)

## What landed

### Plugin shell
- `plugin.mod` — `name=coffee`, `kind=theme`, `scope=@themes`, `version=0.1.0`,
  `categories=["templates"]`, `tags=["warm","hospitality","cafe","bakery","food","handcraft","organic","artisan","menu"]`,
  `[compatibility].block_core = ">=0.11.0 <0.12.0"`.
- `go.mod` — module `git.dev.alexdunmow.com/block/themes/coffee`,
  `go 1.26.4`, pinned `block/core v0.11.1`, no `replace` directives.
- `Makefile` — local-only `make` (CGO `go build -buildmode=plugin`),
  `make clean`, `make templ`, plus the full container-deploy targets copied
  from gotham (rebuild / backend / build-so / sync-migrations / etc.).
- `embed.go` — embeds `assets/*`, `schemas/*`, `presets.json`, `fonts.json`,
  `plugin.mod`. Exposes `Assets`, `Schemas`, `AssetsHandler`, `ThemePresets`,
  `BundledFonts`, `ThemeCSSManifest`.
- `registration.go` — `var Registration plugin.PluginRegistration` with
  `CSSManifest` wired (theme needs paper texture, torn-edge, kraft-tag CSS
  injected into the host Tailwind input).
- `register.go` — entry point. Order: system template → 4 page templates →
  `br.LoadSchemasFromFS` → 6 theme block registrations → 4 built-in
  overrides → email wrapper.
- `master_pages.go` — `DefaultMasterPages()` returns `coffee:default-master`
  and `coffee:landing-master` per spec §7.
- `helpers.go` — content-map readers (`getString`, `getBool`, `getSlice`)
  and weekday helpers (`shortDayName`, `normaliseDay`) for the
  server-side today-row detection in `hours_strip`.

### System + page templates
- System template `coffee` registered exactly once.
- Page templates: `default` (header/main/footer), `landing`
  (hero/menu/story/cta/footer), `article` (header/main/footer),
  `full-width` (header/main/footer) — `templ` components in
  `template.templ`, each rendered via `Render*` adapter wrapped with `wrap()`.

### Theme blocks (Source: `coffee`)
| Key | File pair | Schema | Notes |
|---|---|---|---|
| `menu_board` | `menu_board.{go,templ}` | `menu_board.schema.json` | Sectioned kraft-paper card; collection of items with price, note, allergens. |
| `hours_strip` | `hours_strip.{go,templ}` | `hours_strip.schema.json` | Today row flagged server-side via `time.Now().Weekday()` → `is-today today` classes. |
| `location_card` | `location_card.{go,templ}` | `location_card.schema.json` | Doodled SVG pin overlay; falls back to placeholder when map image absent. |
| `featured_pour` | `featured_pour.{go,templ}` | `featured_pour.schema.json` | Hero card with "Featured" badge, rich-text tasting notes, mono price. |
| `footer` | `footer.{go,templ}` | `footer.schema.json` | Torn-edge top border via `.coffee-torn-top` mask; newsletter caption. |
| `doodle_divider` | `doodle_divider.{go,templ}` | `doodle_divider.schema.json` | Inline SVG; four motifs (beans/croissant/cup/leaf), each visibly distinct. |

All 6 schemas use draft-07 and an allowed `x-editor` from
`{text, richtext, media, color, select, number, slug, textarea, array, collection, bucket-picker, menu-select, template-select, link}`.
Schema property names match each block's `content["..."]` reads.

### Built-in block overrides (active only when Coffee is the system template)
| Built-in | Coffee replacement | Aesthetic |
|---|---|---|
| `heading` | `CoffeeHeadingBlock` (`heading_override.{go,templ}`) | Fraunces display via `var(--font-heading)`, doodle underline on h2/h3. |
| `text` | `CoffeeTextBlock` (`text_override.{go,templ}`) | `.coffee-dropcap` first-letter floats large in `--primary`. |
| `button` | `CoffeeButtonBlock` (`button_override.{go,templ}`) | `.kraft-tag` class with `rotate(-1.2deg)` on hover, `:focus-visible` ring at 2px. |
| `image` | `CoffeeImageBlock` (`image_override.{go,templ}`) | Torn-edge bottom frame, handwritten italic caption. |

### Email wrapper
- `coffee/email_wrapper.templ` renders a single-column 560px-wide table
  layout, cream `Background`, espresso `Foreground`, inline-SVG doodle
  divider beneath the body. Hex fallbacks live in `coffeeBgColor` etc.;
  the resolved `EmailContext.Colors` overrides them per email.
- Registered via `tr.RegisterEmailWrapper("coffee", CoffeeEmailWrapper)`.

### Presets (`presets.json`)
Three presets, all 19 tokens populated for both `lightColors` and `darkColors`:
- `morning-pour` (mode: light) — cream paper, espresso ink, terracotta accent.
- `dark-roast` (mode: dark) — espresso base, copper primary, terracotta accent.
- `kraft-cream` (mode: light) — warmer ivory paper, deeper terracotta.

All colour values are HSL triple strings (no `hsl()` wrapper). Token values
copied from spec §4 verbatim where given. Two derived values were tuned
for accessibility (noted under "Open items").

### CSS Manifest
`assets/style.css` is injected into the host Tailwind input via
`CSSManifest.InputCSSAppend`. Provides:
- `--coffee-{heading,body,mono}-fallback` font stacks consumed via
  `var(--font-heading, var(--coffee-heading-fallback))` etc.
- `.coffee-paper` body background (inline SVG noise, palette-neutral).
- `.coffee-display`, `.coffee-body`, `.coffee-mono` font-family hooks.
- `.coffee-doodle-underline` SVG underline applied to h2/h3.
- `.coffee-dropcap` for article drop-cap and text override.
- `.kraft-tag` button styling with `:hover { transform: rotate(-1.2deg); }`
  and `:focus-visible` outline.
- `.coffee-torn-top` and `.coffee-torn-bottom` `mask-image` SVG paths.
- `.coffee-card`, `.coffee-frame`, `.coffee-pencil-rule` surfaces.
- `.coffee-hours-today` today-row highlight (border-left accent).
- `.coffee-price` mono numerals.

### Fonts policy (per `docs/FONTS.md` wave-1)
- `fonts.json` is literal `[]`.
- No woff2 bundled in this pass.
- All `font-family` usage goes through the CSS variables.
- `RECOMMENDED_FONTS.md` documents Fraunces / Inter / JetBrains Mono as
  Google Fonts picker recommendations.

## Build output

```
$ cd /home/alex/src/blockninja/themes/coffee
$ go mod tidy
(no output)

$ /home/alex/go/bin/templ generate
(✓) Complete [ updates=12 duration=8.143585ms ]

$ make
CGO_ENABLED=1 go build -buildmode=plugin -ldflags="-s -w" -o coffee.so .
$ ls -la coffee.so
-rw-rw-r-- 1 alex alex 21520096  ./coffee.so   (≈ 20.5 MiB)
```

Zero compiler warnings, zero `WARN` lines. The .so is in the same size
range as the gotham reference (`gotham.so` is 20.2 MiB).

## Safety check

The user-supplied invocation references `/home/alex/src/blockninja/backend`
which does not exist on this host. The two available check-safety
locations are:

1. Standalone module at `/home/alex/src/blockninja/check-safety` — the
   canonical clean run.
2. CMS backend worktree at
   `/home/alex/src/blockninja/cms/.worktrees/orchestrator-plugin-builds/backend/cmd/check-safety` —
   also reports coffee-specific checks as `OK` but has pre-existing
   failures in the CMS backend itself unrelated to this plugin
   (`templ.ResolveAttributeValue`, Tailwind v4 frontend lints).

Used invocation:

```
$ cd /home/alex/src/blockninja/check-safety
$ go run . /home/alex/src/blockninja/themes/coffee \
    --plugin-dir /home/alex/src/blockninja/themes/coffee
... 22 checks ...
=== Check 22: No hand-rolled HTML sanitization (use bluemonday) ===
  OK: No hand-rolled HTML sanitization detected
exit=0
```

All 22 checks PASS or SKIP. Notable:
- Check 2c (Standalone plugin SDK import boundaries) — `coffee` stays on
  the SDK boundary v0.11.1.
- Check 3 (Go lint pipeline) — clean for the single coffee module
  after dropping the unused `getInt` helper.
- Check 6 (No hardcoded colours in `.templ` / `.ninjatpl`) — passes; the
  hex fallbacks in `email_wrapper.templ` (`coffeeBgColor` and siblings)
  are the email-client compatibility fallbacks the check tolerates,
  matching the same pattern gotham ships.
- Check 21 (preset validation) — all three presets parse against the
  theme.Theme schema.

## Open items / deferred

1. **No bundled woff2s.** Per wave-1 `docs/FONTS.md`. `fonts.json` is `[]`,
   `RECOMMENDED_FONTS.md` documents the Google Fonts picks (Fraunces /
   Inter / JetBrains Mono). Wave-2 follow-up will bundle and add
   `LICENSES.md`.
2. **No bitmap paper-grain texture.** The `.coffee-paper` body background
   uses an inline SVG noise data URI. The UAT §13.1 expects
   `assets/textures/paper-grain.<ext>` at 8–80 KB. Deferred to a screenshot
   / marketplace pass that ships an actual PNG.
3. **`mutedForeground` accessibility tuning.** Spec §4 sets the
   `morning-pour` light `mutedForeground` at `25 20% 40%`, which fails
   the UAT §6 contrast gate against `muted` at 4.5:1. Bumped to
   `25 25% 32%` to clear AA. Same treatment applied to `kraft-cream`
   and `dark-roast` light fallbacks. The HSL family stays in the
   spec-described "soft brown over cream" range.
4. **Marketplace assets (UAT §12).** Screenshots, demo seed JSON, and
   launch-copy.txt are not produced in this pass.
5. **Live URL & container deploy (UAT §2 final, §5 final, §6 etc.).**
   `make rebuild` and the `instance-coffee` container are out of scope
   here; the build pass only runs `make` locally + safety.
6. **Email wrapper hex fallbacks.** `coffeeBgColor` and siblings carry
   hard-coded hex for the case where `EmailContext.Colors` arrives
   empty. This mirrors the gotham reference pattern; email clients
   cannot consume CSS variables, so the resolved palette is delivered
   per-email and the hex strings only ever land in the no-colour
   fallback path. Visual gate UAT §5 last bullet treats this as a
   deliberate exception.
7. **`EmailColors.Accent` does not exist.** The spec mentions a
   terracotta accent for the email body divider. The SDK's
   `templates.EmailColors` exposes Primary / Secondary / Background /
   Foreground / Muted / MutedForeground / Border / Card / CardForeground
   only — no `Accent`. `coffeeAccentColor` therefore reuses Primary
   when present, with a terracotta hex fallback.
8. **`hours_strip` "today" detection uses the server's local time zone.**
   Spec §15 flagged this as an open question; resolved here by using
   `time.Now()`. A future pass could thread a clock through context to
   make this testable without monkey-patching.
9. **`menu_board` allergen field is free-text.** Per spec §15. Structured
   allergen taxonomy deferred.

## File map

```
coffee/
├── BUILD_REPORT.md             ← this file
├── Makefile
├── RECOMMENDED_FONTS.md
├── assets/
│   ├── style.css               ← injected via CSSManifest
│   └── textures/
│       └── README.txt          ← placeholder; paper-grain inlined in CSS for v0.1.0
├── coffee.so                   ← 20.5 MiB build artefact
├── embed.go
├── plugin.mod
├── go.mod
├── go.sum
├── presets.json                ← morning-pour, dark-roast, kraft-cream
├── fonts.json                  ← [] (wave-1 policy)
├── registration.go             ← exports var Registration
├── register.go                 ← Register(tr, br) wires everything
├── master_pages.go             ← DefaultMasterPages()
├── helpers.go                  ← getString/getBool/getSlice + day helpers
├── template.templ              ← 4 page templates (Coffee, CoffeeLanding, CoffeeArticle, CoffeeFullWidth)
├── menu_board.{go,templ}
├── hours_strip.{go,templ}
├── location_card.{go,templ}
├── featured_pour.{go,templ}
├── footer.{go,templ}
├── doodle_divider.{go,templ}
├── heading_override.{go,templ}
├── text_override.{go,templ}
├── button_override.{go,templ}
├── image_override.{go,templ}
├── email_wrapper.templ
├── *_templ.go                  ← templ-generated companions (committed)
└── schemas/
    ├── menu_board.schema.json
    ├── hours_strip.schema.json
    ├── location_card.schema.json
    ├── featured_pour.schema.json
    ├── footer.schema.json
    └── doodle_divider.schema.json
```