Skip to content

PROJECT_STRATEGY.md

Latest commit

 

History

History
202 lines (137 loc) · 10.4 KB

PROJECT_STRATEGY.md

File metadata and controls

202 lines (137 loc) · 10.4 KB

Project Strategy

Purpose

This document captures the product and project strategy for Libration.

It explains what the project is trying to become, what it is not trying to become, and how future feature work should be judged.

Product thesis

Libration is a precision world time instrument evolving into a scientifically grounded planetary scene instrument, not merely a decorative map.

Its differentiating ideas are:

  • longitude-first structure.
  • continuous global time visualization.
  • canonical UTC instant per frame.
  • reference-frame civil presentation.
  • renderer-agnostic architecture.
  • composable projection-space scene.
  • planetary illumination and composition.
  • local-first desktop use.
  • public, inspectable, user-freedom-preserving implementation.

Product positioning

Libration should feel like an instrument:

  • stable.
  • legible.
  • precise.
  • calm.
  • deliberate.
  • configurable without becoming chaotic.

The product may gain many scene layers and visual modes over time, but the core display must remain understandable.

Independence and differentiation

Libration is independently developed.

The project should retain general world-time-map utility while differentiating its implementation, architecture, visual language, and feature set.

Useful differentiation directions:

  • renderer-agnostic internals.
  • open AGPL reference implementation.
  • explicit SceneConfig and composable layers.
  • curated scientific and cartographic map families (incremental bundled-catalog onboarding for validated substrates—including shipped static topography equirect-world-topography-ne-v1, political equirect-world-political-v1, geology equirect-world-geology-v1, bathymetry equirect-world-bathymetry-etopo-v1, land cover equirect-world-landcover-modis-v1, climate normals equirect-world-climate-koppen-beck-v1, and population density equirect-world-population-gpw-v1—see PLAN.md Slice 3 and docs/ROADMAP.md Phase 8).
  • reference-frame time model.
  • modern top-band chrome visual language.
  • planetary illumination and atmospheric composition.
  • future data overlays and playback features.
  • local-first power-user workflows.

Avoid cloning the look or exact interaction patterns of existing commercial products.

Open source strategy

Libration is intended to be a serious public reference implementation.

The AGPL license supports:

  • user inspection.
  • modification.
  • sharing.
  • downstream freedom.
  • network-use reciprocity.

The project should keep docs, rules, and architecture clear enough that future contributors and future AI sessions can work safely.

Product design principles

1. Time clarity over cleverness

The product must never confuse the canonical instant, the selected reference frame, and the visual presentation mode.

2. Spatial truth is projection truth

Maps are visual substrates. Projection math and geographic coordinates define placement.

3. Instrument first, layer platform second

Layer richness matters, but it must not undermine the core time instrument.

4. Curated, not random

Map families and overlays should be selected, sourced, validated, and named intentionally.

5. Configurable without mode chaos

Expose powerful controls through coherent axes:

  • time and reference frame.
  • chrome display.
  • scene and map selection.
  • layer composition.
  • presets when implemented.

6. Future backends must remain possible

Canvas is the current backend. The architecture should keep a future GPU or bare-metal renderer plausible.

7. Scientific grounding over arbitrary effects

Atmospheric transitions, twilight behavior, planetary illumination, moonlight, and emissive city-light composition should emerge from:

  • real solar geometry.
  • lunar geometry.
  • physically-inspired attenuation.
  • coherent upstream composition policy.

Further refinement (readability extensions after shipped v1 + v1.1 + derived substrate lift + substrate heuristic increments (catalog reliefShaded / boundaryDense / chromaticDense / bathymetryShaded / fineScaleTexture / labelDense / etchedReliefDense / sunGlintDense, sub-1 brightness dimming) + presentation scalars + six default-stack perLayer pilots, clouds/weather, scattering) extends this upstream model rather than replacing it with backend-owned effects.

Avoid:

  • arbitrary glow effects.
  • backend-specific visual tricks.
  • disconnected visual layers.
  • composition logic implemented inside backend execution.

8. Planetary composition over isolated overlays

The scene system includes a coherent upstream planetary illumination composition path (solar, twilight, moonlight, optional emissive night lights → one rasterPatch), not merely a pile of unrelated overlays.

Future work extends that subsystem for readability policy beyond the shipped global presentation + six default perLayer keys + substrate heuristic increments (reliefShaded, boundaryDense, chromaticDense, bathymetryShaded, fineScaleTexture, labelDense, etchedReliefDense, sunGlintDense, presentation dimming in lift), atmosphere, and (when lifecycle exists) weather and clouds. Systems should participate coherently in:

  • atmospheric attenuation.
  • reflected illumination.
  • emissive illumination.
  • visibility/readability policy.
  • weather/cloud implementation (planning shipped in docs/specs/scene/weather-cloud-composition-plan.md; Phase 10 lifecycle prerequisite).
  • dynamic scene composition.

