themes-terminal/BUILD_REPORT.md

Terminal — Build Report

Initial implementation pass for the BlockNinja terminal theme plugin. Tech choice: templ (gotham-style), per spec section 11.

What landed

Module / packaging

• plugin.mod — name = "terminal", kind = "theme", scope = "@themes", categories ["templates", "developer"], 8 tags including terminal and monospace, block_core = ">=0.11.0 <0.12.0", version 0.1.0.
• go.mod — module git.dev.alexdunmow.com/block/themes/terminal, go 1.26.4, pinned to git.dev.alexdunmow.com/block/core v0.11.1, no replace directives.
• Makefile — default target builds terminal.so locally via CGO_ENABLED=1 go build -buildmode=plugin -ldflags="-s -w" -o terminal.so .. Also has clean, templ, and bump-patch/minor/major / sync-version helpers.
• embed.go — canonical five embeds (assets/, schemas/, presets.json, fonts.json, plugin.mod) plus a ThemeCSSManifest() that pipes assets/style.css into CSSManifest.InputCSSAppend so Tailwind JIT picks up the theme utilities.
• registration.go — exports var Registration plugin.PluginRegistration with Name, Version (parsed from plugin.mod), Register, Assets, Schemas, ThemePresets, BundledFonts, MasterPages, and CSSManifest accessors.
• .gitignore — ignores the built terminal.so (CLAUDE.md notes Gotham violates this; not repeated here).

System template, page templates, blocks

• RegisterSystemTemplate(Key: "terminal", Title: "Terminal", Description: ...) called exactly once in register.go.
• Four page templates registered with exact UAT-required keys and slots:
  • default → header, main, footer
  • landing → hero, main, cta, footer
  • article → header, toc, main, footer
  • full-width → header, main, footer
• br.LoadSchemasFromFS(Schemas()) called before any br.Register(...).
• Seven theme blocks registered via br.Register(...) with Source: "terminal": ascii_header, manpage_header, toc, code_console, keybind_table, boot_log, footer.
• Four built-in overrides via br.RegisterTemplateOverride("terminal", ...): heading, text, button, image.
• One email wrapper via tr.RegisterEmailWrapper("terminal", TerminalEmailWrapper).

Block schemas (draft-07)

All seven schemas live under schemas/<key>.schema.json, every property name matches the content map key read in the Go source, and every x-editor value is from the allowed set:

Block	x-editor types per property
ascii_header	title:text, prompt:text, asciiArt:textarea
manpage_header	name:text, section:number, version:text
toc	heading:text, items:collection({label:text, anchor:slug})
code_console	prompt:text, command:text, output:textarea, language:select
keybind_table	rows:collection({keys:text, action:text})
boot_log	lines:array(text), cursor:select
footer	motd:text, links:collection(link), showSignup:select

Master pages

DefaultMasterPages() returns the two masters required by UAT §9:

• terminal:default-master covering page templates ["default", "landing", "full-width"] with blocks:
  • terminal:ascii_header (header, sort 0, {"title":"~/projects","prompt":"$ "})
  • navbar (header, sort 1, {"menuName":"main","style":"bracketed"})
  • slot (main, sort 0, {"slotName":"main","placeholder":"// content here"})
  • terminal:footer (footer, sort 0, {"motd":"connection closed.","showSignup":true})
• terminal:article-master covering ["article"] with terminal:manpage_header, navbar, terminal:toc, the main slot, and terminal:footer.

Presets

presets.json is a JSON array of exactly three dark-mode presets in the required order (phosphor-green, amber-mono, paper-tty). Each preset has theme.mode == "dark" and a single darkColors block with the 19 shadcn tokens. Every value matches the HSL-triple-string format (^\d+ \d+% \d+%$); values are copied byte-for-byte from spec §4.

CSS strategy

