@openwaters/almanac 0.4.1 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # Almanac
 
-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.
+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 anywhere on Earth, 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:
 
@@ -21,36 +21,38 @@ Algorithms translated from [Astronomy Engine](https://github.com/cosinekitty/ast
 
 ## Performance
 
-Almanac includes a shared performance harness for both ports: **22 workloads**
+Almanac includes a shared performance harness for both ports: **27 workloads**
 cover positions, a 228-hour sky track, short/year/polar event windows, full-range
-moon phases, next/previous/range lunar and solar eclipse searches, including empty
-windows, and solar obscuration over a 228-hour track.
+moon phases, next/previous/range lunar, solar, and global solar eclipse searches,
+including empty windows, solar obscuration over a 228-hour track, and the central
+line of the 2024-04-08 eclipse.
 
-The v0.2.1 optimizations reuse Moon and shadow geometry, flatten scratch arrays,
-and refine altitude crossings with fewer position evaluations. In the
-[hosted CI comparison](https://github.com/openwatersio/almanac/actions/runs/34119038860),
-median query time fell relative to the v0.2.0 astronomy code:
+Event searches find altitude extrema with Brent's method and altitude crossings
+with a cosine-seeded secant solver, each root proven inside a half-second
+bracket, and the TypeScript Sun series evaluates its terms as straight-line
+arithmetic. Median query time relative to v0.4.1:
 
 | Workload | TypeScript: less time | Swift: less time |
 | --- | ---: | ---: |
-| Moon positions / 1,024 hours | 29.8% | 22.1% |
-| Sky track / 228 hours | 40.0% | 42.4% |
-| Sun events / 228 hours | 39.3% | 40.2% |
-| Moon events / 228 hours | 39.1% | 35.1% |
-| Previous lunar eclipse | 26.0% | 36.6% |
-| Lunar eclipses / 1950–2100 | 26.4% | 23.4% |
+| Sun events / year | 73.4% | 62.8% |
+| Moon events / year | 57.6% | 57.4% |
+| Sun events / 228 hours | 73.4% | 61.9% |
+| Moon events / 228 hours | 57.1% | 57.0% |
+| Sun positions / 1,024 hours | 35.5% | — |
+| Lunar eclipses / 1950–2100 | 24.6% | — |
 
-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.
+Swift already evaluated the Sun series efficiently, so its gains are confined to
+the searches. 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 with mise 2026.9.1 or newer after installing the configured Node and Swift versions in `mise.toml`:
 
 ```bash
 mise install
 mise exec -- npm ci --prefix typescript
-mise exec -- node benchmarks/run.mjs --base v0.2.0 --skip '^solar/'
+mise exec -- node benchmarks/run.mjs --base v0.4.1 --skip '^global/'
 ```
 
-The `--skip` pattern leaves out the solar eclipse workloads, which need a base of 0.4.0 or later.
+The `--skip` pattern leaves out the global solar eclipse workloads, which need a base of 0.5.0 or later. Use `--skip '^(solar|global)/'` when the base predates 0.4.0, which is when the solar eclipse workloads arrived.
 
 CI runs the harness on code changes and fails on **median regressions over 20%**.
 Results include timing tables, raw samples, checksums, and revision/toolchain
@@ -69,7 +71,9 @@ npm install @openwaters/almanac
 ```
 
 ```ts
-import { nextLunarEclipse, lunarEclipseVisibility, nextSolarEclipse, solarObscuration, sunEvents, starAltAz } from '@openwaters/almanac';
+import {
+  nextLunarEclipse, lunarEclipseVisibility, nextSolarEclipse, solarObscuration, nextGlobalSolarEclipse, sunEvents, starAltAz
+} from '@openwaters/almanac';
 
 const observer = { latitudeDeg: 48.5, longitudeDeg: -123.0 };
 
@@ -81,6 +85,9 @@ 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 anywhere = nextGlobalSolarEclipse(new Date());   // no observer: the next solar eclipse on Earth
+console.log(anywhere.kind, anywhere.peak, anywhere.latitudeDeg, anywhere.longitudeDeg);   // where the shadow axis lands; null for a partial
+
 const today = new Date();
 const tomorrow = new Date(today.getTime() + 24 * 60 * 60 * 1000);
 for (const { kind, time } of sunEvents(today, tomorrow, observer)) {
@@ -94,7 +101,7 @@ const { azDeg, altDeg } = starAltAz(88.792939, 7.407064, today, observer);
 ### Swift
 
 ```swift
-.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.4.0")
+.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.5.0")
 ```
 
 ```swift
@@ -111,6 +118,12 @@ 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 anywhere = try nextGlobalSolarEclipse(after: Date())   // no observer: the next solar eclipse on Earth
+print(anywhere.kind, anywhere.peak, anywhere.axisDistanceKm)
+if let lat = anywhere.latitudeDeg, let lon = anywhere.longitudeDeg {
+  print(lat, lon)   // where the shadow axis lands; nil for a partial
+}
+
 let today = Date()
 let tomorrow = today.addingTimeInterval(24 * 60 * 60)
 for event in try sunEvents(from: today, to: tomorrow, observer: observer) {
@@ -141,3 +154,22 @@ 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.
+
+To ask about the whole Earth instead, `nextGlobalSolarEclipse(after)`, `previousGlobalSolarEclipse(before)`, and `globalSolarEclipses(startUtc, endUtc)` need no observer. Each eclipse reports its greatest eclipse, the shadow axis's distance from the Earth's center, and where the axis meets the ground, with the kind and obscuration seen there. When the axis misses the Earth the eclipse is partial and has no ground point.
+
+`solarEclipseCentralLine(peak, stepSeconds)` samples where the axis meets the ground from its first contact to its last, and `solarEclipseAxisPoint(time)` gives that point at any instant. How far the next totality passes from a place is a distance to each point of a line:
+
+```ts
+import { nextGlobalSolarEclipse, solarEclipseCentralLine } from '@openwaters/almanac';
+let next = nextGlobalSolarEclipse(new Date());
+while (next.kind !== 'total') next = nextGlobalSolarEclipse(next.peak);
+const line = solarEclipseCentralLine(next.peak);   // every whole minute of the path, and its two ends
+```
+
+```swift
+var next = try nextGlobalSolarEclipse(after: Date())
+while next.kind != .total { next = try nextGlobalSolarEclipse(after: next.peak) }
+let line = try solarEclipseCentralLine(peak: next.peak)   // every whole minute of the path, and its two ends
+```
+
+Points are a median 47 km apart at the default step but hundreds apart beside an end, where the shadow races along the horizon; pass a smaller `stepSeconds` for a finer line.

package/dist/events.js

@@ -8,8 +8,9 @@
 // a grid can straddle both halves of a grazing pair (the polar-onset day where
 // the Sun sets at 08:00 and rises again at 08:16) and report neither. Here each
 // daily cycle's altitude extrema are located numerically and every monotonic
-// segment between consecutive extrema is bisected, so a pair of crossings
-// minutes apart is bracketed by construction rather than by luck of the grid.
+// segment between consecutive extrema is solved for each target level, so a
+// pair of crossings minutes apart is bracketed by construction rather than by
+// luck of the grid.
 // Hour angle supplies only the initial bracket: HA 0/12h are not the exact
 // extrema, because declination, distance and lunar parallax all drift within a
 // cycle, and toward the poles the daily altitude cycle flattens until the
@@ -22,7 +23,7 @@
 // and `NextMoonQuarter` (~5362).
 import { assertObserver, assertSupported, assertSupportedWindowEnd, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
 import { dateFromUt, ttDaysFromUt, utDays } from './time.js';
-import { KM_PER_AU, RAD2DEG } from './nutation.js';
+import { DEG2RAD, KM_PER_AU, RAD2DEG } from './nutation.js';
 import { topoAltAzUnrefracted } from './transforms.js';
 import { sunGeoVectorEqj } from './sun.js';
 import { moonGeoVectorEqj } from './moon.js';
@@ -57,7 +58,7 @@ const SUN_CYCLE_DAYS = 1;
 const MOON_CYCLE_DAYS = 1.035050;
 const MOON_HA_RATE_DEG_PER_DAY = 360 / MOON_CYCLE_DAYS;
 const SECOND_DAYS = 1 / 86400;
-/** Bisection and golden-section both stop under a second; events are reported to the ms. */
+/** Every search stops under a second; events are reported to the ms. */
 const TIME_TOL_DAYS = SECOND_DAYS;
 /** An extremum this close to the target grazes it without crossing: no event. */
 const TANGENT_EPS_DEG = 1e-6;
@@ -76,6 +77,7 @@ const EXTREMUM_HALF_WIDTH_DAYS = 2 / 24;
 const FLAT_CYCLE_LATITUDE_DEG = 85;
 const GOLDEN_SECTION_CAP = 100;
 const BISECTION_CAP = 60;
+const SECANT_CAP = 8;
 const HOUR_ANGLE_ITER_CAP = 20;
 const MOON_PHASE_ITER_CAP = 50;
 const INV_PHI = 0.6180339887498949;
@@ -171,8 +173,7 @@ function nextHourAngle(sample, afterUt, targetHaDeg, rateDegPerDay) {
     return ut;
 }
 /**
- * Golden-section refinement of the altitude extremum bracketed around
- * `centreUt`. Evaluating the true extremum is what makes a grazing pair
+ * Refinement of the altitude extremum bracketed around `centreUt`. Evaluating the true extremum is what makes a grazing pair
  * findable: the segment on either side of it is monotonic, so bisection can
  * only miss a crossing if the extremum itself was never seen.
  *
@@ -182,9 +183,105 @@ function nextHourAngle(sample, afterUt, targetHaDeg, rateDegPerDay) {
  * declination's slow annual drift, unclamped golden section will happily walk
  * backwards and break the chain's ordering.
  */
-function refineExtremum(sample, centreUt, wantMax, halfWidthDays, afterUt) {
-    let a = Math.max(clampUt(centreUt - halfWidthDays), afterUt);
-    let b = clampUt(centreUt + halfWidthDays);
+function refineExtremum(sample, centreUt, wantMax, halfWidthDays, afterUt, flatCycle) {
+    const a = Math.max(clampUt(centreUt - halfWidthDays), afterUt);
+    const b = clampUt(centreUt + halfWidthDays);
+    if (!flatCycle) {
+        const best = brentExtremum(sample, a, b, wantMax);
+        if (best !== null)
+            return best;
+    }
+    return goldenExtremum(sample, a, b, wantMax);
+}
+/**
+ * Brent's parabolic-plus-golden minimizer on `[a, b]`, scored for a maximum
+ * or minimum. Each step evaluates one sample; a parabola through the three
+ * best points supplies the step whenever it is finite, lands strictly inside
+ * the bracket, and contracts faster than the step before last, and golden
+ * section takes over otherwise. Returns `null` when the search hits its cap or
+ * settles within a tolerance of the original bracket edge, where the flat,
+ * asymmetric altitude curve has made the parabola unreliable; the caller then
+ * runs the golden search unchanged.
+ */
+function brentExtremum(sample, a0, b0, wantMax) {
+    const cost = (s) => (wantMax ? -s.altDeg : s.altDeg);
+    let a = a0;
+    let b = b0;
+    let x = a + (1 - INV_PHI) * (b - a);
+    let w = x;
+    let v = x;
+    let sx = sample(x);
+    let fx = cost(sx);
+    let fw = fx;
+    let fv = fx;
+    let d = 0; // the last step taken
+    let e = 0; // the step before last, which the parabolic step must beat
+    for (let i = 0; i < GOLDEN_SECTION_CAP; i++) {
+        if (b - a < TIME_TOL_DAYS) {
+            return x - a0 < TIME_TOL_DAYS || b0 - x < TIME_TOL_DAYS ? null : sx;
+        }
+        const tol1 = Math.max(TIME_TOL_DAYS / 16, 4 * Number.EPSILON * Math.abs(x));
+        const xm = (a + b) / 2;
+        let golden = true;
+        if (Math.abs(e) > tol1) {
+            const r = (x - w) * (fx - fv);
+            let q = (x - v) * (fx - fw);
+            let p = (x - v) * q - (x - w) * r;
+            q = 2 * (q - r);
+            if (q > 0)
+                p = -p;
+            q = Math.abs(q);
+            const eTemp = e;
+            e = d;
+            if (Number.isFinite(p / q) && Math.abs(p) < Math.abs(0.5 * q * eTemp) && p > q * (a - x) && p < q * (b - x)) {
+                d = p / q;
+                // Near an edge the parabola only re-proposes the best point; step across it instead.
+                if (x + d - a < 2 * tol1 || b - (x + d) < 2 * tol1)
+                    d = xm >= x ? tol1 : -tol1;
+                golden = false;
+            }
+        }
+        if (golden) {
+            e = x >= xm ? a - x : b - x;
+            d = (1 - INV_PHI) * e;
+        }
+        const u = Math.abs(d) >= tol1 ? x + d : x + (d >= 0 ? tol1 : -tol1);
+        const su = sample(u);
+        const fu = cost(su);
+        if (fu <= fx) {
+            if (u >= x)
+                a = x;
+            else
+                b = x;
+            v = w;
+            fv = fw;
+            w = x;
+            fw = fx;
+            x = u;
+            fx = fu;
+            sx = su;
+        }
+        else {
+            if (u < x)
+                a = u;
+            else
+                b = u;
+            if (fu <= fw || w === x) {
+                v = w;
+                fv = fw;
+                w = u;
+                fw = fu;
+            }
+            else if (fu <= fv || v === x || v === w) {
+                v = u;
+                fv = fu;
+            }
+        }
+    }
+    return null;
+}
+/** Golden-section search of the extremum on `[a, b]`: slow, and safe on any curve shape. */
+function goldenExtremum(sample, a, b, wantMax) {
     let x1 = b - INV_PHI * (b - a);
     let x2 = a + INV_PHI * (b - a);
     let s1 = sample(x1);
@@ -215,16 +312,27 @@ function refineExtremum(sample, centreUt, wantMax, halfWidthDays, afterUt) {
     return score(s1) > score(s2) ? s1 : s2;
 }
 /**
- * Quadratically accelerated search for the single crossing of `level` on a
- * monotonic segment, with bisection if the estimate cannot be verified.
+ * The single crossing of `level` on a monotonic segment between two extrema,
+ * reported from inside a verified half-second bracket.
+ *
+ * Between extrema the altitude offset is close to a half cosine, so the cosine
+ * through the two endpoints predicts the crossing to within a minute for the
+ * Sun and a few minutes for the Moon, with no probe at all. Secant steps from
+ * that estimate reach the second in one or two probes, and one more probe on
+ * the side the last sign points to proves the bracket. Anything that escapes
+ * the segment, stalls, or fails the proof falls back to the quadratically
+ * accelerated bracketed search with bisection behind it.
  */
-function bisectCrossing(sample, level, s0, s1) {
+function solveCrossing(sample, level, s0, s1) {
     let a = s0.ut;
     let b = s1.ut;
     const belowAtA = offsetDeg(s0, level) < 0;
-    // Reuse the phase search's quadratic acceleration, normalized to an
-    // ascending crossing. Endpoint geometry has already been evaluated.
+    // Normalized to an ascending crossing. Endpoint geometry has already been evaluated.
     const f = (ut) => (belowAtA ? 1 : -1) * offsetDeg(ut === s0.ut ? s0 : ut === s1.ut ? s1 : sample(ut), level);
+    const targetDeg = level === null ? (s0.riseSetAltDeg + s1.riseSetAltDeg) / 2 : level;
+    const secant = secantCrossing(f, a, b, s0, s1, targetDeg);
+    if (secant !== null)
+        return secant;
     const root = search(f, a, b, 0.25, BISECTION_CAP, 'altitude crossing');
     if (root !== null) {
         // A derivative-based estimate alone does not establish a time bound.
@@ -246,6 +354,51 @@ function bisectCrossing(sample, level, s0, s1) {
     assertReached(false, 'crossing bisection');
     return (a + b) / 2;
 }
+/**
+ * Secant refinement of the ascending crossing of `f` on `[a, b]`, started from
+ * the half cosine that the sine of altitude follows between two extrema.
+ * Returns the root inside a proven half-second bracket, or `null` when the
+ * caller should run the bracketed search.
+ */
+function secantCrossing(f, a, b, s0, s1, targetDeg) {
+    // sin(alt) ≈ c + amp·cos(π (t − a) / (b − a)) passes through both extrema; a
+    // constant declination and no parallax would make it exact.
+    const g0 = Math.sin(s0.altDeg * DEG2RAD);
+    const g1 = Math.sin(s1.altDeg * DEG2RAD);
+    const c = (g0 + g1) / 2;
+    const amp = (g0 - g1) / 2;
+    const ratio = (Math.sin(targetDeg * DEG2RAD) - c) / amp;
+    if (!(Math.abs(ratio) < 1))
+        return null;
+    const theta = Math.acos(ratio);
+    let t = a + theta * (b - a) / Math.PI;
+    let slope = Math.abs(amp) * Math.sin(theta) * Math.PI / (b - a) / Math.cos(targetDeg * DEG2RAD) * RAD2DEG;
+    let ft = f(t);
+    for (let i = 0; i < SECANT_CAP; i++) {
+        const step = -ft / slope;
+        if (!Number.isFinite(step))
+            return null;
+        if (Math.abs(step) < TIME_TOL_DAYS / 4) {
+            // The last sign says which side the root is on: prove a half-second
+            // bracket there, then report the secant root itself, held inside the
+            // bracket, so the answer does not jump with the side the probe picked.
+            if (ft < 0) {
+                const right = Math.min(b, t + TIME_TOL_DAYS / 2);
+                return f(right) >= 0 ? Math.min(t + step, right) : null;
+            }
+            const left = Math.max(a, t - TIME_TOL_DAYS / 2);
+            return f(left) < 0 ? Math.max(left, t + step) : null;
+        }
+        const next = t + step;
+        if (next <= a || next >= b)
+            return null;
+        const fNext = f(next);
+        slope = (fNext - ft) / (next - t);
+        t = next;
+        ft = fNext;
+    }
+    return null;
+}
 /**
  * Walk the window one half-cycle at a time, refining each altitude extremum and
  * solving every monotonic segment between consecutive extrema for every target
@@ -253,7 +406,8 @@ function bisectCrossing(sample, level, s0, s1) {
  * containing the window's first instant is covered, and runs one extremum past
  * `endUt` so an event just inside the window's end is too.
  */
-function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRateDegPerDay, cycleDays, extremumHalfWidthDays) {
+function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRateDegPerDay, cycleDays, flatCycle) {
+    const extremumHalfWidthDays = flatCycle ? cycleDays / 2 : EXTREMUM_HALF_WIDTH_DAYS;
     const found = [];
     const emit = (ut, kind) => {
         const q = quantizedUt(ut);
@@ -276,29 +430,16 @@ function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRat
         // extremum we are not allowed to probe past. The segment up to it is
         // still monotonic, so any crossing inside the window is still found.
         const s1 = atRangeEnd ? sample(MAX_UT)
-            : refineExtremum(sample, nextEst, nextIsMax, extremumHalfWidthDays, s0.ut);
+            : refineExtremum(sample, nextEst, nextIsMax, extremumHalfWidthDays, s0.ut, flatCycle);
         assertReached(s1.ut > s0.ut, 'extremum chain ordering');
         // Earlier extrema still establish the chain, but their crossings cannot be emitted.
         if (quantizedUt(s1.ut) >= startUt) {
-            let crossingSample = sample;
-            if (levels.length > 1) {
-                // Twilight levels share midpoint probes; retain them only for this segment.
-                const samples = new Map();
-                crossingSample = (ut) => {
-                    const previous = samples.get(ut);
-                    if (previous)
-                        return previous;
-                    const current = sample(ut);
-                    samples.set(ut, current);
-                    return current;
-                };
-            }
             for (const spec of levels) {
                 const g0 = crossingSign(s0, spec.level);
                 const g1 = crossingSign(s1, spec.level);
                 if (g0 * g1 >= 0)
                     continue; // no crossing, or a graze that only touches
-                emit(bisectCrossing(crossingSample, spec.level, s0, s1), g1 > 0 ? spec.rising : spec.falling);
+                emit(solveCrossing(sample, spec.level, s0, s1), g1 > 0 ? spec.rising : spec.falling);
             }
         }
         if (nextIsMax && transitKind !== null && !atRangeEnd)
@@ -321,10 +462,8 @@ const SUN_LEVELS = [
 const MOON_LEVELS = [
     { level: null, rising: 'rise', falling: 'set' },
 ];
-function extremumHalfWidth(observer, cycleDays) {
-    return Math.abs(observer.latitudeDeg) >= FLAT_CYCLE_LATITUDE_DEG
-        ? cycleDays / 2
-        : EXTREMUM_HALF_WIDTH_DAYS;
+function flatCycle(observer) {
+    return Math.abs(observer.latitudeDeg) >= FLAT_CYCLE_LATITUDE_DEG;
 }
 /**
  * Sun rise, set, the three twilights and upper transit within the half-open
@@ -344,7 +483,7 @@ export function sunEvents(startUtc, endUtc, observer) {
     assertObserver(observer);
     if (startUtc.getTime() >= endUtc.getTime())
         return [];
-    return searchAltitudeEvents(sunSampler(observer), SUN_LEVELS, 'transit', utDays(startUtc), utDays(endUtc), SUN_HA_RATE_DEG_PER_DAY, SUN_CYCLE_DAYS, extremumHalfWidth(observer, SUN_CYCLE_DAYS));
+    return searchAltitudeEvents(sunSampler(observer), SUN_LEVELS, 'transit', utDays(startUtc), utDays(endUtc), SUN_HA_RATE_DEG_PER_DAY, SUN_CYCLE_DAYS, flatCycle(observer));
 }
 /**
  * Moonrise and moonset within the half-open window `[startUtc, endUtc)`,
@@ -358,7 +497,7 @@ export function moonEvents(startUtc, endUtc, observer) {
     assertObserver(observer);
     if (startUtc.getTime() >= endUtc.getTime())
         return [];
-    return searchAltitudeEvents(moonSampler(observer), MOON_LEVELS, null, utDays(startUtc), utDays(endUtc), MOON_HA_RATE_DEG_PER_DAY, MOON_CYCLE_DAYS, extremumHalfWidth(observer, MOON_CYCLE_DAYS));
+    return searchAltitudeEvents(moonSampler(observer), MOON_LEVELS, null, utDays(startUtc), utDays(endUtc), MOON_HA_RATE_DEG_PER_DAY, MOON_CYCLE_DAYS, flatCycle(observer));
 }
 // -------------------------------------------------------------- moon phases
 /**

package/dist/globalSolar.d.ts

@@ -0,0 +1,76 @@
+import { SolarEclipseKind } from './solar.js';
+/** A solar eclipse as the whole Earth sees it: greatest eclipse, and where the Moon's shadow axis meets the ground then. */
+export interface GlobalSolarEclipse {
+    /** Kind at the point where the shadow axis meets the ground; `partial` when the axis misses the Earth. */
+    kind: SolarEclipseKind;
+    /** Greatest eclipse: the instant the Moon's shadow axis passes closest to the Earth's center. */
+    peak: Date;
+    /** Distance from the shadow axis to the Earth's center at the peak, km. */
+    axisDistanceKm: number;
+    /** Geodetic latitude where the axis meets the ground at the peak, degrees; `null` for a partial eclipse. */
+    latitudeDeg: number | null;
+    /** Longitude where the axis meets the ground at the peak, degrees east in (−180, 180]; `null` for a partial eclipse. */
+    longitudeDeg: number | null;
+    /** Fraction of the Sun's disc area covered at that point; exactly 1 for a total eclipse; `null` for a partial eclipse. */
+    obscuration: number | null;
+}
+/** A point on a solar eclipse's central line: where the Moon's shadow axis meets the ground at one instant. */
+export interface SolarEclipseAxisPoint {
+    time: Date;
+    /** Geodetic latitude, degrees. */
+    latitudeDeg: number;
+    /** Longitude, degrees east in (−180, 180]. */
+    longitudeDeg: number;
+    /** `total` or `annular` at this point; the kind can change along a hybrid path. */
+    kind: 'total' | 'annular';
+    /** Fraction of the Sun's disc area covered at this point; exactly 1 for a total eclipse. */
+    obscuration: number;
+}
+/**
+ * The first solar eclipse anywhere on Earth whose greatest eclipse falls
+ * strictly after `after`.
+ *
+ * Every new moon up to the end of the supported interval is tested: the
+ * Moon's ecliptic latitude prunes the ones no shadow can reach, and the rest
+ * get a peak-shadow search against the Earth's center. A new moon is an
+ * eclipse when the Moon's penumbra reaches the Earth.
+ *
+ * @throws {AlmanacOutOfRangeError} if `after` is outside the supported
+ *      interval, or if no eclipse remains before the end of it.
+ * @throws {RangeError} if `after` is invalid.
+ */
+export declare function nextGlobalSolarEclipse(after: Date): GlobalSolarEclipse;
+/**
+ * The last solar eclipse anywhere on Earth whose greatest eclipse falls
+ * strictly before `before`, skipping peaks within 100 ms of it, just as
+ * `nextGlobalSolarEclipse` does on the other side.
+ *
+ * @throws {AlmanacOutOfRangeError} if `before` is outside the supported
+ *      interval, or if no eclipse remains after the start of it.
+ * @throws {RangeError} if `before` is invalid.
+ */
+export declare function previousGlobalSolarEclipse(before: Date): GlobalSolarEclipse;
+/** Solar eclipses anywhere on Earth with greatest eclipse in `[startUtc, endUtc)`, sorted ascending. */
+export declare function globalSolarEclipses(startUtc: Date, endUtc: Date): GlobalSolarEclipse[];
+/**
+ * Where the Moon's shadow axis meets the ground at `time`, with the kind and
+ * obscuration a person standing there sees, or `null` when the axis misses
+ * the Earth. This is the point `nextGlobalSolarEclipse` reports at greatest
+ * eclipse, at any instant.
+ *
+ * @throws {AlmanacOutOfRangeError} if `time` is outside the supported interval.
+ * @throws {RangeError} if `time` is invalid.
+ */
+export declare function solarEclipseAxisPoint(time: Date): SolarEclipseAxisPoint | null;
+/**
+ * The central line of the solar eclipse in progress at `peak`, normally its
+ * greatest eclipse: the axis point at every whole multiple of `stepSeconds`
+ * between the first and last ground contact, with the points where the axis
+ * grazes the Earth at those two contacts as its ends. Empty when the axis
+ * misses the Earth at `peak`, as it does for a partial eclipse.
+ *
+ * @throws {AlmanacOutOfRangeError} if `peak` is outside the supported interval.
+ * @throws {RangeError} if `peak` is invalid, or `stepSeconds` is not a whole
+ *      number from 1 to 3600.
+ */
+export declare function solarEclipseCentralLine(peak: Date, stepSeconds?: number): SolarEclipseAxisPoint[];

package/dist/globalSolar.js

@@ -0,0 +1,357 @@
+// L3 solar eclipses anywhere on Earth: the Moon's shadow cone against the
+// Earth's center at every new moon — greatest eclipse, how far the shadow
+// axis passes from the center then, and where the axis meets the ground, with
+// the kind and covered fraction a person standing there sees. The same
+// intersection at any instant gives the axis point, and between the axis's
+// first and last ground contact, the central line.
+//
+// Translated from the cosinekitty/astronomy upstream, pinned sha
+// 865d3da7d8112bbc7911238052c6af4aaf877181, source/js/astronomy.ts:
+//   EARTH_MEAN_RADIUS_KM (142), MoonShadow (~8481), PeakMoonShadow (~8564),
+//   GeoidIntersect (~8842) and SearchGlobalSolarEclipse (~8975).
+// Constants and operation order are preserved so the Swift port can be a
+// line-for-line translation.
+//
+// Four deliberate departures from upstream, all spec-driven:
+//   - the new-moon probe is this package's `searchMoonPhase`, whose longitudes
+//     are apparent rather than upstream's geometric (see events.ts). It only
+//     seeds a ±0.03 d peak search, so the ~40 s difference cannot change a
+//     result.
+//   - previous and range searches, the fixed whole-UT-day new-moon seed and
+//     the 100 ms same-eclipse band come from the lunar port (eclipse.ts);
+//     upstream searches forward only.
+//   - no twelve-new-moon scan limit: next/previous walk new moons to the
+//     supported boundary, as the local search does (solar.ts).
+//   - upstream's `Rotation_EQJ_EQD` matrix and its inverse are `gyration` in
+//     each direction: the same precession and nutation, applied as two
+//     rotations rather than one combined matrix.
+//
+// The central line is not upstream's: its ends are roots of the intersection
+// quadratic's discriminant, and an axis point rejects the crossing on the
+// Sun's side of the Moon that upstream, asking only at greatest eclipse,
+// never meets.
+import { assertSupported, assertSupportedWindowEnd, AlmanacOutOfRangeError, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
+import { dateFromUt, ttDaysFromUt, utDays } from './time.js';
+import { EARTH_EQUATORIAL_RADIUS_KM, EARTH_FLATTENING, EARTH_FLATTENING_SQUARED, KM_PER_AU, RAD2DEG, PrecessDirection, gyration } from './nutation.js';
+import { moonGeoVectorEqj } from './moon.js';
+import { sunGeoVectorEqj } from './sun.js';
+import { siderealDeg } from './transforms.js';
+import { MOON_MEAN_RADIUS_KM, search, searchMoonPhase } from './events.js';
+import { calcShadow, moonEclipticLatitudeDeg, PRUNE_LATITUDE_DEG, SAME_ECLIPSE_MS, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP } from './eclipse.js';
+import { MOON_POLAR_RADIUS_KM, eclipseKindFromUmbra, solarEclipseObscuration } from './solar.js';
+/**
+ * UPSTREAM: `EARTH_MEAN_RADIUS_KM`, astronomy.ts 142 — the geoid's mean
+ * radius. A new moon is an eclipse when the Moon's penumbra reaches this
+ * sphere. The lunar port's `EARTH_ECLIPSE_RADIUS_KM` (eclipse.ts) is a
+ * different constant: it adds 88 km of atmosphere for the Earth's own shadow.
+ */
+const EARTH_MEAN_RADIUS_KM = 6371.0;
+/** Upstream's `PeakMoonShadow` window, in days, either side of the new moon. */
+const PEAK_WINDOW_DAYS = 0.03;
+/** How far either side of a ground point the search for the central line's ends reaches, days: longer than any path lasts. */
+const CONTACT_WINDOW_DAYS = 0.25;
+/** The central line's ends are found to a millisecond: the crossing races along the horizon there. */
+const CONTACT_TOL_SECONDS = 0.001;
+/** Bisection alone would need 25 iterations to take the window down to the tolerance. */
+const CONTACT_ITER_CAP = 50;
+/** The central line's default spacing, seconds: at most 235 points on a path from 1950 through 2100. */
+const DEFAULT_STEP_SECONDS = 60;
+/** The widest spacing a central line accepts, seconds; the narrowest is 1. */
+const MAX_STEP_SECONDS = 3600;
+/**
+ * UPSTREAM: `MoonShadow`, astronomy.ts ~8481 — the Moon's shadow cone
+ * evaluated at the Earth's center: the lunacentric Earth measured against the
+ * heliocentric Moon. Both vectors are EQJ, and `calcShadow` only ever takes
+ * dot products and norms of them, so the frame cancels.
+ */
+function moonShadow(ut) {
+    const tt = ttDaysFromUt(ut);
+    // Light-travel and aberration corrected Sun.
+    const s = sunGeoVectorEqj(tt);
+    // Geocentric Moon.
+    const m = moonGeoVectorEqj(tt);
+    // Lunacentric Earth.
+    const e = { x: -m.x, y: -m.y, z: -m.z };
+    // Convert geocentric moon to heliocentric Moon.
+    const hm = { x: m.x - s.x, y: m.y - s.y, z: m.z - s.z };
+    return calcShadow(MOON_MEAN_RADIUS_KM, ut, e, hm);
+}
+/** UPSTREAM: `ShadowDistanceSlope`, astronomy.ts ~8535, bound to `MoonShadow`. */
+function moonShadowSlope(ut) {
+    const dt = 1.0 / 86400.0;
+    return (moonShadow(ut + dt).r - moonShadow(ut - dt).r) / dt;
+}
+/**
+ * UPSTREAM: `PeakMoonShadow`, astronomy.ts ~8564 — greatest eclipse: the time
+ * near the new moon when the Moon's shadow axis passes closest to the Earth's
+ * center, i.e. the ascending zero of the axis distance's time derivative.
+ */
+function peakMoonShadow(centerUt) {
+    // Use the same new-moon seed regardless of search direction or window.
+    // Otherwise a ~1 ms root shift can lose/duplicate a peak when a caller
+    // splits a range at a previously returned peak. Only unpruned moons pay
+    // for this second phase search; its start is a fixed whole UT day.
+    const newmoon = searchMoonPhase(0, Math.floor(centerUt) - 1, 4);
+    if (newmoon === null)
+        throw new Error('almanac internal: cannot refine new moon');
+    const ut = search(moonShadowSlope, newmoon - PEAK_WINDOW_DAYS, newmoon + PEAK_WINDOW_DAYS, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'peak moon shadow');
+    if (ut === null)
+        throw new Error('almanac internal: failed to find peak Moon shadow time');
+    return moonShadow(ut);
+}
+function dilatedAxis(shadow) {
+    // We want to calculate the intersection of the shadow axis with the Earth's geoid.
+    // First we must convert EQJ (equator of J2000) coordinates to EQD (equator of date)
+    // coordinates that are perfectly aligned with the Earth's equator at this
+    // moment in time.
+    const tt = ttDaysFromUt(shadow.ut);
+    const vd = gyration(shadow.dir, tt, PrecessDirection.From2000); // shadow-axis vector in equator-of-date coordinates
+    const ed = gyration(shadow.target, tt, PrecessDirection.From2000); // lunacentric Earth in equator-of-date coordinates
+    // Convert all distances from AU to km.
+    // But dilate the z-coordinates so that the Earth becomes a perfect sphere.
+    // Then find the intersection of the vector with the sphere.
+    // See p 184 in Montenbruck & Pfleger's "Astronomy on the Personal Computer", second edition.
+    const v = { x: vd.x * KM_PER_AU, y: vd.y * KM_PER_AU, z: vd.z * (KM_PER_AU / EARTH_FLATTENING) };
+    const e = { x: ed.x * KM_PER_AU, y: ed.y * KM_PER_AU, z: ed.z * (KM_PER_AU / EARTH_FLATTENING) };
+    // Solve the quadratic equation that finds whether and where
+    // the shadow axis intersects with the Earth in the dilated coordinate system.
+    const R = EARTH_EQUATORIAL_RADIUS_KM;
+    const A = v.x * v.x + v.y * v.y + v.z * v.z;
+    const B = -2.0 * (v.x * e.x + v.y * e.y + v.z * e.z);
+    const C = (e.x * e.x + e.y * e.y + e.z * e.z) - R * R;
+    const radic = B * B - 4 * A * C;
+    return { tt, v, e, A, B, radic };
+}
+/**
+ * UPSTREAM: the second half of `GeoidIntersect`, astronomy.ts ~8842 — the
+ * geodetic point at parameter `u` along the dilated axis, and the kind and
+ * covered fraction a person standing there sees.
+ */
+function axisGround(shadow, axis, u) {
+    const { tt, v, e } = axis;
+    // Convert lunacentric dilated coordinates to geocentric coordinates.
+    const px = u * v.x - e.x;
+    const py = u * v.y - e.y;
+    const pz = (u * v.z - e.z) * EARTH_FLATTENING;
+    // Convert cartesian coordinates into geodetic latitude/longitude.
+    const proj = Math.hypot(px, py) * EARTH_FLATTENING_SQUARED;
+    let latitudeDeg;
+    if (proj == 0.0)
+        latitudeDeg = (pz > 0.0) ? +90.0 : -90.0;
+    else
+        latitudeDeg = RAD2DEG * Math.atan(pz / proj);
+    // Adjust longitude for Earth's rotation at the given UT. `siderealDeg`
+    // is upstream's `15 * sidereal_time`, already in degrees.
+    let longitudeDeg = (RAD2DEG * Math.atan2(py, px) - siderealDeg(shadow.ut)) % 360.0;
+    if (longitudeDeg <= -180.0)
+        longitudeDeg += 360.0;
+    else if (longitudeDeg > +180.0)
+        longitudeDeg -= 360.0;
+    // We want to determine whether the observer sees a total eclipse or an annular eclipse.
+    // Put the EQD geocentric coordinates of the observer back into AU, and
+    // rotate them back to the EQJ system.
+    const og = gyration({ x: px / KM_PER_AU, y: py / KM_PER_AU, z: pz / KM_PER_AU }, tt, PrecessDirection.Into2000);
+    // Convert geocentric vector to lunacentric vector.
+    const o = { x: og.x + shadow.target.x, y: og.y + shadow.target.y, z: og.z + shadow.target.z };
+    // Recalculate the shadow using a vector from the Moon's center toward the observer.
+    const surface = calcShadow(MOON_POLAR_RADIUS_KM, shadow.ut, o, shadow.dir);
+    // If we did everything right, the shadow distance should be very close to zero.
+    // That's because we already determined the observer 'o' is on the shadow axis!
+    // Upstream's bound is 1e-9 km; exceeding it is an implementation failure.
+    if (surface.r > 1.0e-9 || surface.r < 0.0)
+        throw new Error(`almanac internal: unexpected shadow distance from geoid intersection = ${surface.r}`);
+    const kind = eclipseKindFromUmbra(surface.k);
+    const obscuration = (kind === 'total') ? 1.0 : solarEclipseObscuration(shadow.dir, o);
+    return { latitudeDeg, longitudeDeg, kind, obscuration };
+}
+/**
+ * UPSTREAM: `GeoidIntersect`'s choice of root — where the axis first meets
+ * the geoid on its way from the Moon, on the day side of the Earth, or null
+ * when it misses. Upstream only asks at a new moon's greatest eclipse. At an
+ * arbitrary instant the line through the Sun and Moon can also cross the
+ * Earth on the Sun's side of the Moon, near a full moon, where the Moon casts
+ * no shadow on it: both roots are then negative.
+ */
+function nearAxisGround(shadow) {
+    const axis = dilatedAxis(shadow);
+    if (!(axis.radic > 0.0))
+        return null;
+    // Calculate the closer of the two intersection points.
+    // This will be on the day side of the Earth.
+    const u = (-axis.B - Math.sqrt(axis.radic)) / (2 * axis.A);
+    if (!(u > 0.0))
+        return null;
+    return axisGround(shadow, axis, u);
+}
+/**
+ * Where the axis grazes the geoid at a ground contact: its closest approach to
+ * the geoid's center, which moves smoothly through the contact while the
+ * crossing itself races along the horizon.
+ */
+function grazingGround(shadow) {
+    const axis = dilatedAxis(shadow);
+    return axisGround(shadow, axis, -axis.B / (2 * axis.A));
+}
+/**
+ * UPSTREAM: `GeoidIntersect`, astronomy.ts ~8842 — where the shadow axis at
+ * greatest eclipse meets the Earth's oblate geoid, and the kind and covered
+ * fraction a person standing there sees. An axis that misses the geoid is a
+ * partial eclipse with no ground point.
+ */
+function geoidIntersect(shadow, peak) {
+    const ground = nearAxisGround(shadow);
+    if (ground === null) {
+        // This is a partial solar eclipse, and an obscuration needs a place:
+        // `solarEclipses` and `solarObscuration` take an observer.
+        return { kind: 'partial', peak, axisDistanceKm: shadow.r, latitudeDeg: null, longitudeDeg: null, obscuration: null };
+    }
+    return {
+        kind: ground.kind, peak, axisDistanceKm: shadow.r,
+        latitudeDeg: ground.latitudeDeg, longitudeDeg: ground.longitudeDeg, obscuration: ground.obscuration
+    };
+}
+/**
+ * The first solar eclipse anywhere on Earth whose greatest eclipse falls
+ * strictly after `after`.
+ *
+ * Every new moon up to the end of the supported interval is tested: the
+ * Moon's ecliptic latitude prunes the ones no shadow can reach, and the rest
+ * get a peak-shadow search against the Earth's center. A new moon is an
+ * eclipse when the Moon's penumbra reaches the Earth.
+ *
+ * @throws {AlmanacOutOfRangeError} if `after` is outside the supported
+ *      interval, or if no eclipse remains before the end of it.
+ * @throws {RangeError} if `after` is invalid.
+ */
+export function nextGlobalSolarEclipse(after) {
+    return nearestGlobalSolarEclipse(after, 1);
+}
+/**
+ * The last solar eclipse anywhere on Earth whose greatest eclipse falls
+ * strictly before `before`, skipping peaks within 100 ms of it, just as
+ * `nextGlobalSolarEclipse` does on the other side.
+ *
+ * @throws {AlmanacOutOfRangeError} if `before` is outside the supported
+ *      interval, or if no eclipse remains after the start of it.
+ * @throws {RangeError} if `before` is invalid.
+ */
+export function previousGlobalSolarEclipse(before) {
+    return nearestGlobalSolarEclipse(before, -1);
+}
+/** Solar eclipses anywhere on Earth with greatest eclipse in `[startUtc, endUtc)`, sorted ascending. */
+export function globalSolarEclipses(startUtc, endUtc) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    return scanGlobalSolarEclipses(startUtc.getTime(), endUtc.getTime(), 1, false);
+}
+function nearestGlobalSolarEclipse(anchor, direction) {
+    assertSupported(anchor);
+    const ms = anchor.getTime();
+    // No scan limit: walk to the supported boundary, as the local search does.
+    // At least two solar eclipses happen every year, so only the last and
+    // first few months of the interval walk far, and a pruned new moon is cheap.
+    const startMs = direction > 0 ? ms + SAME_ECLIPSE_MS + 1 : SUPPORTED_MIN;
+    const endMs = direction > 0 ? SUPPORTED_MAX : ms - SAME_ECLIPSE_MS;
+    const found = scanGlobalSolarEclipses(startMs, endMs, direction, true);
+    if (found.length)
+        return found[0];
+    throw new AlmanacOutOfRangeError();
+}
+function scanGlobalSolarEclipses(startMs, endMs, direction, firstOnly) {
+    const found = [];
+    if (startMs >= endMs)
+        return found;
+    // Peak and new moon differ by up to the peak window. Include the entire
+    // margin at both ends, then apply the caller's bounds to the reported peak.
+    const startUt = utDays(new Date(startMs)) - PEAK_WINDOW_DAYS;
+    const endUt = utDays(new Date(endMs)) + PEAK_WINDOW_DAYS;
+    let nmUt = direction > 0 ? startUt : endUt;
+    const limitUt = direction > 0 ? endUt : startUt;
+    while (direction * (limitUt - nmUt) > 0) {
+        const newmoon = searchMoonPhase(0, nmUt, direction * Math.min(40, Math.abs(limitUt - nmUt)));
+        if (newmoon === null)
+            break;
+        // UPSTREAM `SearchGlobalSolarEclipse`: step past this new moon before
+        // the next probe, so the same one cannot be found twice.
+        nmUt = newmoon + direction * 10;
+        // Pruning: if the new moon's ecliptic latitude is too large, a solar
+        // eclipse is not possible.
+        if (Math.abs(moonEclipticLatitudeDeg(newmoon)) >= PRUNE_LATITUDE_DEG)
+            continue;
+        // Search near the new moon for the time when the center of the Earth
+        // is closest to the line passing through the centers of the Sun and Moon.
+        const shadow = peakMoonShadow(newmoon);
+        if (shadow.r >= shadow.p + EARTH_MEAN_RADIUS_KM)
+            continue; // the penumbra misses the Earth
+        const peak = dateFromUt(shadow.ut);
+        if (peak.getTime() < startMs || peak.getTime() >= endMs)
+            continue;
+        // This is at least a partial solar eclipse visible somewhere on Earth.
+        // Try to find an intersection between the shadow axis and the Earth's oblate geoid.
+        found.push(geoidIntersect(shadow, peak));
+        if (firstOnly)
+            break;
+    }
+    return found;
+}
+/**
+ * Where the Moon's shadow axis meets the ground at `time`, with the kind and
+ * obscuration a person standing there sees, or `null` when the axis misses
+ * the Earth. This is the point `nextGlobalSolarEclipse` reports at greatest
+ * eclipse, at any instant.
+ *
+ * @throws {AlmanacOutOfRangeError} if `time` is outside the supported interval.
+ * @throws {RangeError} if `time` is invalid.
+ */
+export function solarEclipseAxisPoint(time) {
+    assertSupported(time);
+    const ground = nearAxisGround(moonShadow(utDays(time)));
+    return ground === null ? null : { time: new Date(time.getTime()), ...ground };
+}
+/**
+ * The central line of the solar eclipse in progress at `peak`, normally its
+ * greatest eclipse: the axis point at every whole multiple of `stepSeconds`
+ * between the first and last ground contact, with the points where the axis
+ * grazes the Earth at those two contacts as its ends. Empty when the axis
+ * misses the Earth at `peak`, as it does for a partial eclipse.
+ *
+ * @throws {AlmanacOutOfRangeError} if `peak` is outside the supported interval.
+ * @throws {RangeError} if `peak` is invalid, or `stepSeconds` is not a whole
+ *      number from 1 to 3600.
+ */
+export function solarEclipseCentralLine(peak, stepSeconds = DEFAULT_STEP_SECONDS) {
+    assertSupported(peak);
+    if (!(Number.isInteger(stepSeconds) && stepSeconds >= 1 && stepSeconds <= MAX_STEP_SECONDS))
+        throw new RangeError(`stepSeconds must be a whole number from 1 to ${MAX_STEP_SECONDS}: ${stepSeconds}`);
+    const peakUt = utDays(peak);
+    if (nearAxisGround(moonShadow(peakUt)) === null)
+        return [];
+    const first = dateFromUt(groundContactUt(peakUt, -1));
+    const last = dateFromUt(groundContactUt(peakUt, +1));
+    const point = (time, ground) => ({ time, ...ground });
+    const line = [point(first, grazingGround(moonShadow(utDays(first))))];
+    const stepMs = stepSeconds * 1000;
+    for (let ms = (Math.floor(first.getTime() / stepMs) + 1) * stepMs; ms < last.getTime(); ms += stepMs) {
+        const time = new Date(ms);
+        const ground = nearAxisGround(moonShadow(utDays(time)));
+        // A step within the contacts' millisecond tolerance can fall just outside the path.
+        if (ground !== null)
+            line.push(point(time, ground));
+    }
+    if (last.getTime() > first.getTime())
+        line.push(point(last, grazingGround(moonShadow(utDays(last)))));
+    return line;
+}
+/**
+ * The ground contact before (`direction` −1) or after (+1) `ut`: where the
+ * discriminant of the intersection quadratic crosses zero, so the axis
+ * touches the geoid. Every central path is shorter than the search window.
+ */
+function groundContactUt(ut, direction) {
+    const t1 = direction < 0 ? ut - CONTACT_WINDOW_DAYS : ut;
+    const t2 = direction < 0 ? ut : ut + CONTACT_WINDOW_DAYS;
+    const contact = search(u => -direction * dilatedAxis(moonShadow(u)).radic, t1, t2, CONTACT_TOL_SECONDS, CONTACT_ITER_CAP, 'central line contact');
+    if (contact === null)
+        throw new Error('almanac internal: failed to find a ground contact of the shadow axis');
+    return contact;
+}

package/dist/index.d.ts

@@ -12,3 +12,5 @@ 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';
+export type { GlobalSolarEclipse, SolarEclipseAxisPoint } from './globalSolar.js';
+export { nextGlobalSolarEclipse, previousGlobalSolarEclipse, globalSolarEclipses, solarEclipseAxisPoint, solarEclipseCentralLine } from './globalSolar.js';

package/dist/index.js

@@ -5,3 +5,4 @@ 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';
+export { nextGlobalSolarEclipse, previousGlobalSolarEclipse, globalSolarEclipses, solarEclipseAxisPoint, solarEclipseCentralLine } from './globalSolar.js';

package/dist/solar.d.ts

@@ -1,4 +1,5 @@
 import { Observer } from './types.js';
+import { Vec3 } from './nutation.js';
 /** How much of the Sun an observer sees covered: `partial` when the Moon never covers it, `annular` when the Moon sits inside the Sun's disc, `total` when it covers it. */
 export type SolarEclipseKind = 'partial' | 'annular' | 'total';
 /** The Sun's refracted topocentric altitude at each contact, degrees; `null` exactly where the eclipse has no such contact. */
@@ -27,6 +28,7 @@ export interface SolarEclipse {
     /** The number `sunAltAz` reports at each contact instant, so "above the horizon" agrees with the Sun a consumer draws. */
     sunAltDeg: SolarEclipseSunAltitudes;
 }
+export declare const MOON_POLAR_RADIUS_KM = 1736;
 /**
  * The fraction of the Sun's disc area the Moon covers for `observer` at
  * `time`: 0 when the discs are apart, 1 in totality, the ratio of the disc
@@ -38,6 +40,20 @@ export interface SolarEclipse {
  * @throws {RangeError} if `time` is invalid or `observer` is out of range.
  */
 export declare function solarObscuration(time: Date, observer: Observer): number;
+/**
+ * UPSTREAM: `SolarEclipseObscuration`, astronomy.ts ~8670, with its clamp:
+ * "in marginal cases, we need to clamp obscuration to less than 1.0. This
+ * function is never called for total eclipses, so it should never return 1.0."
+ * INTERNAL: shared with globalSolar.ts.
+ */
+export declare function solarEclipseObscuration(hm: Vec3, lo: Vec3): number;
+/**
+ * UPSTREAM: `EclipseKindFromUmbra`, astronomy.ts ~8834 — a positive umbra
+ * radius at the observer is a total eclipse, otherwise annular. The 14 m
+ * bias is upstream's, added to match Espenak's classifications.
+ * INTERNAL: shared with globalSolar.ts.
+ */
+export declare function eclipseKindFromUmbra(k: number): 'total' | 'annular';
 /**
  * The first solar eclipse `observer` can see whose peak falls strictly after
  * `after`.

package/dist/solar.js

@@ -35,9 +35,10 @@ import { sunGeoVectorEqj } from './sun.js';
 import { observerGeoVectorEqj, refractionDeg, topoAltAzUnrefracted } from './transforms.js';
 import { MOON_MEAN_RADIUS_KM, SUN_RADIUS_KM, search, searchMoonPhase } from './events.js';
 import { calcShadow, moonEclipticLatitudeDeg, PRUNE_LATITUDE_DEG, SAME_ECLIPSE_MS, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP } from './eclipse.js';
-/** UPSTREAM: `SUN_RADIUS_AU` and `MOON_POLAR_RADIUS_AU`, astronomy.ts 135 and 149-150. */
+/** UPSTREAM: `SUN_RADIUS_AU` and `MOON_POLAR_RADIUS_AU`, astronomy.ts 135 and 149-150.
+ *  INTERNAL: `MOON_POLAR_RADIUS_KM` is shared with globalSolar.ts. */
 const SUN_RADIUS_AU = SUN_RADIUS_KM / KM_PER_AU;
-const MOON_POLAR_RADIUS_KM = 1736.0;
+export const MOON_POLAR_RADIUS_KM = 1736.0;
 const MOON_POLAR_RADIUS_AU = MOON_POLAR_RADIUS_KM / KM_PER_AU;
 /** Upstream's `PeakLocalMoonShadow` window, in days, either side of the new moon. */
 const PEAK_WINDOW_DAYS = 0.2;
@@ -154,8 +155,9 @@ export function solarObscuration(time, observer) {
  * UPSTREAM: `SolarEclipseObscuration`, astronomy.ts ~8670, with its clamp:
  * "in marginal cases, we need to clamp obscuration to less than 1.0. This
  * function is never called for total eclipses, so it should never return 1.0."
+ * INTERNAL: shared with globalSolar.ts.
  */
-function solarEclipseObscuration(hm, lo) {
+export function solarEclipseObscuration(hm, lo) {
     return Math.min(0.9999, discObscuration(hm, lo));
 }
 /** UPSTREAM: `ShadowDistanceSlope`, astronomy.ts ~8535, bound to `localMoonShadow`. */
@@ -185,8 +187,9 @@ function peakLocalMoonShadow(centerUt, observer) {
  * UPSTREAM: `EclipseKindFromUmbra`, astronomy.ts ~8834 — a positive umbra
  * radius at the observer is a total eclipse, otherwise annular. The 14 m
  * bias is upstream's, added to match Espenak's classifications.
+ * INTERNAL: shared with globalSolar.ts.
  */
-function eclipseKindFromUmbra(k) {
+export function eclipseKindFromUmbra(k) {
     return (k > 0.014) ? 'total' : 'annular';
 }
 /** UPSTREAM: `local_partial_distance`, astronomy.ts ~9126. */

package/dist/sun.d.ts

@@ -1,4 +1,12 @@
 import { Vec3 } from './nutation.js';
+export type VsopFormula = number[][][];
+type VsopModel = [VsopFormula, VsopFormula, VsopFormula];
+/**
+ * UPSTREAM: `vsop.Earth`, astronomy.ts lines 555-628 (longitude, latitude,
+ * radius). The reference the unrolled `earthLon`/`earthLat`/`earthRad`
+ * below are checked against; exported for that test only.
+ */
+export declare const vsopEarth: VsopModel;
 /**
  * UPSTREAM: `CalcVsop`, astronomy.ts lines 3255-3262, specialised to
  * `vsop.Earth` — i.e. `HelioVector(Body.Earth, time)`. J2000 mean equator (EQJ).
@@ -25,3 +33,4 @@ export declare function sunGeoVectorEqj(tt: number): Vec3;
  * @returns geocentric position in AU, true equator & equinox of date.
  */
 export declare function sunGeoVector(tt: number): Vec3;
+export {};

package/dist/sun.js

@@ -8,8 +8,12 @@
 //
 // INTERNAL: not part of the curated public API (see index.ts).
 import { C_AUDAY, PI2, PrecessDirection, gyration } from './nutation.js';
-/** UPSTREAM: `vsop.Earth`, astronomy.ts lines 555-628 (longitude, latitude, radius). */
-const vsopEarth = [
+/**
+ * UPSTREAM: `vsop.Earth`, astronomy.ts lines 555-628 (longitude, latitude,
+ * radius). The reference the unrolled `earthLon`/`earthLat`/`earthRad`
+ * below are checked against; exported for that test only.
+ */
+export const vsopEarth = [
     [
         [
             [1.75347045673, 0.00000000000, 0.00000000000],
@@ -85,23 +89,118 @@ const vsopEarth = [
 ];
 /** UPSTREAM: astronomy.ts lines 3229-3232. */
 const DAYS_PER_MILLENNIUM = 365250;
-const LON_INDEX = 0;
-const LAT_INDEX = 1;
-const RAD_INDEX = 2;
-/** UPSTREAM: `VsopFormula`, astronomy.ts lines 3191-3205. */
-function vsopFormula(formula, t, clamp_angle) {
+/**
+ * UPSTREAM: `VsopFormula`, astronomy.ts lines 3191-3205, written out term by
+ * term for `vsop.Earth` because the event searches evaluate it tens of
+ * thousands of times. Term order, per-series scaling, clamping and
+ * accumulation match upstream's loop, so the result is bit-for-bit the same;
+ * `test/positions.test.ts` checks that against the table above.
+ */
+function earthLon(t) {
     let tpower = 1;
     let coord = 0;
-    for (let series of formula) {
-        let sum = 0;
-        for (let [ampl, phas, freq] of series)
-            sum += ampl * Math.cos(phas + (t * freq));
-        let incr = tpower * sum;
-        if (clamp_angle)
-            incr %= PI2; // improve precision for longitudes: they can be hundreds of radians
-        coord += incr;
-        tpower *= t;
-    }
+    let sum;
+    let incr;
+    sum = 0;
+    sum += 1.75347045673; // cos(0) is 1 exactly
+    sum += 0.03341656453 * Math.cos(4.66925680415 + (t * 6283.07584999140));
+    sum += 0.00034894275 * Math.cos(4.62610242189 + (t * 12566.15169998280));
+    sum += 0.00003417572 * Math.cos(2.82886579754 + (t * 3.52311834900));
+    sum += 0.00003497056 * Math.cos(2.74411783405 + (t * 5753.38488489680));
+    sum += 0.00003135899 * Math.cos(3.62767041756 + (t * 77713.77146812050));
+    sum += 0.00002676218 * Math.cos(4.41808345438 + (t * 7860.41939243920));
+    sum += 0.00002342691 * Math.cos(6.13516214446 + (t * 3930.20969621960));
+    sum += 0.00001273165 * Math.cos(2.03709657878 + (t * 529.69096509460));
+    sum += 0.00001324294 * Math.cos(0.74246341673 + (t * 11506.76976979360));
+    sum += 0.00000901854 * Math.cos(2.04505446477 + (t * 26.29831979980));
+    sum += 0.00001199167 * Math.cos(1.10962946234 + (t * 1577.34354244780));
+    sum += 0.00000857223 * Math.cos(3.50849152283 + (t * 398.14900340820));
+    sum += 0.00000779786 * Math.cos(1.17882681962 + (t * 5223.69391980220));
+    sum += 0.00000990250 * Math.cos(5.23268072088 + (t * 5884.92684658320));
+    sum += 0.00000753141 * Math.cos(2.53339052847 + (t * 5507.55323866740));
+    sum += 0.00000505267 * Math.cos(4.58292599973 + (t * 18849.22754997420));
+    sum += 0.00000492392 * Math.cos(4.20505711826 + (t * 775.52261132400));
+    sum += 0.00000356672 * Math.cos(2.91954114478 + (t * 0.06731030280));
+    sum += 0.00000284125 * Math.cos(1.89869240932 + (t * 796.29800681640));
+    sum += 0.00000242879 * Math.cos(0.34481445893 + (t * 5486.77784317500));
+    sum += 0.00000317087 * Math.cos(5.84901948512 + (t * 11790.62908865880));
+    sum += 0.00000271112 * Math.cos(0.31486255375 + (t * 10977.07880469900));
+    sum += 0.00000206217 * Math.cos(4.80646631478 + (t * 2544.31441988340));
+    sum += 0.00000205478 * Math.cos(1.86953770281 + (t * 5573.14280143310));
+    sum += 0.00000202318 * Math.cos(2.45767790232 + (t * 6069.77675455340));
+    sum += 0.00000126225 * Math.cos(1.08295459501 + (t * 20.77539549240));
+    sum += 0.00000155516 * Math.cos(0.83306084617 + (t * 213.29909543800));
+    incr = tpower * sum;
+    incr %= PI2;
+    coord += incr;
+    tpower *= t;
+    sum = 0;
+    sum += 6283.07584999140; // cos(0) is 1 exactly
+    sum += 0.00206058863 * Math.cos(2.67823455808 + (t * 6283.07584999140));
+    sum += 0.00004303419 * Math.cos(2.63512233481 + (t * 12566.15169998280));
+    incr = tpower * sum;
+    incr %= PI2;
+    coord += incr;
+    tpower *= t;
+    sum = 0;
+    sum += 0.00008721859 * Math.cos(1.07253635559 + (t * 6283.07584999140));
+    incr = tpower * sum;
+    incr %= PI2;
+    coord += incr;
+    tpower *= t;
+    return coord;
+}
+function earthLat(t) {
+    let tpower = 1;
+    let coord = 0;
+    let sum;
+    let incr;
+    sum = 0;
+    incr = tpower * sum;
+    coord += incr;
+    tpower *= t;
+    sum = 0;
+    sum += 0.00227777722 * Math.cos(3.41376620530 + (t * 6283.07584999140));
+    sum += 0.00003805678 * Math.cos(3.37063423795 + (t * 12566.15169998280));
+    incr = tpower * sum;
+    coord += incr;
+    tpower *= t;
+    return coord;
+}
+function earthRad(t) {
+    let tpower = 1;
+    let coord = 0;
+    let sum;
+    let incr;
+    sum = 0;
+    sum += 1.00013988784; // cos(0) is 1 exactly
+    sum += 0.01670699632 * Math.cos(3.09846350258 + (t * 6283.07584999140));
+    sum += 0.00013956024 * Math.cos(3.05524609456 + (t * 12566.15169998280));
+    sum += 0.00003083720 * Math.cos(5.19846674381 + (t * 77713.77146812050));
+    sum += 0.00001628463 * Math.cos(1.17387558054 + (t * 5753.38488489680));
+    sum += 0.00001575572 * Math.cos(2.84685214877 + (t * 7860.41939243920));
+    sum += 0.00000924799 * Math.cos(5.45292236722 + (t * 11506.76976979360));
+    sum += 0.00000542439 * Math.cos(4.56409151453 + (t * 3930.20969621960));
+    sum += 0.00000472110 * Math.cos(3.66100022149 + (t * 5884.92684658320));
+    sum += 0.00000085831 * Math.cos(1.27079125277 + (t * 161000.68573767410));
+    sum += 0.00000057056 * Math.cos(2.01374292245 + (t * 83996.84731811189));
+    sum += 0.00000055736 * Math.cos(5.24159799170 + (t * 71430.69561812909));
+    sum += 0.00000174844 * Math.cos(3.01193636733 + (t * 18849.22754997420));
+    sum += 0.00000243181 * Math.cos(4.27349530790 + (t * 11790.62908865880));
+    incr = tpower * sum;
+    coord += incr;
+    tpower *= t;
+    sum = 0;
+    sum += 0.00103018607 * Math.cos(1.10748968172 + (t * 6283.07584999140));
+    sum += 0.00001721238 * Math.cos(1.06442300386 + (t * 12566.15169998280));
+    incr = tpower * sum;
+    coord += incr;
+    tpower *= t;
+    sum = 0;
+    sum += 0.00004359385 * Math.cos(5.78455133808 + (t * 6283.07584999140));
+    incr = tpower * sum;
+    coord += incr;
+    tpower *= t;
     return coord;
 }
 /** UPSTREAM: `VsopRotate`, astronomy.ts lines 3234-3241 — VSOP ecliptic to J2000 equatorial. */
@@ -130,9 +229,9 @@ function vsopSphereToRect(lon, lat, radius) {
  */
 export function earthHelioVector(tt) {
     const t = tt / DAYS_PER_MILLENNIUM; // millennia since 2000
-    const lon = vsopFormula(vsopEarth[LON_INDEX], t, true);
-    const lat = vsopFormula(vsopEarth[LAT_INDEX], t, false);
-    const rad = vsopFormula(vsopEarth[RAD_INDEX], t, false);
+    const lon = earthLon(t);
+    const lat = earthLat(t);
+    const rad = earthRad(t);
     const eclip = vsopSphereToRect(lon, lat, rad);
     return vsopRotate(eclip);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Offline sun & moon engine: positions, rise/set, moon phase, lunar and solar eclipses.",
   "license": "MIT",
   "repository": {