@openwaters/almanac 0.8.0 → 0.9.0

package/README.md

@@ -1,12 +1,13 @@
 # Almanac
 
-Offline sky engine for the Salish Sea and everywhere else: Sun, Moon, and planet positions, apparent horizon dip, rise, set, twilight, any Sun altitude, upper and lower transits, Moon phase and orientation, planetary brightness, lunar and solar eclipses, 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, Moon, and planet positions, apparent horizon dip, rise, set, twilight, any Sun altitude, upper and lower transits, Moon phase and orientation, equinoxes and solstices, lunar perigee and apogee, the equation of time, planetary brightness, lunar and solar eclipses, 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:
+Three implementations, one behavior:
 
 - `swift/` — SwiftPM package `Almanac`
 - `typescript/` — npm `@openwaters/almanac`
-- `fixtures/` — the shared test corpus (JPL Horizons, USNO, Espenak) both suites
+- `kotlin/` — Kotlin/JVM `io.openwaters.almanac`, source-consumed with Gradle
+- `fixtures/` — the shared test corpus (JPL Horizons, USNO, Espenak) all three 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, 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.
@@ -21,7 +22,7 @@ Algorithms translated from [Astronomy Engine](https://github.com/cosinekitty/ast
 
 ## Performance
 
-Almanac includes a shared performance harness for both ports: **34 workloads**
+Almanac includes a shared performance harness for TypeScript and Swift: **34 workloads**
 cover positions, a 228-hour sky track, short/year/polar event windows, full-range
 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
@@ -66,9 +67,40 @@ background task; use shorter windows for interactive queries.
 
 ## Usage
 
-Migrating from SunCalc: [`docs/migrating-from-suncalc.md`](docs/migrating-from-suncalc.md) maps every SunCalc call to Almanac and gives drop-in `getTimes` and `getMoonTimes` adapters. Migrating from Solar: [`docs/migrating-from-solar.md`](docs/migrating-from-solar.md). How Almanac compares with SunCalc, Astronomy Engine, astronomia, Solar, SwiftAA, and EDSunriseSet, and when each is the better choice: [`docs/comparison.md`](docs/comparison.md).
+Migration guides for [SunCalc](docs/migrating-from-suncalc.md), [Astronomy Engine](docs/migrating-from-astronomy-engine.md), and [Solar](docs/migrating-from-solar.md) include tested examples. The [library comparison](docs/comparison.md) explains the features and limits of each library.
 
-Migrating from the Solar Swift library: [`docs/migrating-from-solar.md`](docs/migrating-from-solar.md) maps every Solar property to Almanac and gives a drop-in `Solar` adapter.
+Angles use degrees. All three ports provide `degreesToRadians(angle)` and `radiansToDegrees(angle)` for callers that use radians. These functions preserve sign and full turns without wrapping or changing the angle's origin; non-finite inputs and conversion overflow raise validation errors. Swift calls use `try`.
+
+For an instantaneous day/night decision, `sunIsUp(time, observer, heightAboveGroundM = 0)` uses the same upper-limb convention as sunrise and sunset, including polar periods. See the [day/night recipe](docs/cookbook.md).
+
+### JavaScript module loading
+
+The npm package is ESM and has no separate CommonJS build. Use Node 22.12 or later for the Node examples; CI and release checks load the packed package on Node 22.12 and Node 24. Browser applications can import it through their ESM bundler.
+
+In an ES module (`.mjs` or a package with `"type": "module"`):
+
+```js
+import { sunAltAz } from '@openwaters/almanac';
+const observer = { latitudeDeg: 48.5, longitudeDeg: -123.0 };
+console.log(sunAltAz(new Date(), observer));
+```
+
+A CommonJS application can keep synchronous initialization. [Node's `require(esm)` support](https://nodejs.org/docs/latest-v22.x/api/modules.html#loading-ecmascript-modules-using-require) is enabled without a flag from Node 22.12:
+
+```js
+const { sunAltAz } = require('@openwaters/almanac');
+const observer = { latitudeDeg: 48.5, longitudeDeg: -123.0 };
+console.log(sunAltAz(new Date(), observer));
+```
+
+CommonJS can also load ESM asynchronously if its initialization flow already supports it:
+
+```js
+async function initializeSky() {
+  const { sunAltAz } = await import('@openwaters/almanac');
+  return sunAltAz(new Date(), { latitudeDeg: 48.5, longitudeDeg: -123.0 });
+}
+```
 
 ### TypeScript
 
@@ -78,7 +110,8 @@ npm install @openwaters/almanac
 
 ```ts
 import {
-  nextLunarEclipse, lunarEclipseVisibility, nextSolarEclipse, solarObscuration, nextGlobalSolarEclipse, sunEvents, starAltAz
+  nextLunarEclipse, lunarEclipseVisibility, nextSolarEclipse, solarObscuration, nextGlobalSolarEclipse, sunEvents, starAltAz,
+  seasons, moonApsides, equationOfTime
 } from '@openwaters/almanac';
 
 const observer = { latitudeDeg: 48.5, longitudeDeg: -123.0 };
@@ -102,6 +135,13 @@ for (const { kind, time } of sunEvents(today, tomorrow, observer)) {
 
 // Betelgeuse from its J2000 catalog position: az/alt in degrees, refracted.
 const { azDeg, altDeg } = starAltAz(88.792939, 7.407064, today, observer);
+
+// The year's equinoxes and solstices, the Moon's perigees and apogees with
+// distances, and the equation of time in minutes.
+const year = new Date(today.getUTCFullYear() + 1, 0, 1);
+for (const { kind, time } of seasons(today, year)) console.log(kind, time.toISOString());
+for (const { kind, time, distanceKm } of moonApsides(today, year)) console.log(kind, time.toISOString(), distanceKm);
+console.log(equationOfTime(today));   // sundial minus clock, minutes
 ```
 
 For an unobstructed sea horizon, supply eye height above the water separately from elevation above sea level. Body altitudes remain measured from the horizontal plane:
@@ -149,6 +189,31 @@ for event in try sunEvents(from: today, to: tomorrow, observer: observer) {
 
 // Betelgeuse from its J2000 catalog position: az/alt in degrees, refracted.
 let star = try starAltAz(raDeg: 88.792939, decDeg: 7.407064, at: today, observer: observer)
+
+// The year's equinoxes and solstices, the Moon's perigees and apogees with
+// distances, and the equation of time in minutes.
+let year = today.addingTimeInterval(366 * 24 * 60 * 60)
+for event in try seasons(from: today, to: year) { print(event.kind, event.time) }
+for apsis in try moonApsides(from: today, to: year) { print(apsis.kind, apsis.time, apsis.distanceKm) }
+print(try equationOfTime(today))   // sundial minus clock, minutes
+```
+
+### Kotlin/JVM and Android
+
+The Kotlin library provides the same 38 functions and result fields, using `java.time.Instant` and immutable data classes. It targets JVM 8 and Android minSdk 26, builds with JDK 17, and has no runtime dependencies beyond the Kotlin standard library and platform APIs. Maven publication and a Kotlin benchmark runner are deferred; consume the source at a reviewed Git SHA as described in [`kotlin/README.md`](kotlin/README.md).
+
+```kotlin
+import io.openwaters.almanac.*
+import java.time.Instant
+
+val observer = Observer(48.5, -123.0)
+val today = Instant.now()
+val tomorrow = today.plusSeconds(86400)
+val events = sunEvents(today, tomorrow, observer)
+val moon = moonIllumination(today)
+val next = nextGlobalSolarEclipse(today)
+val line = solarEclipseCentralLine(next.peak)
+val minutes = equationOfTime(today)
 ```
 
 ### Golden hour, transits, and the Moon's tilt

package/dist/angles.d.ts

@@ -0,0 +1,4 @@
+/** Converts degrees to radians without wrapping the angle. */
+export declare function degreesToRadians(degrees: number): number;
+/** Converts radians to degrees without wrapping; rejects conversion overflow. */
+export declare function radiansToDegrees(radians: number): number;

package/dist/angles.js

@@ -0,0 +1,16 @@
+import { DEG2RAD, RAD2DEG } from './nutation.js';
+/** Converts degrees to radians without wrapping the angle. */
+export function degreesToRadians(degrees) {
+    if (!Number.isFinite(degrees))
+        throw new RangeError('degrees must be finite');
+    return degrees * DEG2RAD;
+}
+/** Converts radians to degrees without wrapping; rejects conversion overflow. */
+export function radiansToDegrees(radians) {
+    if (!Number.isFinite(radians))
+        throw new RangeError('radians must be finite');
+    const degrees = radians * RAD2DEG;
+    if (!Number.isFinite(degrees))
+        throw new RangeError('angle conversion overflow');
+    return degrees;
+}

package/dist/apsides.d.ts

@@ -0,0 +1,14 @@
+/** Closest approach or farthest remove of the Moon from the Earth's centre. */
+export type MoonApsisKind = 'perigee' | 'apogee';
+/** A lunar perigee or apogee, with the Earth–Moon centre distance there. */
+export interface MoonApsis {
+    time: Date;
+    kind: MoonApsisKind;
+    distanceKm: number;
+}
+/**
+ * The Moon's perigees and apogees within the half-open window
+ * `[startUtc, endUtc)`, sorted ascending, each with the geocentric distance
+ * at that instant.
+ */
+export declare function moonApsides(startUtc: Date, endUtc: Date): MoonApsis[];

package/dist/apsides.js

@@ -0,0 +1,88 @@
+// L3 lunar apsides: perigee and apogee, the zeros of the Moon's radial
+// velocity, from the MOON2 distance the position layer already evaluates.
+//
+// Translated from the cosinekitty/astronomy upstream, pinned sha
+// 865d3da7d8112bbc7911238052c6af4aaf877181, source/js/astronomy.ts:
+// `SearchLunarApsis` (~6534) — its central-difference `distance_slope`, its
+// five-day scan, its sign-change classification, and the `Search` it hands
+// each bracket to. Upstream scans forward from the caller's instant and
+// `NextLunarApsis` (~6621) chains from the last result; here the five-day scan
+// points are a fixed grid anchored at J2000, so every window that contains an
+// apsis finds it from the same bracket and reports the same millisecond — the
+// fixed-seed rule the eclipse searches follow. Apsides are at least 11.8 days
+// apart, so a cell holds at most one.
+//
+// INTERNAL except `moonApsides`: not part of the curated public API (see index.ts).
+import { assertSupported, assertSupportedWindowEnd } from './types.js';
+import { utDays, ttDaysFromUt, dateFromUt } from './time.js';
+import { KM_PER_AU } from './nutation.js';
+import { calcMoon } from './moon.js';
+import { search, quantizedUt, assertReached } from './events.js';
+/** UPSTREAM: the central-difference half-width `dt` inside `SearchLunarApsis`. */
+const SLOPE_DT_DAYS = 0.001;
+/** UPSTREAM: `increment` — the scan step, here also the grid cell in days since J2000 UT. */
+const APSIS_CELL_DAYS = 5;
+/** UPSTREAM: `distance_slope` — dr/dt in AU per day, by central difference. */
+function distanceSlope(ut) {
+    const tt = ttDaysFromUt(ut);
+    const r1 = calcMoon(tt - SLOPE_DT_DAYS / 2).distanceAu;
+    const r2 = calcMoon(tt + SLOPE_DT_DAYS / 2).distanceAu;
+    return (r2 - r1) / SLOPE_DT_DAYS;
+}
+function negativeDistanceSlope(ut) {
+    return -distanceSlope(ut);
+}
+/**
+ * UPSTREAM: the body of `SearchLunarApsis`'s scan loop for one cell `[t1, t2]`
+ * with the slopes `m1`, `m2` at its ends. A slope rising through zero is a
+ * perigee and falling through zero an apogee. A zero exactly at a grid point
+ * belongs to the cell it ends, so no apsis is reported twice.
+ */
+function searchApsisInCell(t1, t2, m1, m2) {
+    if (m1 < 0 && m2 >= 0) {
+        const ut = search(distanceSlope, t1, t2, 1, undefined, 'perigee search');
+        assertReached(ut !== null, 'perigee search');
+        return { ut: ut, kind: 'perigee' };
+    }
+    if (m1 > 0 && m2 <= 0) {
+        const ut = search(negativeDistanceSlope, t1, t2, 1, undefined, 'apogee search');
+        assertReached(ut !== null, 'apogee search');
+        return { ut: ut, kind: 'apogee' };
+    }
+    return null;
+}
+/**
+ * The Moon's perigees and apogees within the half-open window
+ * `[startUtc, endUtc)`, sorted ascending, each with the geocentric distance
+ * at that instant.
+ */
+export function moonApsides(startUtc, endUtc) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    const startUt = utDays(startUtc);
+    const endUt = utDays(endUtc);
+    const events = [];
+    let t1 = Math.floor(startUt / APSIS_CELL_DAYS) * APSIS_CELL_DAYS;
+    let m1 = distanceSlope(t1);
+    while (t1 < endUt) {
+        const t2 = t1 + APSIS_CELL_DAYS;
+        const m2 = distanceSlope(t2);
+        const found = searchApsisInCell(t1, t2, m1, m2);
+        if (found !== null) {
+            const q = quantizedUt(found.ut); // judge the half-open bounds on the reported instant, not the raw root
+            if (q >= endUt)
+                break;
+            if (q >= startUt) {
+                events.push({
+                    time: dateFromUt(found.ut), kind: found.kind,
+                    distanceKm: calcMoon(ttDaysFromUt(found.ut)).distanceAu * KM_PER_AU
+                });
+            }
+        }
+        t1 = t2;
+        m1 = m2;
+    }
+    return events;
+}

package/dist/events.d.ts

@@ -43,6 +43,16 @@ export interface MoonPhaseEvent {
 export declare const MOON_MEAN_RADIUS_KM = 1737.4;
 /** UPSTREAM: `SUN_RADIUS_KM`, astronomy.ts line 134. INTERNAL, see above. */
 export declare const SUN_RADIUS_KM = 695700;
+/**
+ * Clamps a probe into the supported interval. The altitude-search chain
+ * (searchAltitudeEvents) applies this to every probe it samples, so it never
+ * evaluates the model outside [MIN_UT, MAX_UT]. The phase-search walk
+ * (searchMoonPhases) only clamps its first probe — later quarter-to-quarter
+ * probes can land past MAX_UT and evaluate the model there harmlessly; it is
+ * the half-open window filter on emitted results, not this clamp, that keeps
+ * reported answers inside the interval.
+ */
+export declare function clampUt(ut: number): number;
 /**
  * Truncates a ut-days root to the same integer-ms precision `dateFromUt`
  * reports it at (TimeClip). A root finder's raw `ut` carries sub-ms
@@ -55,6 +65,12 @@ export declare const SUN_RADIUS_KM = 695700;
  * no other module consumes it.
  */
 export declare function quantizedUt(ut: number): number;
+/** Hitting an iteration cap is a bug, not a runtime condition — see the spec. */
+export declare function assertReached(condition: boolean, what: string): void;
+/** Wrap a hour-angle difference into (−180, 180]. */
+export declare function angleOffset(diff: number): number;
+/** Whether the Sun's upper limb is above the modeled horizon, using the sunrise/set convention. */
+export declare function sunIsUp(time: Date, observer: Observer, heightAboveGroundM?: number): boolean;
 /**
  * Sun rise, set, the three twilights and upper transit within the half-open
  * window `[startUtc, endUtc)`, sorted ascending.
@@ -97,6 +113,13 @@ export declare function sunTransits(startUtc: Date, endUtc: Date, observer: Obse
  * parallax is included, whether or not the Moon is above the horizon.
  */
 export declare function moonTransits(startUtc: Date, endUtc: Date, observer: Observer): TransitEvent[];
+/**
+ * UPSTREAM: `MEAN_SYNODIC_MONTH`, astronomy.ts line 129. The elongation it
+ * searches is {@link moonPhaseDeg}, apparent on both sides per the spec's
+ * moon-phase definition — upstream's `PairLongitude` uses geometric longitudes,
+ * which sit a flat ~40 s off the USNO catalogue.
+ */
+export declare const MEAN_SYNODIC_MONTH = 29.530588;
 /**
  * UPSTREAM: `Search`, astronomy.ts ~4634 — bisection with quadratic
  * acceleration for the ascending zero crossing of `f` in `[t1, t2]`. Times are

package/dist/events.js

@@ -94,7 +94,7 @@ const MAX_UT = utDays(new Date(SUPPORTED_MAX));
  * the half-open window filter on emitted results, not this clamp, that keeps
  * reported answers inside the interval.
  */
-function clampUt(ut) {
+export function clampUt(ut) {
     return ut < MIN_UT ? MIN_UT : (ut > MAX_UT ? MAX_UT : ut);
 }
 /**
@@ -112,7 +112,7 @@ export function quantizedUt(ut) {
     return utDays(dateFromUt(ut));
 }
 /** Hitting an iteration cap is a bug, not a runtime condition — see the spec. */
-function assertReached(condition, what) {
+export function assertReached(condition, what) {
     if (!condition)
         throw new Error(`almanac internal: ${what} did not converge`);
 }
@@ -150,7 +150,7 @@ function crossingSign(s, level) {
 }
 // ----------------------------------------------------------- root findings
 /** Wrap a hour-angle difference into (−180, 180]. */
-function angleOffset(diff) {
+export function angleOffset(diff) {
     let offset = diff % 360;
     if (offset <= -180)
         offset += 360;
@@ -478,6 +478,13 @@ const MOON_LEVELS = [
 function flatCycle(observer) {
     return Math.abs(observer.latitudeDeg) >= FLAT_CYCLE_LATITUDE_DEG;
 }
+/** Whether the Sun's upper limb is above the modeled horizon, using the sunrise/set convention. */
+export function sunIsUp(time, observer, heightAboveGroundM = 0) {
+    assertSupported(time);
+    const dip = horizonDip(observer, heightAboveGroundM);
+    const sample = sunSampler(observer, dip)(utDays(time));
+    return sample.altDeg > sample.riseSetAltDeg;
+}
 /**
  * Sun rise, set, the three twilights and upper transit within the half-open
  * window `[startUtc, endUtc)`, sorted ascending.
@@ -574,7 +581,7 @@ export function moonTransits(startUtc, endUtc, observer) {
  * moon-phase definition — upstream's `PairLongitude` uses geometric longitudes,
  * which sit a flat ~40 s off the USNO catalogue.
  */
-const MEAN_SYNODIC_MONTH = 29.530588;
+export const MEAN_SYNODIC_MONTH = 29.530588;
 const PHASE_NAMES = ['new', 'firstQuarter', 'full', 'lastQuarter'];
 /** UPSTREAM: `QuadInterp`, astronomy.ts ~4528. */
 function quadInterp(tm, dt, fa, fm, fb) {

package/dist/illumination.d.ts

@@ -9,6 +9,12 @@ export interface MoonIllumination {
 }
 /** UPSTREAM: `AngleBetween`, astronomy.ts lines 256-273 — angle between two vectors, [0, 180]. */
 export declare function angleBetweenDeg(a: Vec3, b: Vec3): number;
+/**
+ * INTERNAL: the Sun's apparent geocentric ecliptic longitude of date, [0, 360)
+ * — upstream `SunPosition(t).elon` (astronomy.ts ~2738), which `seasons.ts`
+ * roots against 0/90/180/270. Aberration is in the vector, nutation in the frame.
+ */
+export declare function sunEclipticLonDeg(tt: number): number;
 /**
  * INTERNAL: the Moon's apparent ecliptic longitude ahead of the Sun's, [0, 360)
  * — 0 at new moon, 180 at full. The single definition of lunar phase in this

package/dist/illumination.js

@@ -44,6 +44,14 @@ function eclipticLonOfDateDeg(eqj, tt) {
         elon += 360;
     return elon;
 }
+/**
+ * INTERNAL: the Sun's apparent geocentric ecliptic longitude of date, [0, 360)
+ * — upstream `SunPosition(t).elon` (astronomy.ts ~2738), which `seasons.ts`
+ * roots against 0/90/180/270. Aberration is in the vector, nutation in the frame.
+ */
+export function sunEclipticLonDeg(tt) {
+    return eclipticLonOfDateDeg(sunGeoVectorEqj(tt), tt);
+}
 /** UPSTREAM: `NormalizeLongitude`, astronomy.ts lines 4735-4739. */
 function normalizeLongitude(lon) {
     return ((lon % 360) + 360) % 360;

package/dist/index.d.ts

@@ -1,16 +1,21 @@
+export { degreesToRadians, radiansToDegrees } from './angles.js';
 export type { Observer, Planet } from './types.js';
 export type { HeliocentricPosition, PlanetPosition, PlanetIllumination } from './planets.js';
 export { planetHeliocentricPosition, planetPosition, planetAltAz, planetIllumination } from './planets.js';
 export { horizonDip } from './horizon.js';
 export { AlmanacOutOfRangeError } from './types.js';
 export type { SunPosition, MoonPosition } from './positions.js';
-export { sunPosition, moonPosition } from './positions.js';
+export { sunPosition, moonPosition, equationOfTime } from './positions.js';
+export type { SeasonKind, SeasonEvent } from './seasons.js';
+export { seasons } from './seasons.js';
+export type { MoonApsisKind, MoonApsis } from './apsides.js';
+export { moonApsides } from './apsides.js';
 export type { AltAz } from './transforms.js';
 export { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
 export type { MoonIllumination, MoonOrientation } from './illumination.js';
 export { moonIllumination, moonOrientation } from './illumination.js';
 export type { SunEvent, SunEventKind, MoonEvent, MoonEventKind, MoonPhaseEvent, MoonPhaseName, PlanetEvent, PlanetEventKind, AltitudeEvent, AltitudeEventKind, TransitEvent, TransitEventKind } from './events.js';
-export { sunEvents, moonEvents, searchMoonPhases, planetEvents, sunAltitudeEvents, sunTransits, moonTransits } from './events.js';
+export { sunIsUp, sunEvents, moonEvents, searchMoonPhases, planetEvents, sunAltitudeEvents, sunTransits, moonTransits } 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';

package/dist/index.js

@@ -1,10 +1,14 @@
+// The public contract's API table is the complete export allow-list.
+export { degreesToRadians, radiansToDegrees } from './angles.js';
 export { planetHeliocentricPosition, planetPosition, planetAltAz, planetIllumination } from './planets.js';
 export { horizonDip } from './horizon.js';
 export { AlmanacOutOfRangeError } from './types.js';
-export { sunPosition, moonPosition } from './positions.js';
+export { sunPosition, moonPosition, equationOfTime } from './positions.js';
+export { seasons } from './seasons.js';
+export { moonApsides } from './apsides.js';
 export { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
 export { moonIllumination, moonOrientation } from './illumination.js';
-export { sunEvents, moonEvents, searchMoonPhases, planetEvents, sunAltitudeEvents, sunTransits, moonTransits } from './events.js';
+export { sunIsUp, sunEvents, moonEvents, searchMoonPhases, planetEvents, sunAltitudeEvents, sunTransits, moonTransits } 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/positions.d.ts

@@ -32,3 +32,18 @@ export declare function sunPosition(time: Date): SunPosition;
  * the Earth-Moon centre distance in kilometres.
  */
 export declare function moonPosition(time: Date): MoonPosition;
+/**
+ * INTERNAL: equation of time for a TT instant, in minutes. Not from upstream:
+ * Meeus, *Astronomical Algorithms*, formula 28.1, `E = L0 − 0.0057183° − α +
+ * Δψ cos ε`, with `L0` the Sun's mean longitude from formula 28.2 and `α` the
+ * apparent right ascension `sunApparentAtTT` already computes. The constant
+ * is aberration plus the FK5 correction; `Δψ cos ε` moves `L0` from the mean
+ * equinox to the true one `α` is measured from.
+ */
+export declare function equationOfTimeAtTT(tt: number): number;
+/**
+ * Equation of time: apparent solar time minus mean solar time, in minutes.
+ * Positive when a sundial runs ahead of the clock; about +16.4 at the start
+ * of November and −14.2 in mid February.
+ */
+export declare function equationOfTime(time: Date): number;

package/dist/positions.js

@@ -13,7 +13,7 @@
 // parallax subtraction) is zero and drops out.
 import { assertSupported } from './types.js';
 import { ttDays } from './time.js';
-import { KM_PER_AU, equatorialFromVector } from './nutation.js';
+import { DEG2RAD, KM_PER_AU, earthTilt, equatorialFromVector } from './nutation.js';
 import { moonGeoVector } from './moon.js';
 import { sunGeoVector } from './sun.js';
 /**
@@ -50,3 +50,30 @@ export function moonPosition(time) {
     assertSupported(time);
     return moonApparentAtTT(ttDays(time));
 }
+/**
+ * INTERNAL: equation of time for a TT instant, in minutes. Not from upstream:
+ * Meeus, *Astronomical Algorithms*, formula 28.1, `E = L0 − 0.0057183° − α +
+ * Δψ cos ε`, with `L0` the Sun's mean longitude from formula 28.2 and `α` the
+ * apparent right ascension `sunApparentAtTT` already computes. The constant
+ * is aberration plus the FK5 correction; `Δψ cos ε` moves `L0` from the mean
+ * equinox to the true one `α` is measured from.
+ */
+export function equationOfTimeAtTT(tt) {
+    const tau = tt / 365250;
+    const l0 = 280.4664567 + tau * (360007.6982779 + tau * (0.03032028
+        + tau * (1 / 49931 + tau * (-1 / 15300 + tau * (-1 / 2000000)))));
+    const tilt = earthTilt(tt);
+    const nutationRaDeg = (tilt.dpsi / 3600) * Math.cos(tilt.tobl * DEG2RAD);
+    let e = l0 - 0.0057183 - sunApparentAtTT(tt).raDeg + nutationRaDeg;
+    e = ((e % 360) + 540) % 360 - 180; // (−180, 180]
+    return e * 4; // 360° of right ascension is 1440 minutes
+}
+/**
+ * Equation of time: apparent solar time minus mean solar time, in minutes.
+ * Positive when a sundial runs ahead of the clock; about +16.4 at the start
+ * of November and −14.2 in mid February.
+ */
+export function equationOfTime(time) {
+    assertSupported(time);
+    return equationOfTimeAtTT(ttDays(time));
+}

package/dist/seasons.d.ts

@@ -0,0 +1,17 @@
+/** The season the Sun's longitude starts: 0° March equinox, 90° June solstice, 180° September equinox, 270° December solstice. */
+export type SeasonKind = 'marchEquinox' | 'juneSolstice' | 'septemberEquinox' | 'decemberSolstice';
+/** An equinox or solstice. */
+export interface SeasonEvent {
+    time: Date;
+    kind: SeasonKind;
+}
+/**
+ * The equinoxes and solstices within the half-open window `[startUtc, endUtc)`,
+ * sorted ascending.
+ *
+ * A season starts the instant the Sun's apparent geocentric ecliptic longitude
+ * reaches 0° (March equinox), 90° (June solstice), 180° (September equinox) or
+ * 270° (December solstice). The names are months, not seasons, because the
+ * same instant starts opposite seasons in the two hemispheres.
+ */
+export declare function seasons(startUtc: Date, endUtc: Date): SeasonEvent[];

package/dist/seasons.js

@@ -0,0 +1,73 @@
+// L3 season search: the four instants a year when the Sun's apparent
+// geocentric ecliptic longitude reaches 0°, 90°, 180° and 270°.
+//
+// Translated from the cosinekitty/astronomy upstream, pinned sha
+// 865d3da7d8112bbc7911238052c6af4aaf877181, source/js/astronomy.ts:
+// `SearchSunLongitude` (~4787), whose `sun_offset` and 0.01 s `Search` are
+// kept. Upstream's `Seasons(year)` (~6130) brackets each search from a fixed
+// calendar date. Here the bracket is a cell of a fixed 80-day grid anchored at
+// J2000, so every window that contains a season finds it from the same bracket
+// and reports the same millisecond — the fixed-seed rule the eclipse searches
+// follow. A cell spans under 90° of solar longitude, so it holds at most one
+// quarter crossing.
+//
+// INTERNAL except `seasons`: not part of the curated public API (see index.ts).
+import { assertSupported, assertSupportedWindowEnd } from './types.js';
+import { utDays, ttDaysFromUt, dateFromUt } from './time.js';
+import { sunEclipticLonDeg } from './illumination.js';
+import { search, angleOffset, quantizedUt, assertReached } from './events.js';
+const SEASON_KINDS = ['marchEquinox', 'juneSolstice', 'septemberEquinox', 'decemberSolstice'];
+/** Grid cell, in days since J2000 UT: under the 89-day shortest season, so a cell holds at most one crossing. */
+const SEASON_CELL_DAYS = 80;
+function sunLonDeg(ut) {
+    return sunEclipticLonDeg(ttDaysFromUt(ut));
+}
+/**
+ * UPSTREAM: `SearchSunLongitude` on one grid cell `[t1, t2]`, with
+ * `lon1 = sunLonDeg(t1)` already in hand. Returns the crossing of the next
+ * multiple of 90° after `lon1`, or `null` when the cell ends before it.
+ */
+function searchSeasonInCell(t1, t2, lon1) {
+    const quarter = (Math.floor(lon1 / 90) + 1) % 4;
+    const targetLonDeg = 90 * quarter;
+    const sunOffset = (ut) => angleOffset(sunLonDeg(ut) - targetLonDeg);
+    if (sunOffset(t2) < 0)
+        return null;
+    const ut = search(sunOffset, t1, t2, 0.01, undefined, 'season search');
+    assertReached(ut !== null, 'season search');
+    return { ut: ut, quarter };
+}
+/**
+ * The equinoxes and solstices within the half-open window `[startUtc, endUtc)`,
+ * sorted ascending.
+ *
+ * A season starts the instant the Sun's apparent geocentric ecliptic longitude
+ * reaches 0° (March equinox), 90° (June solstice), 180° (September equinox) or
+ * 270° (December solstice). The names are months, not seasons, because the
+ * same instant starts opposite seasons in the two hemispheres.
+ */
+export function seasons(startUtc, endUtc) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    const startUt = utDays(startUtc);
+    const endUt = utDays(endUtc);
+    const events = [];
+    let t1 = Math.floor(startUt / SEASON_CELL_DAYS) * SEASON_CELL_DAYS;
+    let lon1 = sunLonDeg(t1);
+    while (t1 < endUt) {
+        const t2 = t1 + SEASON_CELL_DAYS;
+        const found = searchSeasonInCell(t1, t2, lon1);
+        if (found !== null) {
+            const q = quantizedUt(found.ut); // judge the half-open bounds on the reported instant, not the raw root
+            if (q >= endUt)
+                break;
+            if (q >= startUt)
+                events.push({ time: dateFromUt(found.ut), kind: SEASON_KINDS[found.quarter] });
+        }
+        t1 = t2;
+        lon1 = sunLonDeg(t1);
+    }
+    return events;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Offline astronomy: Sun, Moon and planet positions, apparent horizon, rise/set, phases and eclipses.",
   "license": "MIT",
   "repository": {