first commit

docs/geospatial/geo/solar-system/README.md

@@ -0,0 +1,19 @@
+# @suaveplan/solar-system - Solar-system provider with injectable astronomy engine and season/equinox/solstice/sunrise/sunset/lunar-phase calculations; emits CelestialBody records for the Sun, Moon, and inner/outer planets via a SolarProvider contract.
+
+## Summary
+
+Solar system provider with astronomy engine.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [provider](./src/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [provider](./src/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [seasons](./src/seasons/seasons.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [seasons](./src/seasons/seasons.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+<!-- end:auto-docs -->  - [provider](./src/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [seasons](./src/seasons/seasons.md) — <!-- begin:auto-docs --> _(no submodules)_- [seasons](./src/seasons/seasons.md) — <!-- begin:auto-docs --> _(no submodules)_- [provider](./src/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [seasons](./src/seasons/seasons.md) — <!-- begin:auto-docs --> _(no submodules)_- [seasons](./src/seasons/seasons.md) — <!-- begin:auto-docs --> _(no submodules)_- [provider](./src/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [seasons](./src/seasons/seasons.md) — <!-- begin:auto-docs --> _(no submodules)_- [seasons](./src/seasons/seasons.md) — <!-- begin:auto-docs --> _(no submodules)_- [provider](./src/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [seasons](./src/seasons/seasons.md) — <!-- begin:auto-docs --> _(no submodules)_  - [seasons](./src/seasons/seasons.md) — <!-- begin:auto-docs --> _(no submodules)_
+## Install
+
+```bash
+bun add @suaveplan/solar-system
+```

docs/geospatial/geo/solar-system/src/provider/provider.md

@@ -0,0 +1,61 @@
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Composes a `SolarProvider` (from `@suaveplan/types`) over an injectable `AstronomyEngine` so callers can swap a deterministic stub, a high-precision ephemeris (e.g. VSOP87, JPL DE), or a remote API without touching downstream code. The provider emits `CelestialBody` records for the Sun, Moon, and the classical naked-eye planets, and delegates sunrise/sunset to the `seasons` module so a single calling site covers the full solar-day surface.
+
+## Features
+
+- `AstronomyEngine` interface — single seam (`bodyPosition(name, jd)`) for arbitrary ephemeris back-ends.
+- `DefaultEngine` — pure-deterministic placeholder useful for tests, demos, and offline builds.
+- `createSolarSystemProvider(engine?)` — factory returning a `SolarProvider` with sensible defaults.
+- Returns the seven canonical bodies (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn) in `getBodies()`.
+- Per-body lookup via `getBody(name)` with automatic `"star" | "moon" | "planet"` typing.
+- Sunrise / sunset honour an `Observer` argument so future engines can plug in topocentric refinements.
+
+## Usage: Basic Example
+
+```ts
+import { createSolarSystemProvider } from "@suaveplan/solar-system";
+
+const provider = createSolarSystemProvider();
+const sun = await provider.getBody("Sun");
+console.log(sun.type); // "star"
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    type AstronomyEngine,
+    createSolarSystemProvider,
+} from "@suaveplan/solar-system";
+
+class Vsop87Engine implements AstronomyEngine {
+    bodyPosition(name: string, jd: number) {
+        // delegate to a real ephemeris — values are heliocentric AU
+        return computeVsop87(name, jd);
+    }
+}
+
+const provider = createSolarSystemProvider(new Vsop87Engine());
+const bodies = await provider.getBodies();
+const observer = {
+    kind: "surface" as const,
+    planet: { name: "Earth", radius: 6_371_000, rotationPeriod: 86_164 },
+    coord: { latitude: 51.5, longitude: -0.1 },
+};
+const sunrise = await provider.getSunrise(observer, new Date());
+```
+
+## API Reference
+
+- `interface AstronomyEngine` — `bodyPosition(name: string, jd: number): { x: number; y: number; z: number }`. Returns heliocentric coordinates (AU) at the given Julian Date.
+- `class DefaultEngine implements AstronomyEngine` — deterministic placeholder; `bodyPosition` returns `{ x, y, z }` derived from the first character code of `name`, yielding `{0,0,0}` for empty names.
+- `createSolarSystemProvider(engine?: AstronomyEngine): SolarProvider` — `engine` defaults to a fresh `DefaultEngine`. Returned provider exposes `getBodies()`, `getBody(name)`, `getSunrise(observer, date)`, and `getSunset(observer, date)`. None of the methods throw under normal usage; engine errors surface as rejected promises.
+
+## Implementation Notes
+
+The provider is intentionally engine-agnostic: every astronomical computation flows through `AstronomyEngine.bodyPosition`, so swapping engines never requires editing `provider.ts`. `makeBody` currently fixes apparent magnitude, angular diameter, and topocentric altitude/azimuth — these are hooks for future engine extensions rather than computed values, and call sites should treat them as best-effort placeholders until a precision engine is wired in. Sunrise and sunset are delegated to the sibling `seasons` module to keep the time-of-day surface cohesive and testable. The factory accepts an `engine` argument so consumers can substitute deterministic engines in tests without `vi.mock`.

docs/geospatial/geo/solar-system/src/seasons/seasons.md

@@ -0,0 +1,65 @@
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Pure functions covering the solar-calendar surface: meteorological seasons, the next equinox / solstice after a given instant, sunrise / sunset offsets, and lunar-phase fraction. The module is intentionally side-effect-free and dependency-free so it ships in universal bundles (browser, server, R3F, edge) and remains trivial to substitute with a high-precision ephemeris later.
+
+## Features
+
+- `getSeason(date)` — returns one of `"spring" | "summer" | "autumn" | "winter"` using meteorological month boundaries (UTC).
+- `getNextEquinox(date)` / `getNextSolstice(date)` — placeholder implementations returning the next canonical event Date.
+- `getSunrise(date)` / `getSunset(date)` — return Dates offset by 6 h and 18 h respectively, suitable for tests and as a default until a precision engine is wired into `provider.ts`.
+- `getLunarPhase(date)` — returns a fraction in `[0, 1]` (currently a constant `0.5` placeholder).
+- Zero runtime dependencies; all functions are deterministic and synchronous.
+- Designed to be re-implemented behind the same signatures with a real ephemeris (e.g. SunCalc, Astronomy Engine) without changing call sites.
+
+## Usage: Basic Example
+
+```ts
+import { getSeason } from "@suaveplan/solar-system";
+
+const season = getSeason(new Date("2026-04-15T00:00:00Z"));
+console.log(season); // "spring"
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    getLunarPhase,
+    getNextEquinox,
+    getNextSolstice,
+    getSeason,
+    getSunrise,
+    getSunset,
+} from "@suaveplan/solar-system";
+
+const today = new Date();
+const summary = {
+    season: getSeason(today),
+    sunrise: getSunrise(today),
+    sunset: getSunset(today),
+    nextEquinox: getNextEquinox(today),
+    nextSolstice: getNextSolstice(today),
+    moonPhase: getLunarPhase(today),
+};
+
+// Pipe into a UI panel, ICS export, or scheduling rule.
+console.log(summary);
+```
+
+## API Reference
+
+- `type Season = "spring" | "summer" | "autumn" | "winter"` — UTC-month-based labelling.
+- `getSeason(date: Date): Season` — Mar–May spring, Jun–Aug summer, Sep–Nov autumn, otherwise winter.
+- `getNextEquinox(date: Date): Date` — currently returns the canonical March 2026 equinox; signature stable for a future precision impl.
+- `getNextSolstice(date: Date): Date` — currently returns the canonical June 2026 solstice; signature stable.
+- `getSunrise(date: Date): Date` — returns `date + 6h`.
+- `getSunset(date: Date): Date` — returns `date + 18h`.
+- `getLunarPhase(date: Date): number` — fraction in `[0, 1]`; `0` = new moon, `0.5` = full moon.
+
+## Implementation Notes
+
+The package favours a stable public surface over astronomical precision so swapping in a real ephemeris is a non-breaking change. `getSeason` uses UTC months to stay deterministic across runtimes — callers in the southern hemisphere should remap the labels at the application layer. The sunrise / sunset offsets are deliberate placeholders that satisfy `provider.getSunrise/getSunset` contracts (the returned Date is strictly after the input Date). When integrating a precision engine, replace function bodies in-place; tests rely only on monotonicity and return-type invariants, not exact times.