intotheeast-com/docs/working/milestone2-template-refactor-brief.md

# Milestone 2: Template Refactor — Session Brief

Use this as the starting point for the brainstorm in a new session.
Invoke the brainstorming skill (`/brainstorm`) and hand it this file as context.

---

## What this milestone is about

The asset pipeline (Milestone 1) is done — CDN dependencies eliminated, JS deduplicated into shared bundles. The templates themselves still have structural problems that make them hard to maintain and extend.

## Problems to solve

### 1. `trip.html.twig` mixes three concerns

Currently ~384 lines after Milestone 1 cleanup. Still mixes:
- Twig data-building loops (collecting `map_entries`, building entry lists, GPX URL arrays)
- HTML structure (cards, panels, filter bar)
- Inline JS (map init, GPX stats block)

Goal: split into focused, readable sections or partials.

### 2. `map_entries` loop is duplicated across 4 templates

Near-identical Twig loop that builds `[{lat, lng, title, slug, url, type, ...}]` appears in:
- `trip.html.twig`
- `dailies.html.twig`
- `stories.html.twig`
- `map.html.twig`

Candidate for a Twig macro so a change only needs to happen once.

### 3. Stats computation is slow Twig loops

Country counting, temperature range, days on road — currently computed in Twig on every uncached page load. At 60–80 entries this is noticeable.

**Stronger option:** Move to a small PHP Grav plugin that exposes a single `{{ trip_stats }}` Twig variable. PHP loops are significantly faster than Twig loops. This is also the prerequisite for showing stats on other pages (homepage, story pages) in future.

### 4. Date range formatting duplicated

Same date formatting logic in both `story.html.twig` and `stories.html.twig`.

### 5. Latent bugs on inactive pages (fix while touching templates)

While refactoring, fix these two issues on pages not yet in active use:
- `map.html.twig`: inline map init needs `DOMContentLoaded` wrapper; `{% block map_assets %}` nested inside `{% block content %}` (double-registers assets)
- `feed-map.html.twig` (partial): `{% do assets.addCss %}` registers after `{{ assets.css()|raw }}` has rendered; inline map init also needs `DOMContentLoaded`

---

## Key constraint

Mischa wants stats and cycling data (distance, elevation gain/loss, moving time) visible on other pages in future (homepage, story pages). Centralising the computation — whether as Twig macros or a PHP plugin — is the prerequisite for that.

## What NOT to do in this milestone

- Don't touch JS or asset pipeline (that's Milestone 1, done)
- Don't redesign the visual layout
- Don't activate `dailies.html.twig`, `stories.html.twig`, or `map.html.twig` as new features — just fix their structural bugs while you're in the templates

## Relevant files

- `user/themes/intotheeast/templates/trip.html.twig` — main template (~384 lines)
- `user/themes/intotheeast/templates/partials/base.html.twig` — base layout
- `user/themes/intotheeast/templates/partials/feed-map.html.twig` — mini-map partial
- `user/themes/intotheeast/templates/map.html.twig` — full-page map (inactive)
- `user/themes/intotheeast/templates/dailies.html.twig` — journal feed (inactive)
- `user/themes/intotheeast/templates/stories.html.twig` — stories grid (inactive)
- `user/themes/intotheeast/templates/story.html.twig` — single story page
- `user/plugins/` — where a new stats plugin would live

## Open question for the brainstorm

The biggest design decision: **PHP plugin vs Twig macro for stats computation.**

- Twig macro: simpler, no new plugin, but still slow Twig loops
- PHP plugin: faster, reusable across pages, but adds a plugin to maintain

Mischa's stated preference leans toward the PHP plugin given the future-reuse goal, but hasn't committed yet.