Development strategy

The project should evolve through phase-scoped slices.

A good phase:

  • has a clear objective.
  • updates one architectural area at a time.
  • has exit criteria.
  • adds or updates tests.
  • updates docs.
  • leaves the codebase cleaner than it found it.

A bad phase:

  • mixes unrelated UI, runtime, config, and docs changes.
  • moves product semantics into the backend.
  • adds duplicate config surfaces.
  • silently changes persisted semantics.
  • implements future capability by hardcoding special cases.

Current strategic position

The project has passed the initial foundation threshold.

Foundational systems now exist:

  • RenderPlan pipeline.
  • Canvas backend boundary.
  • structured chrome.
  • SceneConfig.
  • curated map catalog.
  • map onboarding.
  • static and derived overlays.
  • month-aware map families.
  • coherent upstream planetary illumination composition (twilight—including shipped cumulative incremental transition tuning in illuminationShading.ts—moonlight, emissive night lights; single illumination rasterPatch).
  • composition-aware overlay readability (v1 + v1.1 + derived substrate lift + substrate heuristic increments (reliefShaded / boundaryDense / chromaticDense / bathymetryShaded / fineScaleTexture / labelDense / etchedReliefDense / sunGlintDense, sub-1 effective brightness dimming in lift) + SceneConfig presentation scalars + default-stack perLayer pilots (grid, solarAnalemma, subsolarMarker, sublunarMarker, cityPins, staticEquirectOverlay): night veil + emissive policy + presentation/catalog lift + user veil/lift multipliers on selected overlays; optional second veil/lift pass per pilot layer via scene.overlayReadability.perLayer; one OverlayReadabilityFrame per tick on TimeContext when the shell attaches it).

The next strategic need is not another large hidden architecture migration. The planetary composition baseline (eight-intrinsic substrate lift, third twilight pass, overlay readability closure) is complete for standing incremental work—Slice 2 queues B/C are closed as default PR tracks. Default engineering pull is sourced map inventory (Phase 8 / queue A) or other explicitly scoped work. Composition extensions (perLayer beyond six defaults, ninth+ intrinsics, fourth+ twilight, deeper scattering, cloud/weather implementation after Phase 10) reopen only with explicit product scope—not agent-invented filler PRs.

Default sequencing for planning/discovery sessions: when no explicit human override is given, use PLAN.md → “Agent session handoff (planning prompts)”—do not default to Slice 2 B/C.

Strategic next frontiers

Likely next frontiers:

  1. Documentation, rules, and co-engineering reliability (Phase 7 rolling hygiene; keep shipped vs future language aligned—for example the eight-intrinsic substrate overlay-lift contract through sunGlintDense is shipped and doc-finalized, not hypothetical; cumulative twilight tuning through second and third narrow illuminationShading.ts passes is doc-finalized; geology equirect-world-geology-v1, climate normals equirect-world-climate-koppen-beck-v1, population density equirect-world-population-gpw-v1, and structured map selector attribution are doc-finalized).
  2. Map inventory and explicit-scope work (default macro PR track: Phase 8 / queue A when sourced substrate or scoped polish exists; composition baseline closed—queues B/C not standing defaults). Readability/composition extensions (perLayer beyond six defaults, ninth+ intrinsics, fourth+ twilight, deeper atmosphere) and cloud/weather implementation (after Phase 10 per docs/specs/scene/weather-cloud-composition-plan.md; planning closed) reopen only with explicit product scope.
  3. Map inventory (re-opens queue A when a sourced static substrate or explicitly scoped catalog polish is available—queue (2) land cover, bathymetry, and climate normals shipped; structured attribution and month-aware selector polish shipped).
  4. Further scientific substrate onboarding (emissive-compatible substrates, alternate climate/terrain products) beyond shipped static families (topography, political, geology, bathymetry, land cover, Köppen–Geiger climate).
  5. Dynamic data lifecycle.
  6. Advanced scene view and projection work.
  7. Preset system.
  8. GPU backend exploration.

Decision filter for new features

Before implementing a feature, answer:

  1. Does it strengthen the core world time instrument?
  2. Does it belong in chrome, scene, config, lifecycle, or backend?
  3. Does it preserve RenderPlan separation?
  4. Does it preserve projection correctness?
  5. Does it need durable config, or is it derived?
  6. Does it need docs and tests now?
  7. Is it phase-sized?

If the answer is unclear, write a planning doc or implementation intent before editing.