# Phase 4: Theme Engine - Context

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

<domain>
## 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.

</domain>

<decisions>
## 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

</decisions>

<specifics>
## 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

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

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