@openwaters/almanac 0.7.0 → 0.8.1

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, Moon phase, 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,11 +22,13 @@ Algorithms translated from [Astronomy Engine](https://github.com/cosinekitty/ast
 
 ## Performance
 
-Almanac includes a shared performance harness for both ports: **30 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
-line of the 2024-04-08 eclipse, five-planet sky tracks, and planetary rise/set.
+line of the 2024-04-08 eclipse, five-planet sky tracks, planetary rise/set, a
+year of golden-hour crossings and Sun and Moon transits, and a 228-hour Moon
+orientation track.
 
 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
@@ -49,10 +52,10 @@ Reproduce the comparison locally from the repository root with mise 2026.9.1 or
 ```bash
 mise install
 mise exec -- npm ci --prefix typescript
-mise exec -- node benchmarks/run.mjs --base v0.4.1 --skip '^(global|planets)/'
+mise exec -- node benchmarks/run.mjs --base v0.4.1 --skip '^(global|planets|suncalc)/'
 ```
 
-The `--skip` pattern leaves out global eclipse and planetary workloads absent from that base. Use `--skip '^(solar|global|planets)/'` when the base predates 0.4.0, which is when the solar eclipse workloads arrived. For a newer base that lacks only planets, use `--skip '^planets/'`.
+The `--skip` pattern leaves out global eclipse, planetary, and SunCalc-parity workloads absent from that base. Use `--skip '^(solar|global|planets|suncalc)/'` when the base predates 0.4.0, which is when the solar eclipse workloads arrived. For a base that lacks only the SunCalc-parity APIs, use `--skip '^suncalc/'`.
 
 CI runs the harness on code changes and fails on **median regressions over 20%**.
 Results include timing tables, raw samples, checksums, and revision/toolchain
@@ -64,6 +67,39 @@ background task; use shorter windows for interactive queries.
 
 ## Usage
 
+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.
+
+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`.
+
+### 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
 
 ```bash
@@ -72,7 +108,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 };
@@ -96,6 +133,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:
@@ -112,7 +156,7 @@ const crossings = sunEvents(today, tomorrow, viewer, eyeHeightM);
 ### Swift
 
 ```swift
-.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.7.0")
+.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.8.0")
 ```
 
 ```swift
@@ -143,18 +187,64 @@ 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 37 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
+
+`sunAltitudeEvents` finds the Sun's center crossing any altitude, with the twilight convention, so `6` gives golden hour and `-6` civil twilight. `sunTransits` and `moonTransits` give each body's highest (`upper`) and lowest (`lower`) meridian crossings. `moonOrientation` turns the Moon's disc: subtracting the parallactic angle from the bright-limb angle gives the bright limb's direction from the zenith.
+
+```ts
+import { sunAltitudeEvents, sunTransits, moonTransits, moonOrientation } from '@openwaters/almanac';
+const golden = sunAltitudeEvents(today, tomorrow, observer, 6);       // 'rising' ends morning golden hour, 'falling' starts the evening one
+const solarMidnight = sunTransits(today, tomorrow, observer).find(e => e.kind === 'lower');
+const moonHighest = moonTransits(today, tomorrow, observer).find(e => e.kind === 'upper');
+const { brightLimbAngleDeg, parallacticAngleDeg } = moonOrientation(today, observer);
+const brightLimbFromZenithDeg = brightLimbAngleDeg - parallacticAngleDeg;
+```
+
+```swift
+let golden = try sunAltitudeEvents(from: today, to: tomorrow, observer: observer, altitudeDeg: 6)
+let solarMidnight = try sunTransits(from: today, to: tomorrow, observer: observer).first { $0.kind == .lower }
+let moonHighest = try moonTransits(from: today, to: tomorrow, observer: observer).first { $0.kind == .upper }
+let orientation = try moonOrientation(at: today, observer: observer)
+let brightLimbFromZenithDeg = orientation.brightLimbAngleDeg - orientation.parallacticAngleDeg
 ```
 
 ### Planetary views
 
-Mercury, Venus, Earth, Mars, Jupiter, and Saturn have geometric Sun-centered positions in AU, in fixed J2000 equatorial coordinates. Place the Sun at `(0, 0, 0)` and orient the scene's camera for the desired view:
+Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune have geometric Sun-centered positions in AU, in fixed J2000 equatorial coordinates. Place the Sun at `(0, 0, 0)` and orient the scene's camera for the desired view:
 
 ```ts
 import { planetHeliocentricPosition, planetAltAz, planetIllumination, planetEvents,
   horizonDip, sunAltAz } from '@openwaters/almanac';
 import type { Planet } from '@openwaters/almanac';
 
