Research spike: Rebuild Lumina theme as an Astro integration

[kirkone]

Goal

Build a minimal "Lumina-Astro" prototype to validate Revela's architectural choices against Astro on real data instead of hand-wavy comparisons.

The trigger: a developer asked "why didn't you just use Astro?" — a fair question that deserves a fact-based answer.

Scope

Rebuild just enough of Lumina in Astro to answer:

• How does Astro handle the "folder = gallery" convention? (Spoiler: it doesn't, out of the box.)
• How does astro:assets (Sharp) compare to NetVips for large photo libraries?
• How does the Astro Integration API compare to our IPlugin lifecycle?
• How does Content Collections + Zod compare to our manifest models?
• What does HMR via Vite feel like vs. our Serve plugin?

In scope

• Astro project with custom integration that scans a folder of galleries
• EXIF extraction (e.g. via exifr)
• Cover image resolution (mirror Revela's logic)
• Lumina CSS port (CSS is portable)
• One nested gallery level
• <picture> tag generation with srcset (AVIF/WebP/JPG)

Out of scope

• Calendar / Statistics / OneDrive plugins
• Production-quality polish
• Theme extension system
• GUI considerations

Timebox

3 weekends max. If incomplete after that, write up what was learned and stop. The goal is insight, not a finished product.

Decision: separate repo or branch?

Defer until we start. Probably a separate repo (e.g. Spectara/lumina-astro or personal) — keeps the comparison clean and avoids polluting Revela's git history.

Deliverables

• Working Astro prototype (link in this issue when done)
• Notes file capturing all four perspectives (not just the flattering ones):
  • what was easier in Astro
  • what was harder in Astro
  • what surprised me (positive or negative)
  • what would I miss if I switched Revela to Astro ← critical for Docs: "Why Revela" — honest comparison page (Astro / Hugo / Jekyll) #69, prevents the comparison page from accidentally becoming a "why Astro wins" list
• Concrete list of "things to steal for Revela" (e.g. Zod-style validation, integration hooks, HMR)
• Performance numbers: Sharp vs NetVips on a real photo set

Follow-up

Findings feed directly into #69 ("Why Revela" comparison page). Do not write that page before this spike is done — otherwise it would be hand-waving.

Priority

Low. This is research, not a feature. Pick up when there's a free weekend and curiosity strikes.

---

Context: discussion with Bertram, May 2026. See also the existing trust-model rationale in src/Features/Generate/Services/MarkdownService.cs for the kind of honest documentation this spike should produce.