@openwaters/almanac 0.3.0 → 0.4.1

package/README.md

@@ -1,9 +1,6 @@
 # Almanac
 
-Offline sun & moon engine for the Salish Sea and everywhere else — positions,
-rise/set/twilight, moon phase, lunar eclipses (solar planned), and where any fixed
-star stands from a catalog position, computed from pure geometry with zero network
-and zero runtime data files.
+Offline sky engine for the Salish Sea and everywhere else: Sun and Moon positions, rise, set, twilight, Moon phase, lunar eclipses, solar eclipses for an observer, and fixed-star altitude and azimuth from catalog positions, computed from pure geometry with zero network and zero runtime data files.
 
 Twin implementations, one behavior:
 
@@ -12,22 +9,22 @@ Twin implementations, one behavior:
 - `fixtures/` — the shared test corpus (JPL Horizons, USNO, Espenak) both suites
   must pass; the contract that keeps the ports identical
 
-Supported interval: 1950-01-01T00:00Z ≤ t < 2101-01-01T00:00Z; results outside it
-raise a typed error. All instants are UT1-accurate, not civil-UTC-accurate in the far
-future — see the design spec's Conventions section for what that means and why.
+Supported interval: 1950-01-01T00:00Z ≤ t < 2101-01-01T00:00Z; results outside it raise a typed error. All instants are UT1-accurate, while unknown future DUT1 is outside the civil-UTC accuracy promise. See the [public contract](docs/CONTRACT.md#time-and-supported-interval) for the time model.
 
-- Design: [`docs/superpowers/specs/2026-08-28-almanac-v1-design.md`](docs/superpowers/specs/2026-08-28-almanac-v1-design.md)
-- Roadmap: [`docs/ROADMAP.md`](docs/ROADMAP.md) — what ships next, and what will not.
-- Landing page: [openwaters.io/sky](https://openwaters.io/sky) — the library running live in a browser.
+- Contract: [`docs/CONTRACT.md`](docs/CONTRACT.md), including coordinates, public behavior, accuracy, and fixture evidence.
+- Scope: [`docs/ROADMAP.md`](docs/ROADMAP.md), including supported behavior and deliberate boundaries.
+- Development and releases: [`CONTRIBUTING.md`](CONTRIBUTING.md), including pinned tools and required checks.
+- Landing page: [openwaters.io/sky](https://openwaters.io/sky), with the library running live in a browser.
 
 Algorithms translated from [Astronomy Engine](https://github.com/cosinekitty/astronomy)
 (MIT, Don Cross) — see [NOTICE](NOTICE). MIT licensed.
 
 ## Performance
 
-Almanac includes a shared performance harness for both ports: **15 workloads**
+Almanac includes a shared performance harness for both ports: **22 workloads**
 cover positions, a 228-hour sky track, short/year/polar event windows, full-range
-moon phases, and next/previous/range eclipse searches, including empty windows.
+moon phases, next/previous/range lunar and solar eclipse searches, including empty
+windows, and solar obscuration over a 228-hour track.
 
 The v0.2.1 optimizations reuse Moon and shadow geometry, flatten scratch arrays,
 and refine altitude crossings with fewer position evaluations. In the
@@ -43,20 +40,18 @@ median query time fell relative to the v0.2.0 astronomy code:
 | Previous lunar eclipse | 26.0% | 36.6% |
 | Lunar eclipses / 1950–2100 | 26.4% | 23.4% |
 
-TypeScript was measured on Ubuntu with Node 22; Swift used release builds on
-macOS 15. Each comparison builds both revisions with the same harness and
-toolchain, then takes seven interleaved process pairs with 300 ms warmup per
-process. Build and startup time are excluded. Timings vary by machine; the shared
-correctness fixtures and parity tolerances remain the accuracy gates.
+TypeScript was measured on Ubuntu; Swift used release builds on macOS. Each comparison builds both revisions with the same harness and toolchain, then takes seven interleaved process pairs with 300 ms warmup per process. Build and startup time are excluded. Timings vary by machine; the shared correctness fixtures and parity tolerances remain the accuracy gates.
 
-Reproduce the comparison locally from the repository root (Node 22+ and Swift
-5.9+):
+Reproduce the comparison locally from the repository root with mise 2026.9.1 or newer after installing the configured Node and Swift versions in `mise.toml`:
 
 ```bash
-npm ci --prefix typescript
-node benchmarks/run.mjs --base v0.2.0
+mise install
+mise exec -- npm ci --prefix typescript
+mise exec -- node benchmarks/run.mjs --base v0.2.0 --skip '^solar/'
 ```
 
+The `--skip` pattern leaves out the solar eclipse workloads, which need a base of 0.4.0 or later.
+
 CI runs the harness on code changes and fails on **median regressions over 20%**.
 Results include timing tables, raw samples, checksums, and revision/toolchain
 metadata. See [the harness guide](CONTRIBUTING.md#performance) for choosing a
@@ -74,7 +69,7 @@ npm install @openwaters/almanac
 ```
 
 ```ts
-import { nextLunarEclipse, lunarEclipseVisibility, sunEvents, starAltAz } from '@openwaters/almanac';
+import { nextLunarEclipse, lunarEclipseVisibility, nextSolarEclipse, solarObscuration, sunEvents, starAltAz } from '@openwaters/almanac';
 
 const observer = { latitudeDeg: 48.5, longitudeDeg: -123.0 };
 
@@ -82,6 +77,10 @@ const eclipse = nextLunarEclipse(new Date());
 const visibility = lunarEclipseVisibility(eclipse, observer);
 console.log(eclipse.kind, eclipse.peak, visibility.visibleAtPeak);
 
+const solar = nextSolarEclipse(new Date(), observer);
+console.log(solar.kind, solar.peak, solar.obscuration, solar.sunAltDeg.peak);
+console.log(solarObscuration(solar.peak, observer));   // fraction of the Sun's disc covered, 0 to 1
+
 const today = new Date();
 const tomorrow = new Date(today.getTime() + 24 * 60 * 60 * 1000);
 for (const { kind, time } of sunEvents(today, tomorrow, observer)) {
@@ -95,7 +94,7 @@ const { azDeg, altDeg } = starAltAz(88.792939, 7.407064, today, observer);
 ### Swift
 
 ```swift
-.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.3.0")
+.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.4.0")
 ```
 
 ```swift
@@ -108,6 +107,10 @@ let eclipse = try nextLunarEclipse(after: Date())
 let visibility = try lunarEclipseVisibility(eclipse, observer: observer)
 print(eclipse.kind, eclipse.peak, visibility.visibleAtPeak)
 
+let solar = try nextSolarEclipse(after: Date(), observer: observer)
+print(solar.kind, solar.peak, solar.obscuration, solar.sunAltDeg.peak)
+print(try solarObscuration(at: solar.peak, observer: observer))   // fraction of the Sun's disc covered, 0 to 1
+
 let today = Date()
 let tomorrow = today.addingTimeInterval(24 * 60 * 60)
 for event in try sunEvents(from: today, to: tomorrow, observer: observer) {
@@ -136,3 +139,5 @@ let eclipses = try lunarEclipses(from: today, to: tomorrow)
 Ranges include peaks at the start and exclude peaks at the end. Contacts may
 extend outside the range. Previous/next searches skip peaks within 100 ms of the
 anchor. Search results are global; apply `lunarEclipseVisibility` for an observer.
+
+Solar eclipses are searched for an observer, because their contacts only exist for a place: `nextSolarEclipse(after, observer)`, `previousSolarEclipse(before, observer)`, and `solarEclipses(startUtc, endUtc, observer)`. An eclipse whose Sun is below the horizon at C1, the peak, and C4 is not returned.

package/dist/eclipse.d.ts

@@ -1,4 +1,5 @@
 import { Observer } from './types.js';
+import { Vec3 } from './nutation.js';
 /** A lunar eclipse: peak circumstances plus the contact instants around them. */
 export interface LunarEclipse {
     /** `total` if the Moon is fully inside the umbra, `partial` if it touches
@@ -39,6 +40,57 @@ export interface LunarEclipseVisibility {
         p4: boolean;
     };
 }
+/** UPSTREAM: `PruneLatitude`, inside `SearchLunarEclipse` — full- or new-Moon
+ *  ecliptic latitude above which no eclipse is possible.
+ *  INTERNAL: shared with solar.ts. */
+export declare const PRUNE_LATITUDE_DEG = 1.8;
+/** Root-finder tolerance for every shadow search, seconds — upstream's `Search` default.
+ *  INTERNAL: shared with solar.ts. */
+export declare const SHADOW_TOL_SECONDS = 1;
+/** UPSTREAM: `Search`'s default `iter_limit`.
+ *  INTERNAL: shared with solar.ts. */
+export declare const SHADOW_ITER_CAP = 20;
+/**
+ * Peaks within 100 ms of a next/previous search anchor count as the same
+ * eclipse. The fixed full-moon seed below removes within-runtime drift; keep
+ * the band for peaks saved by older versions or computed on another runtime.
+ *
+ * This can skip a wanted peak when the anchor is within 100 ms of it, but
+ * cannot skip a distinct eclipse (the catalog's minimum gap is 29 days).
+ * Range searches use exact half-open bounds without this band.
+ * INTERNAL: shared with solar.ts.
+ */
+export declare const SAME_ECLIPSE_MS = 100;
+/**
+ * UPSTREAM: `ShadowInfo` (astronomy.ts ~8445). `target` and `dir` are the
+ * inputs `CalcShadow` measured from: the lunar case passes the geocentric
+ * Moon against the Sun-to-Earth line, the solar case (solar.ts) the
+ * lunacentric observer against the heliocentric Moon, and the obscuration
+ * path reads them back. Upstream's `time` is an `AstroTime`; here the instant
+ * travels as days since J2000 UT, as everywhere in L3.
+ * INTERNAL: exported for `solar.ts`, not part of the public API.
+ */
+export interface ShadowInfo {
+    /** Days since J2000 (UT). */
+    ut: number;
+    /** Shadow-axis parameter: distance to the shadow plane over the casting body's distance. */
+    u: number;
+    /** Distance from `target` to the shadow axis, km. */
+    r: number;
+    /** Umbra radius at the shadow plane, km. */
+    k: number;
+    /** Penumbra radius at the shadow plane, km. */
+    p: number;
+    /** The point measured from, AU. */
+    target: Vec3;
+    /** The shadow axis, AU. */
+    dir: Vec3;
+}
+/** UPSTREAM: `CalcShadow`, astronomy.ts ~8458. INTERNAL, shared with solar.ts. */
+export declare function calcShadow(bodyRadiusKm: number, ut: number, target: Vec3, dir: Vec3): ShadowInfo;
+/** UPSTREAM: `MoonEclipticLatitudeDegrees`, astronomy.ts ~8616.
+ *  INTERNAL: shared with solar.ts. */
+export declare function moonEclipticLatitudeDeg(ut: number): number;
 /**
  * The first lunar eclipse whose peak falls strictly after `after`.
  *

package/dist/eclipse.js

@@ -28,9 +28,10 @@ import { MOON_MEAN_RADIUS_KM, SUN_RADIUS_KM, search, searchMoonPhase } from './e
  *  The 88 km of atmosphere is what makes the umbra match observed eclipse
  *  magnitudes; it is not the geometric Earth radius. */
 const EARTH_ECLIPSE_RADIUS_KM = 6371.0 + 88.0;
-/** UPSTREAM: `PruneLatitude`, inside `SearchLunarEclipse` — full-Moon ecliptic
- *  latitude above which no eclipse is possible. */
-const PRUNE_LATITUDE_DEG = 1.8;
+/** UPSTREAM: `PruneLatitude`, inside `SearchLunarEclipse` — full- or new-Moon
+ *  ecliptic latitude above which no eclipse is possible.
+ *  INTERNAL: shared with solar.ts. */
+export const PRUNE_LATITUDE_DEG = 1.8;
 /** Spec: the search gives up after two years. The catalog's longest gap between
  *  consecutive lunar eclipses over 1950-2100 is under a year. */
 const SCAN_LIMIT_DAYS = 730;
@@ -39,10 +40,12 @@ const PEAK_WINDOW_DAYS = 0.03;
 /** Upstream's outermost `ShadowSemiDurationMinutes` window, in minutes. */
 const PENUMBRAL_WINDOW_MINUTES = 200.0;
 const MINUTES_PER_DAY = 24.0 * 60.0;
-/** Root-finder tolerance for every shadow search, seconds — upstream's `Search` default. */
-const SHADOW_TOL_SECONDS = 1;
-/** UPSTREAM: `Search`'s default `iter_limit`. */
-const SHADOW_ITER_CAP = 20;
+/** Root-finder tolerance for every shadow search, seconds — upstream's `Search` default.
+ *  INTERNAL: shared with solar.ts. */
+export const SHADOW_TOL_SECONDS = 1;
+/** UPSTREAM: `Search`'s default `iter_limit`.
+ *  INTERNAL: shared with solar.ts. */
+export const SHADOW_ITER_CAP = 20;
 /**
  * Peaks within 100 ms of a next/previous search anchor count as the same
  * eclipse. The fixed full-moon seed below removes within-runtime drift; keep
@@ -51,10 +54,11 @@ const SHADOW_ITER_CAP = 20;
  * This can skip a wanted peak when the anchor is within 100 ms of it, but
  * cannot skip a distinct eclipse (the catalog's minimum gap is 29 days).
  * Range searches use exact half-open bounds without this band.
+ * INTERNAL: shared with solar.ts.
  */
-const SAME_ECLIPSE_MS = 100;
-/** UPSTREAM: `CalcShadow`, astronomy.ts ~8458. */
-function calcShadow(bodyRadiusKm, ut, target, dir) {
+export const SAME_ECLIPSE_MS = 100;
+/** UPSTREAM: `CalcShadow`, astronomy.ts ~8458. INTERNAL, shared with solar.ts. */
+export function calcShadow(bodyRadiusKm, ut, target, dir) {
     const u = (dir.x * target.x + dir.y * target.y + dir.z * target.z) / (dir.x * dir.x + dir.y * dir.y + dir.z * dir.z);
     const dx = (u * dir.x) - target.x;
     const dy = (u * dir.y) - target.y;
@@ -62,7 +66,7 @@ function calcShadow(bodyRadiusKm, ut, target, dir) {
     const r = KM_PER_AU * Math.hypot(dx, dy, dz);
     const k = +SUN_RADIUS_KM - (1.0 + u) * (SUN_RADIUS_KM - bodyRadiusKm);
     const p = -SUN_RADIUS_KM + (1.0 + u) * (SUN_RADIUS_KM + bodyRadiusKm);
-    return { ut, u, r, k, p };
+    return { ut, u, r, k, p, target, dir };
 }
 /**
  * UPSTREAM: `EarthShadow`, astronomy.ts ~8470 — the Earth's shadow cone
@@ -119,8 +123,9 @@ function shadowSemiDurationMinutes(shadow, radiusLimitKm, windowMinutes) {
         throw new Error('almanac internal: failed to find shadow semiduration');
     return (t2 - t1) * (MINUTES_PER_DAY / 2.0); // convert days to minutes and average the semi-durations
 }
-/** UPSTREAM: `MoonEclipticLatitudeDegrees`, astronomy.ts ~8616. */
-function moonEclipticLatitudeDeg(ut) {
+/** UPSTREAM: `MoonEclipticLatitudeDegrees`, astronomy.ts ~8616.
+ *  INTERNAL: shared with solar.ts. */
+export function moonEclipticLatitudeDeg(ut) {
     return RAD2DEG * calcMoon(ttDaysFromUt(ut)).geoEclipLat;
 }
 /**

package/dist/index.d.ts

@@ -10,3 +10,5 @@ export type { SunEvent, SunEventKind, MoonEvent, MoonEventKind, MoonPhaseEvent,
 export { sunEvents, moonEvents, searchMoonPhases } from './events.js';
 export type { LunarEclipse, LunarEclipseVisibility } from './eclipse.js';
 export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';
+export type { SolarEclipse, SolarEclipseKind, SolarEclipseSunAltitudes } from './solar.js';
+export { nextSolarEclipse, previousSolarEclipse, solarEclipses, solarObscuration } from './solar.js';

package/dist/index.js

@@ -4,3 +4,4 @@ export { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
 export { moonIllumination } from './illumination.js';
 export { sunEvents, moonEvents, searchMoonPhases } from './events.js';
 export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';
+export { nextSolarEclipse, previousSolarEclipse, solarEclipses, solarObscuration } from './solar.js';