-const planets: Planet[] = ['mercury', 'venus', 'earth', 'mars', 'jupiter', 'saturn'];
+const planets: Planet[] = ['mercury', 'venus', 'earth', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune'];
 const now = new Date();
 const positions = planets.map(planet => ({ planet, ...planetHeliocentricPosition(planet, now) }));
 

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

@@ -17,6 +17,18 @@ export interface PlanetEvent {
     time: Date;
     kind: PlanetEventKind;
 }
+/** The Sun's center crossing a caller-chosen altitude, upward or downward. */
+export type AltitudeEventKind = 'rising' | 'falling';
+export interface AltitudeEvent {
+    time: Date;
+    kind: AltitudeEventKind;
+}
+/** A body crossing the local meridian: highest at `upper`, lowest at `lower`. */
+export type TransitEventKind = 'upper' | 'lower';
+export interface TransitEvent {
+    time: Date;
+    kind: TransitEventKind;
+}
 /** A quarter lunar phase. */
 export type MoonPhaseName = 'new' | 'firstQuarter' | 'full' | 'lastQuarter';
 export interface MoonPhaseEvent {
@@ -31,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
@@ -43,6 +65,10 @@ 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;
 /**
  * Sun rise, set, the three twilights and upper transit within the half-open
  * window `[startUtc, endUtc)`, sorted ascending.
@@ -65,6 +91,33 @@ export declare function sunEvents(startUtc: Date, endUtc: Date, observer: Observ
 export declare function moonEvents(startUtc: Date, endUtc: Date, observer: Observer, heightAboveGroundM?: number): MoonEvent[];
 /** Rise/set of a point center at geometric altitude horizonDip minus 34 arcminutes. */
 export declare function planetEvents(planet: Planet, startUtc: Date, endUtc: Date, observer: Observer, heightAboveGroundM?: number): PlanetEvent[];
+/**
+ * The Sun's unrefracted geometric center crossing `altitudeDeg` within the
+ * half-open window `[startUtc, endUtc)`, sorted ascending: `rising` upward,
+ * `falling` downward. The twilight convention, so `-6` returns the civil
+ * twilight instants. A window with no crossing, as in polar day or night,
+ * returns an empty list.
+ */
+export declare function sunAltitudeEvents(startUtc: Date, endUtc: Date, observer: Observer, altitudeDeg: number): AltitudeEvent[];
+/**
+ * The Sun's upper (local hour angle 0) and lower (180°) transits within the
+ * half-open window `[startUtc, endUtc)`, sorted ascending, whether or not the
+ * Sun is above the horizon. The upper transit is `sunEvents`' `transit`.
+ */
+export declare function sunTransits(startUtc: Date, endUtc: Date, observer: Observer): TransitEvent[];
+/**
+ * The Moon's upper and lower transits within the half-open window
+ * `[startUtc, endUtc)`, sorted ascending, from the topocentric hour angle, so
+ * 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

@@ -21,7 +21,7 @@
 // `SearchMoonPhase` (~5260) and the `Search` (~4634) / `QuadInterp` (~4528)
 // root finder it calls, plus the quarter walk of `SearchMoonQuarter` (~5339)
 // and `NextMoonQuarter` (~5362).
-import { assertPlanet, assertSupported, assertSupportedWindowEnd, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
+import { assertObserver, assertPlanet, assertSupported, assertSupportedWindowEnd, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
 import { dateFromUt, ttDaysFromUt, utDays } from './time.js';
 import { DEG2RAD, KM_PER_AU, RAD2DEG } from './nutation.js';
 import { topoAltAzUnrefracted } from './transforms.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;
@@ -412,9 +412,12 @@ function secantCrossing(f, a, b, s0, s1, targetDeg) {
  * solving every monotonic segment between consecutive extrema for every target
  * level. The chain starts a full cycle before `startUt` so the segment
  * 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.
+ * `endUt` so an event just inside the window's end is too. `transitKind` is
+ * emitted at each hour angle 0 and `lowerTransitKind` at each hour angle 180.
+ * With no levels the extrema are never refined: the hour-angle chain alone
+ * places the transits.
  */
-function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRateDegPerDay, cycleDays, flatCycle) {
+function searchAltitudeEvents(sample, levels, transitKind, lowerTransitKind, startUt, endUt, haRateDegPerDay, cycleDays, flatCycle) {
     const extremumHalfWidthDays = flatCycle ? cycleDays / 2 : EXTREMUM_HALF_WIDTH_DAYS;
     const found = [];
     const emit = (ut, kind) => {
@@ -438,7 +441,8 @@ 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, flatCycle);
+            : levels.length === 0 ? sample(nextEst)
+                : 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) {
@@ -450,8 +454,9 @@ function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRat
                 emit(solveCrossing(sample, spec.level, s0, s1), g1 > 0 ? spec.rising : spec.falling);
             }
         }
-        if (nextIsMax && transitKind !== null && !atRangeEnd)
-            emit(nextEst, transitKind);
+        const transit = nextIsMax ? transitKind : lowerTransitKind;
+        if (transit !== null && !atRangeEnd)
+            emit(nextEst, transit);
         s0 = s1;
         if (atRangeEnd)
             break;
@@ -491,7 +496,7 @@ export function sunEvents(startUtc, endUtc, observer, heightAboveGroundM = 0) {
     const dip = horizonDip(observer, heightAboveGroundM);
     if (startUtc.getTime() >= endUtc.getTime())
         return [];
-    return searchAltitudeEvents(sunSampler(observer, dip), SUN_LEVELS, 'transit', utDays(startUtc), utDays(endUtc), SUN_HA_RATE_DEG_PER_DAY, SUN_CYCLE_DAYS, flatCycle(observer));
+    return searchAltitudeEvents(sunSampler(observer, dip), SUN_LEVELS, 'transit', null, 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)`,
@@ -505,7 +510,7 @@ export function moonEvents(startUtc, endUtc, observer, heightAboveGroundM = 0) {
     const dip = horizonDip(observer, heightAboveGroundM);
     if (startUtc.getTime() >= endUtc.getTime())
         return [];
-    return searchAltitudeEvents(moonSampler(observer, dip), MOON_LEVELS, null, utDays(startUtc), utDays(endUtc), MOON_HA_RATE_DEG_PER_DAY, MOON_CYCLE_DAYS, flatCycle(observer));
+    return searchAltitudeEvents(moonSampler(observer, dip), MOON_LEVELS, null, null, utDays(startUtc), utDays(endUtc), MOON_HA_RATE_DEG_PER_DAY, MOON_CYCLE_DAYS, flatCycle(observer));
 }
 /** Rise/set of a point center at geometric altitude horizonDip minus 34 arcminutes. */
 export function planetEvents(planet, startUtc, endUtc, observer, heightAboveGroundM = 0) {
@@ -516,7 +521,51 @@ export function planetEvents(planet, startUtc, endUtc, observer, heightAboveGrou
     if (startUtc.getTime() >= endUtc.getTime())
         return [];
     const cycleDays = 0.9972695717592592;
-    return searchAltitudeEvents(planetSampler(planet, observer, dip), MOON_LEVELS, null, utDays(startUtc), utDays(endUtc), 360 / cycleDays, cycleDays, flatCycle(observer));
+    return searchAltitudeEvents(planetSampler(planet, observer, dip), MOON_LEVELS, null, null, utDays(startUtc), utDays(endUtc), 360 / cycleDays, cycleDays, flatCycle(observer));
+}
+/**
+ * The Sun's unrefracted geometric center crossing `altitudeDeg` within the
+ * half-open window `[startUtc, endUtc)`, sorted ascending: `rising` upward,
+ * `falling` downward. The twilight convention, so `-6` returns the civil
+ * twilight instants. A window with no crossing, as in polar day or night,
+ * returns an empty list.
+ */
+export function sunAltitudeEvents(startUtc, endUtc, observer, altitudeDeg) {
+    if (!(altitudeDeg >= -90 && altitudeDeg <= 90))
+        throw new RangeError(`altitudeDeg out of range: ${altitudeDeg}`);
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    assertObserver(observer);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    const levels = [{ level: altitudeDeg, rising: 'rising', falling: 'falling' }];
+    return searchAltitudeEvents(sunSampler(observer, 0), levels, null, null, utDays(startUtc), utDays(endUtc), SUN_HA_RATE_DEG_PER_DAY, SUN_CYCLE_DAYS, flatCycle(observer));
+}
+/**
+ * The Sun's upper (local hour angle 0) and lower (180°) transits within the
+ * half-open window `[startUtc, endUtc)`, sorted ascending, whether or not the
+ * Sun is above the horizon. The upper transit is `sunEvents`' `transit`.
+ */
+export function sunTransits(startUtc, endUtc, observer) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    assertObserver(observer);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    return searchAltitudeEvents(sunSampler(observer, 0), [], 'upper', 'lower', utDays(startUtc), utDays(endUtc), SUN_HA_RATE_DEG_PER_DAY, SUN_CYCLE_DAYS, flatCycle(observer));
+}
+/**
+ * The Moon's upper and lower transits within the half-open window
+ * `[startUtc, endUtc)`, sorted ascending, from the topocentric hour angle, so
+ * parallax is included, whether or not the Moon is above the horizon.
+ */
+export function moonTransits(startUtc, endUtc, observer) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    assertObserver(observer);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    return searchAltitudeEvents(moonSampler(observer, 0), [], 'upper', 'lower', utDays(startUtc), utDays(endUtc), MOON_HA_RATE_DEG_PER_DAY, MOON_CYCLE_DAYS, flatCycle(observer));
 }
 // -------------------------------------------------------------- moon phases
 /**
@@ -525,7 +574,7 @@ export function planetEvents(planet, startUtc, endUtc, observer, heightAboveGrou
  * 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

@@ -1,3 +1,4 @@
+import { Observer } from './types.js';
 import { Vec3 } from './nutation.js';
 /** Moon illumination at an instant. `phase` is 0 at new moon, 0.5 at full. */
 export interface MoonIllumination {
@@ -8,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
@@ -33,3 +40,21 @@ export declare function moonIlluminationAtTT(tt: number): MoonIllumination;
  * phase (0 = new, 0.5 = full, `waxing` = phase < 0.5).
  */
 export declare function moonIllumination(time: Date): MoonIllumination;
+/**
+ * How the Moon's disc is turned on the observer's sky. `brightLimbAngleDeg` is
+ * the position angle of the bright limb's midpoint from celestial north
+ * through east, in [0, 360); `parallacticAngleDeg` is the angle at the Moon
+ * from celestial north to the observer's zenith, in (-180, 180]. Their
+ * difference is the bright limb's angle from the zenith.
+ */
+export interface MoonOrientation {
+    brightLimbAngleDeg: number;
+    parallacticAngleDeg: number;
+}
+/**
+ * The Moon's orientation at an instant: the bright limb from the apparent
+ * topocentric Moon and the apparent geocentric Sun (Meeus, Astronomical
+ * Algorithms, 48.5), and the parallactic angle from the Moon's topocentric
+ * hour angle and declination at the observer's geodetic latitude (Meeus 14.1).
+ */
+export declare function moonOrientation(time: Date, observer: Observer): MoonOrientation;

package/dist/illumination.js

@@ -8,8 +8,10 @@
 // 865d3da7d8112bbc7911238052c6af4aaf877181, source/js/astronomy.ts.
 //
 // INTERNAL: not part of the curated public API (see index.ts).
-import { assertSupported } from './types.js';
-import { ttDays } from './time.js';
+import { assertObserver, assertSupported } from './types.js';
+import { ttDays, ttDaysFromUt, utDays } from './time.js';
+import { topoAltAzUnrefracted } from './transforms.js';
+import { sunApparentAtTT } from './positions.js';
 import { DEG2RAD, PrecessDirection, RAD2DEG, earthTilt, eclipticToEquatorial, gyration } from './nutation.js';
 import { moonGeoVectorEqj } from './moon.js';
 import { earthHelioVector, sunGeoVectorEqj } from './sun.js';
@@ -42,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;
@@ -89,3 +99,31 @@ export function moonIllumination(time) {
     assertSupported(time);
     return moonIlluminationAtTT(ttDays(time));
 }
+/**
+ * The Moon's orientation at an instant: the bright limb from the apparent
+ * topocentric Moon and the apparent geocentric Sun (Meeus, Astronomical
+ * Algorithms, 48.5), and the parallactic angle from the Moon's topocentric
+ * hour angle and declination at the observer's geodetic latitude (Meeus 14.1).
+ */
+export function moonOrientation(time, observer) {
+    assertSupported(time);
+    assertObserver(observer);
+    const ut = utDays(time);
+    const tt = ttDaysFromUt(ut);
+    const moon = topoAltAzUnrefracted(moonGeoVectorEqj(tt), ut, observer);
+    const sun = sunApparentAtTT(tt);
+    const dec = moon.decDeg * DEG2RAD;
+    const sunDec = sun.decDeg * DEG2RAD;
+    const dRa = (sun.raDeg - moon.raDeg) * DEG2RAD;
+    let brightLimbAngleDeg = RAD2DEG * Math.atan2(Math.cos(sunDec) * Math.sin(dRa), Math.sin(sunDec) * Math.cos(dec) - Math.cos(sunDec) * Math.sin(dec) * Math.cos(dRa));
+    if (brightLimbAngleDeg < 0)
+        brightLimbAngleDeg += 360;
+    if (brightLimbAngleDeg >= 360)
+        brightLimbAngleDeg -= 360;
+    const ha = moon.hourAngleDeg * DEG2RAD;
+    const lat = observer.latitudeDeg * DEG2RAD;
+    let parallacticAngleDeg = RAD2DEG * Math.atan2(Math.sin(ha), Math.tan(lat) * Math.cos(dec) - Math.sin(dec) * Math.cos(ha));
+    if (parallacticAngleDeg <= -180)
+        parallacticAngleDeg += 360;
+    return { brightLimbAngleDeg, parallacticAngleDeg };
+}