RFC-011 — Science page · render pipeline & content authoring
Orrery · Closed RFC · v0.1 · May 2026
Status: Closed (v0.5.0) Author: product Closed by: ADR-034 (KaTeX server-render), ADR-035 (hand-coded SVG diagram pipeline), ADR-036 (cross-screen
?-chip pattern) Slice gate: v0.5.0 (encyclopedia + explorers release) Why this is an RFC (historical context): PRD-008 locks the what (in-app encyclopedia, six tabs, ~40 sections, ?-chip cross-link from existing screens — actually shipped with 8 tabs and 54 sections in v0.5.0). It did not lock the how — math rendering, diagram authoring, and the cross-screen UX of the?chip each had multiple defensible answers with real trade-offs. Each open question below was resolved via ADR alongside the implementation.
Context
The simulator already references ~90 distinct scientific concepts across docs and code (full inventory in PRD-008 §appendix). The user-visible terminology surfaces today are:
/planporkchop axes + colour bar/flyHUD (∆v · MET · v∞ · velocity · distance)/missionsFLIGHT tab (C3 · v∞ · TLI · TMI · TCM · EDL · ∆v totals)/exploreplanet panels (Keplerian elements · semi-major axis · eccentricity · orbital period)/earthorbit-altitude regimes (LEO · MEO · GEO · L2)/moon(and the new/marsper PRD-009) — landing-site narratives that mention free-return, direct-ascent, gravity assist
Today every one of these terms is undefined in-app. The reader either knows the term or must leave the app to look it up. PRD-008 closes that gap with /science.
Three implementation questions are independent of content and worth resolving up front: math rendering, diagram authoring, and the cross-screen ?-chip wiring.
Open Questions
OQ-1 — How do we render math in section bodies?
The app references formulas like v = √(μ·(2/r − 1/a)) (vis-viva), Δv = Isp·g·ln(m₀/m_f) (Tsiolkovsky), r = a·(1 − e²)/(1 + e·cos ν) (Kepler conic). They must render cleanly in dark theme, scale on mobile, and not blow up the JS payload.
| Option | Bundle | Render path | Pros | Cons |
|---|---|---|---|---|
| A. KaTeX (server-rendered at build) | ~70 KB minified gzipped CSS, 0 KB JS at runtime (HTML output baked in at prerender) | Compile-time | Fast, no client lib, simple authoring (LaTeX source in JSON) | KaTeX rendering only at build; no client-side math edits possible (we don't need them anyway) |
| B. KaTeX (client-side) | ~70 KB JS + CSS | Runtime | Same renderer; trivial drop-in if we ever need dynamic math | Adds 70 KB to client bundle; payload regression for a feature ≤80% of users will reach |
| C. MathJax v3 | ~250 KB+ | Runtime | Most complete LaTeX support; handles edge cases KaTeX can't | 3.5× larger than KaTeX; we don't need the edge cases |
| D. Hand-rolled SVG per formula | ~0 (SVG inlined) | Compile-time | Bullet-proof; pixel-perfect | Authoring nightmare; one-off per formula; brittle when the formula changes |
Recommendation: A — KaTeX server-rendered at build. SvelteKit's prerender step compiles each section's formula_latex field into HTML once; the client never loads KaTeX. We get LaTeX authoring ergonomics without any runtime cost. Any edge case KaTeX can't handle becomes an inline SVG (option D) for that one formula.
OQ-2 — How do we author the diagrams?
PRD-008 commits to ≥ 1 visual element per section. Photos cover ~half (NASA / ESA / Wikimedia). The other half are diagrams — Hohmann transfer geometry, conic sections, porkchop colour-bar key, Keplerian elements illustration, free-return trajectory diagram, etc. ~30 needed for V1.
| Option | Authoring | Cost / diagram | Style consistency | Maintenance |
|---|---|---|---|---|
| A. Hand-drawn Inkscape SVG (committed source) | Open Inkscape, draw, export, commit .svg to static/diagrams/science/ | 30–60 min each | High (single author, single style) | High — every change is hand-edits |
| B. Hand-drawn Figma → SVG export | Figma file as source of truth; export per diagram | 20–40 min each | High | Figma file lives outside repo; harder to PR-review |
| C. Hand-coded SVG in JSON | Each section's JSON carries inline <svg> markup | 60+ min each | Variable | Best for tiny diagrams; awful for anything geometric |
| D. Generated via D3 / chart lib at build | TypeScript build step renders a programmatic SVG | 1–2 hr to author the spec | Highest (programmatic = perfectly consistent) | Best — code-review the spec, regenerate any time |
| E. AI-generated | Prompt → image → curate | 5 min each | Inconsistent; licensing unclear | Off the table per PA §principles ("attribution is design") |
Recommendation: A for V1. Inkscape SVG with the source .svg files committed to the repo. Cheapest to start; we can migrate any single diagram to D (programmatic) if it gets reused or needs to track data. Option E is rejected — we do not generate scientific diagrams via AI.
The build script scripts/validate-diagrams.ts will fail if any section declares a diagram field with no matching SVG file — same fail-fast contract as the existing data-validation pipeline (ADR-019).
OQ-3 — ?-chip UX on existing screens
Every HUD label that names a concept covered in /science gets a ? chip. The interaction model has three options:
| Option | Hover tooltip | Click action |
|---|---|---|
| A. Click → navigate to /science | None | Full page navigation to /science/[tab]/[section] |
| B. Hover tooltip + click → navigate | The section's intro sentence (≤ 80 chars) on desktop hover | Same as A |
| C. Click → mini-modal popover with the section abstract | None | Popover with intro + a "read more" button into /science |
Trade-off. A is the simplest contract and matches the existing LEARN tab pattern (links, no popovers). B adds desktop polish at zero mobile cost. C is "Wikipedia preview"-style but introduces a new component (the popover) and means every chip click on mobile becomes a context-loss modal — exactly what the PRD wants to avoid.
Recommendation: B. The hover tooltip is a desktop-only convenience that doesn't change the contract on mobile (where there's no hover). Click-navigates on both. The intro sentence is already in the JSON — surfacing it as a title attribute is one line of code.
OQ-4 — Should V1 ship a glossary view (alphabetical)?
PRD-008 V1 is tab-organised reading. A glossary is a flat alphabetical lookup ("show me Vis-viva regardless of which tab it's under"). Cmd-K covers the search use case; the glossary is for browsing.
| Option | UX | Cost |
|---|---|---|
| A. Tab-only (no glossary) | Six tabs, each section under one tab | 0 (already in PRD) |
| B. Tabs + alphabetical sidebar toggle | Switch between "by topic" and "A–Z" views | +2 days |
C. Tabs + a separate /science/all flat list | URL-addressable glossary mode | +1 day |
Recommendation: A for V1, defer C to V1.5. The Cmd-K search lands at the same destination as a glossary entry; we don't need both in V1. C is clean to add later as a static prerendered route.
OQ-5 — Translation cadence
40 sections × ≤ 200 words ≈ 8 000 source words per locale. With ADR-033's LLM-only first-pass workflow that's a half-day batch per locale.
Question: does each new locale ship /science simultaneously with the rest of its UI strings, or as a follow-up wave?
| Option | Risk |
|---|---|
| A. Atomic — a locale ships only when /science is also done in that locale | Slows down each locale's launch by ~half a day |
B. Decoupled — /science falls back to en-US per ADR-017 until the locale is ready | Faster launches; readers see English on /science even when the rest of the UI is in their language |
| C. Coupled to the LEARN tabs only — /science ships per locale alongside the mission editorial overlays | Mid-ground; ties /science to the same translation budget that already exists for missions |
Recommendation: B. ADR-017's fallback contract already handles partial-locale state without breaking. A new locale can launch fast; /science follows when the translator is ready.
OQ-6 — Section atomicity: one concept per URL, or one tab per URL?
| Option | URL examples | Pros |
|---|---|---|
| A. One section per URL | /science/orbits/vis-viva, /science/orbits/keplers-laws | Maximum deep-linkability; ?-chip lands precisely |
| B. One tab per URL with anchors | /science/orbits#vis-viva | Single page per tab → faster reading flow |
| C. Both (A is the canonical URL; tab-page redirects to first section) | /science/orbits/ redirects to /science/orbits/vis-viva | Flexibility |
Recommendation: A. The ?-chip's whole value is "land the user on the exact concept in one click." Anchors work but lose the "section is a unit" feeling. The tab page (/science/orbits/) becomes a section-list index — useful as a navigable menu, not a reading surface.
OQ-7 — Diagram licensing / attribution chain
Per PA §principles ("attribution is design"), every visual element must have a clear licence + credit. PRD-008 commits to "Public-domain or CC-BY only."
| Option | Diagram source rules |
|---|---|
| A. Strict — only NASA / ESA / Wikimedia public-domain, no third-party CC-BY | Smallest pool but zero attribution risk |
| B. CC-BY allowed with credit — any CC-BY licence with credit captured per asset | Wider pool; tracks attribution per file |
| C. Original SVGs only | Lock the visual style; everything attributable to the project |
Recommendation: B for photos, C for geometric diagrams. Photos: Wikimedia + NASA + CC-BY academic figures, attribution captured in the section's JSON. Geometric diagrams: original SVGs (per OQ-2 option A) so the visual style of the encyclopedia is the project's own.
Decision criteria
We accept a recommendation when:
- The bundle-size impact (KaTeX, diagrams, science content JSON) is auditable and < 200 KB initial-load delta.
- The cross-link UX (
?chip) does not regress mobile flow on existing screens. - The build-time validation guarantees every published section has the visual it declares.
- The translation pipeline composes cleanly with ADR-017 / ADR-033 — no new translator workflow.
- The decision is reversible at the per-section level (we can change one diagram or one formula without revisiting the whole framework).
Closure path
This RFC closes with three ADRs:
- ADR-034 — Math rendering: KaTeX server-rendered at build.
- ADR-035 — Diagram authoring pipeline: hand-drawn Inkscape SVG, sources committed to
static/diagrams/science/. - ADR-036 —
?-chip cross-screen pattern: click navigates, hover tooltip on desktop, no popover modal.
Glossary (OQ-4) deferred. Translation cadence (OQ-5) noted in RFC body, no ADR — the en-US fallback is the policy.
Orrery · RFC-011 · v0.1 · Open. Comments welcome on each OQ.