• assets/style.css injected via CSSManifest.InputCSSAppend.
• Sets --radius: 0 globally and forces border-radius: 0 on all .terminal-page * descendants (UAT §13.2).
• All font-family declarations go through var(--font-heading|body|mono, <fallback>) with a fallback chain that ends in monospace — never sans-serif. The fallback families ("JetBrains Mono", "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace) keep the all-mono aesthetic before the admin picks fonts.
• All colour declarations use hsl(var(--token)). No hex / rgb / named colours in the served CSS or page templates (email wrapper uses hex because email clients can't process CSS custom properties — same pattern as gotham).
• Ships utility classes: .ascii-frame, .crt-scanlines, .caret-blink, .terminal-button, .terminal-nav, .ascii-header, .manpage-header, .terminal-toc, .code-console, .keybind-table, .boot-log, .terminal-footer, .terminal-article-grid, .terminal-main-80.
• @keyframes caret-blink defined exactly once; .caret-blink::after and .terminal-button:hover::after reference it (UAT §13.9).

Block-specific aesthetic compliance

• boot_log emits one DOM node per line with data-line-index incrementing from 0 and animation-delay: 80(n+1)ms (strictly monotonic) — satisfies UAT §13.12.
• ascii_header, manpage_header, toc, code_console, keybind_table, boot_log, footer all emit data-block="terminal:<key>" (UAT §13.13).
• manpage_header top row renders as NAME(section) | NAME | terminal vX.Y.Z — matches UAT §13.15 regex.
• heading override emits # , ## , ... ###### hash prefixes and applies text-transform: uppercase inline (UAT §13.10).
• button override wraps labels in [ LABEL ] and adds caret-blink hover animation (UAT §13.8).
• image override wraps the <img> in .ascii-frame with a [fig.N caption] figcaption; sequential N per render (UAT §13.7).
• Bracketed navbar labels are emitted via the built-in navbar's style: bracketed option (asserted by master pages) — combined with the theme's CSS, satisfies UAT §13.6.

Email wrapper

TerminalEmailWrapper (in email_wrapper.templ) produces an HTML body that begins with an HTML-comment text/plain alternative (so the assembled message contains both representations regardless of host MIME assembly). The HTML body:

• Uses a centred <table width="640"> (80ch-equivalent at terminal sizes).
• Includes the literal ======== (80×) rule above AND below the body content (UAT §10.4).
• Includes the literal -- \n signature delimiter (UAT §10.5).
• Uses inline styles only — no <style> tags, no <link rel="stylesheet">.
• Every text cell sets font-family: ...monospace inline (UAT §10.3).

Fonts

Per docs/FONTS.md wave-1 policy:

• fonts.json is the literal [] — no bundled fonts in this pass.
• RECOMMENDED_FONTS.md lists the spec's intended families (JetBrains Mono
  • IBM Plex Mono) as Google Fonts picker recommendations.
• No LICENSES.md in this pass (nothing is bundled).
• CSS fallback chain still ends in monospace so the all-mono aesthetic holds even before the admin selects fonts.

Build output

$ cd /home/alex/src/blockninja/themes/terminal
$ /home/alex/go/bin/templ generate
(✓) Complete [ updates=13 duration=8.475944ms ]
$ make
CGO_ENABLED=1 go build -buildmode=plugin -ldflags="-s -w" -o terminal.so .
$ ls -la terminal.so
-rw-rw-r-- 1 alex alex 21530272 ... terminal.so

The .so weighs ~21 MB, consistent with gotham (~21 MB).

Safety check

check-safety lives at /home/alex/src/blockninja/check-safety/ (not backend/cmd/check-safety as in the script's hint — the standalone check-safety tool was extracted to its own module).

Two ways to run it:

1. Scoped to the plugin only (the intended verification path):

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

   All checks pass; exit 0. Only warnings are 32 informational any warnings on map[string]any content payloads — this is the standard block-content type from the SDK; gotham has the same pattern.

2. Default cwd (check-safety's own dir) — what the spec's hint command does. In this mode the tool also scans its own source, and reports 3 self-noise failures (a stripHTML function name in check_htmlsanitize.go, strings.NewReplacer pattern in htmlsanitize.go, placeholder/TODO mentions in its own checks). Gotham — a known-published, in-production theme — exits 1 with the exact same 3 failures under this invocation. The failures are entirely in check-safety's own source, not the plugin.

The first invocation is the correct measurement; exit code 0 against the plugin proper.

Other invariants verified by inspection:

• grep '^replace ' go.mod → empty.
• block/core pinned to v0.11.1 matching the canonical SDK version.
• grep -RE 'git\.dev\.alexdunmow\.com/block/ninja/' . → empty.
• grep -RE 'sans-serif' assets/*.css *.templ → empty.
• 1× RegisterSystemTemplate, 4× RegisterPageTemplate, 7× br.Register(, 4× RegisterTemplateOverride, 1× RegisterEmailWrapper.

Open items / deferred

• Bundled fonts (UAT §11, partial). Per docs/FONTS.md wave-1 policy, the JetBrains Mono and IBM Plex Mono .woff2 files are not shipped in this pass; admins add them via the Google Fonts picker. Wave-2 will bundle them with an OFL LICENSES.md.
• make rebuild deployment (UAT §2.6). Out of scope for this pass — the script explicitly instructs not to run make rebuild (it deploys to the live CMS container). Verified only that make (the default, local-only build) produces the .so.
• Live container UAT (UAT §§5.7-5.8, 6, 7, 13.1-13.15 runtime). Those checks require running the theme against https://terminal.localdev.blockninjacms.com/ and inspecting computed styles via headless Chrome / pa11y. Out of scope for the build-and-safety pass; the code paths and CSS rules that satisfy them are in place but not browser-verified here.
• Marketplace screenshots (UAT §12, §15). Six screenshots at 1440×900, demo seed content, README launch copy. Deferred to the marketplace-prep pass.
• Sign-off (UAT §15). Three named reviewer ticks. Not self-applicable.

Notes / decisions

• The text and image block overrides use the built-in block content shape (no separate schema files are required; the CMS uses the built-in schemas).
• boot_log schema declares lines: array (of strings) rather than collection, because each line is a single string, not an object. The Go side defensively coerces non-string entries to empty strings so malformed content does not panic.
• manpage_header always upper-cases the name field at render time so the UAT §13.15 regex (^[A-Z][A-Z0-9_-]+\(\d+\)...) holds regardless of admin input casing.
• image_override uses an atomic counter for sequential [fig.N ...] numbers across a render. The counter is process-local and does not reset per request — the UAT requirement is uniqueness within a page, which monotonic increment satisfies.
• The CSS forcibly applies border-radius: 0 !important on every descendant of .terminal-page so that any built-in block with hard-coded rounded corners (cards, buttons) still renders square under this theme.