Files

Jakub Zych 1eaa5f5d16 docs(04): capture phase context

Phase 04: Theme Engine
- Template syntax decisions (Twig-style, string templates)
- Layout composition (WinterCMS-style placeholders)
- Asset pipeline requirements (hot reload, bundling)
- Rendering modes (SPA, hybrid, static)

2026-02-04 15:54:14 +01:00

2.7 KiB

Raw Blame History

Phase 4: Theme Engine - Context

Gathered: 2026-02-04 Status: Ready for planning

## Phase Boundary

Render themes with layouts, partials, and Vue integration. Includes asset management and multiple rendering modes (SPA, hybrid, static). Theme creation tooling and CLI scaffolding are separate phases.

## Implementation Decisions

Template Syntax

String templates with interpolation (not ScalaTags) — designers can work with HTML directly
Twig-style syntax for includes: {% partial 'header' %}
Variable passing supports both named parameters and context objects:
- Simple: {% partial 'card' title='Hello' count=5 %}
- Complex: {% partial 'card' with cardData %}
Components expose variables implicitly — templates can use component data directly (WinterCMS style)

Layout Composition

Pages declare layout in front matter YAML: layout: default
WinterCMS-style placeholder system:
- {% page %} injects main page content
- Named placeholders supported: {% placeholder 'sidebar' %}
Flat layout structure only — no layout inheritance
- Use partials for shared pieces across layouts
Theme metadata in theme.yaml at theme root

Asset Pipeline

Research best Scala ecosystem options for manifest/bundling
- Manifest file preferred if no better standard tool exists
Hot reload essential for development workflow
Production optimization requirements:
- Minification with content hashing for cache busting
- Separate bundles: vendor, app, critical CSS
Plugin asset injection like WinterCMS:
- addCss() and addJs() for global hooks
- Component-scoped assets load when components are used
- Both mechanisms supported

Rendering Modes

Theme default in theme.yaml, per-page override in front matter
Three modes: spa, hybrid, static
SPA mode: Server renders HTML, Vue 3 hydrates on client
Hybrid mode: Page-level granularity (whole page is either server or SPA)
Static mode supports both:
- Build-time generation via CLI command
- On-demand generation with caching

Claude's Discretion

Specific string template library/implementation for Scala
Asset bundling tool selection (investigate Scala ecosystem)
Hot reload implementation approach
Exact Vue hydration setup
Cache invalidation strategy for static mode

## Specific Ideas

Template syntax should feel familiar to WinterCMS developers — Twig-style tags
Asset injection API similar to WinterCMS addCss() and addJs() functions
Hot reload is essential — CSS/JS changes must reflect immediately in dev mode

## Deferred Ideas

None — discussion stayed within phase scope

Phase: 04-theme-engine Context gathered: 2026-02-04

2.7 KiB Raw Blame History