@openwaters/almanac 0.5.0 → 0.7.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 anywhere on Earth, 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, 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.
 
 Twin implementations, one behavior:
 
@@ -12,7 +12,7 @@ Twin implementations, one behavior:
 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.
 
 - Contract: [`docs/CONTRACT.md`](docs/CONTRACT.md), including coordinates, public behavior, accuracy, and fixture evidence.
-- Scope: [`docs/ROADMAP.md`](docs/ROADMAP.md), including supported behavior and deliberate boundaries.
+- Scope: [`docs/SCOPE.md`](docs/SCOPE.md), including supported behavior and deliberate boundaries.
 - Development and releases: [`CONTRIBUTING.md`](CONTRIBUTING.md), including pinned tools and required checks.
 - Landing page: [openwaters.io/sky](https://openwaters.io/sky), with the library running live in a browser.
 
@@ -21,11 +21,11 @@ Algorithms translated from [Astronomy Engine](https://github.com/cosinekitty/ast
 
 ## Performance
 
-Almanac includes a shared performance harness for both ports: **27 workloads**
+Almanac includes a shared performance harness for both ports: **30 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.
+line of the 2024-04-08 eclipse, five-planet sky tracks, and planetary rise/set.
 
 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 +49,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/'
+mise exec -- node benchmarks/run.mjs --base v0.4.1 --skip '^(global|planets)/'
 ```
 
-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.
+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/'`.
 
 CI runs the harness on code changes and fails on **median regressions over 20%**.
 Results include timing tables, raw samples, checksums, and revision/toolchain
@@ -98,10 +98,21 @@ for (const { kind, time } of sunEvents(today, tomorrow, observer)) {
 const { azDeg, altDeg } = starAltAz(88.792939, 7.407064, today, observer);
 ```
 
+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:
+
+```ts
+import { horizonDip, sunAltAz } from '@openwaters/almanac';
+const eyeHeightM = 2;
+const viewer = { latitudeDeg: 48.5, longitudeDeg: -123.0, elevationM: 2 };
+const horizonAltDeg = horizonDip(viewer, eyeHeightM);
+const sunAltitudeAboveHorizonDeg = sunAltAz(new Date(), viewer).altDeg - horizonAltDeg;
+const crossings = sunEvents(today, tomorrow, viewer, eyeHeightM);
+```
+
 ### Swift
 
 ```swift
-.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.5.0")
+.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.7.0")
 ```
 
 ```swift
@@ -134,6 +145,44 @@ for event in try sunEvents(from: today, to: tomorrow, observer: observer) {
 let star = try starAltAz(raDeg: 88.792939, decDeg: 7.407064, at: today, observer: observer)
 ```
 
+### 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:
+
+```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 now = new Date();
+const positions = planets.map(planet => ({ planet, ...planetHeliocentricPosition(planet, now) }));
+
+const viewer = { latitudeDeg: 48.5, longitudeDeg: -123.0, elevationM: 2 };
+const horizonAltDeg = horizonDip(viewer, 2);
+const venus = planetAltAz('venus', now, viewer);
+const brightness = planetIllumination('venus', now);
+console.log(venus.azDeg, venus.altDeg - horizonAltDeg, sunAltAz(now, viewer).altDeg,
+  brightness.magnitude, brightness.elongationDeg);
+const crossings = planetEvents('venus', now, new Date(now.getTime() + 86400000), viewer, 2);
+```
+
+```swift
+let now = Date()
+let positions = try Planet.allCases.map { try planetHeliocentricPosition($0, at: now) }
+let viewer = try Observer(latitudeDeg: 48.5, longitudeDeg: -123.0, elevationM: 2)
+let horizon = try horizonDip(observer: viewer, heightAboveGroundM: 2)
+let venus = try planetAltAz(.venus, at: now, observer: viewer)
+let brightness = try planetIllumination(.venus, at: now)
+print(venus.azDeg, venus.altDeg - horizon, brightness.magnitude, brightness.elongationDeg)
+let crossings = try planetEvents(.venus, from: now, to: now.addingTimeInterval(86400),
+  observer: viewer, heightAboveGroundM: 2)
+```
+
+Earth is included for the solar-system view. Earth-based position, altitude/azimuth, illumination, and rise/set reject Earth. Sky coordinates include light-time and apparent corrections; heliocentric scene coordinates do not.
+
+A viewing-window policy can combine planet altitude above the horizon, Sun altitude, elongation, and brightness. Actual visibility also depends on weather and observing conditions. Magnitude is approximate: the pinned model and Horizons differ by up to 0.75 magnitudes for extreme Venus crescents in the fixture interval.
+
 ### Eclipse searches
 
 Search for a previous eclipse or all eclipses in a time window:
@@ -155,7 +204,7 @@ anchor. Search results are global; apply `lunarEclipseVisibility` for an observe
 
 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.
+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, and greatest eclipse falls on the Earth's limb nearest the axis, with the Sun on the horizon: `greatestLatitudeDeg`, `greatestLongitudeDeg`, and `greatestObscuration` give that place for every eclipse.
 
 `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:
 

package/dist/eclipse.d.ts

@@ -127,4 +127,4 @@ export declare function lunarEclipses(startUtc: Date, endUtc: Date): LunarEclips
  *
  * @throws {RangeError} if `eclipse` is structurally invalid or `observer` is out of range.
  */
-export declare function lunarEclipseVisibility(eclipse: LunarEclipse, observer: Observer): LunarEclipseVisibility;
+export declare function lunarEclipseVisibility(eclipse: LunarEclipse, observer: Observer, heightAboveGroundM?: number): LunarEclipseVisibility;

package/dist/eclipse.js

@@ -17,12 +17,13 @@
 //     result.
 //   - upstream reports semi-durations in minutes; the spec's public shape is
 //     the contact instants themselves, and `obscuration` is not in it.
-import { assertObserver, assertSupported, assertSupportedWindowEnd, AlmanacOutOfRangeError, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
+import { assertSupported, assertSupportedWindowEnd, AlmanacOutOfRangeError, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
 import { dateFromUt, ttDaysFromUt, utDays } from './time.js';
 import { KM_PER_AU, RAD2DEG } from './nutation.js';
 import { calcMoon, moonGeoVectorEqj } from './moon.js';
 import { sunGeoVectorEqj } from './sun.js';
 import { topoAltAzUnrefracted } from './transforms.js';
+import { horizonDip } from './horizon.js';
 import { MOON_MEAN_RADIUS_KM, SUN_RADIUS_KM, search, searchMoonPhase } from './events.js';
 /** UPSTREAM: `EARTH_MEAN_RADIUS_KM` + `EARTH_ATMOSPHERE_KM`, astronomy.ts 142-144.
  *  The 88 km of atmosphere is what makes the umbra match observed eclipse
@@ -306,19 +307,19 @@ function assertLunarEclipse(e) {
  *
  * @throws {RangeError} if `eclipse` is structurally invalid or `observer` is out of range.
  */
-export function lunarEclipseVisibility(eclipse, observer) {
+export function lunarEclipseVisibility(eclipse, observer, heightAboveGroundM = 0) {
     assertLunarEclipse(eclipse);
-    assertObserver(observer);
+    const dip = horizonDip(observer, heightAboveGroundM);
     const altAt = (d) => {
         const ut = utDays(d);
         return topoAltAzUnrefracted(moonGeoVectorEqj(ttDaysFromUt(ut)), ut, observer).altDeg;
     };
     // `== null` deliberately: the validator counts `undefined` as absent too,
     // so the reader must, or an `undefined` contact would reach `utDays` raw.
-    const up = (d) => (d == null ? null : altAt(d) > 0);
+    const up = (d) => (d == null ? null : altAt(d) > dip);
     const peakAltDeg = altAt(eclipse.peak);
     return {
-        visibleAtPeak: peakAltDeg > 0,
+        visibleAtPeak: peakAltDeg > dip,
         moonGeometricAltAtPeakDeg: peakAltDeg,
         contactsVisible: {
             p1: up(eclipse.p1),

package/dist/events.d.ts

@@ -1,4 +1,4 @@
-import { Observer } from './types.js';
+import { Observer, type Planet } from './types.js';
 /** A Sun event: a horizon or twilight crossing, or upper transit. */
 export type SunEventKind = 'rise' | 'set' | 'civilDawn' | 'civilDusk' | 'nauticalDawn' | 'nauticalDusk' | 'astroDawn' | 'astroDusk' | 'transit';
 export interface SunEvent {
@@ -11,6 +11,12 @@ export interface MoonEvent {
     time: Date;
     kind: MoonEventKind;
 }
+/** A planet's point center crossing the apparent horizon. */
+export type PlanetEventKind = 'rise' | 'set';
+export interface PlanetEvent {
+    time: Date;
+    kind: PlanetEventKind;
+}
 /** A quarter lunar phase. */
 export type MoonPhaseName = 'new' | 'firstQuarter' | 'full' | 'lastQuarter';
 export interface MoonPhaseEvent {
@@ -41,7 +47,7 @@ export declare function quantizedUt(ut: number): number;
  * Sun rise, set, the three twilights and upper transit within the half-open
  * window `[startUtc, endUtc)`, sorted ascending.
  *
- * Rise and set are the unrefracted geometric centre altitude at −(34′ + the
+ * Rise and set use the supplied horizon dip minus (34′ + the
  * Sun's true semidiameter at distance) — the upper-limb convention with the
  * actual disc, the same rule the Moon gets; the twilights are centre altitude
  * −6°, −12° and −18° with no refraction term; transit is local hour angle
@@ -49,14 +55,16 @@ export declare function quantizedUt(ut: number): number;
  * the crossings — while transit is reported regardless of whether the Sun is
  * above the horizon when it happens.
  */
-export declare function sunEvents(startUtc: Date, endUtc: Date, observer: Observer): SunEvent[];
+export declare function sunEvents(startUtc: Date, endUtc: Date, observer: Observer, heightAboveGroundM?: number): SunEvent[];
 /**
  * Moonrise and moonset within the half-open window `[startUtc, endUtc)`,
  * sorted ascending — the apparent topocentric upper limb crossing the horizon,
  * so refraction (34′), topocentric parallax and the true semidiameter at the
  * Moon's distance are all included — the same upper-limb rule as the Sun's. An empty list is a valid answer.
  */
-export declare function moonEvents(startUtc: Date, endUtc: Date, observer: Observer): MoonEvent[];
+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[];
 /**
  * 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,13 +21,15 @@
 // `SearchMoonPhase` (~5260) and the `Search` (~4634) / `QuadInterp` (~4528)
 // root finder it calls, plus the quarter walk of `SearchMoonQuarter` (~5339)
 // and `NextMoonQuarter` (~5362).
-import { assertObserver, assertSupported, assertSupportedWindowEnd, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
+import { 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';
 import { sunGeoVectorEqj } from './sun.js';
 import { moonGeoVectorEqj } from './moon.js';
 import { moonPhaseDeg } from './illumination.js';
+import { horizonDip } from './horizon.js';
+import { planetGeoVectorEqj } from './planetModels.js';
 // ---------------------------------------------------------------- constants
 const CIVIL_ALT_DEG = -6;
 const NAUTICAL_ALT_DEG = -12;
@@ -114,24 +116,30 @@ function assertReached(condition, what) {
     if (!condition)
         throw new Error(`almanac internal: ${what} did not converge`);
 }
-function sunSampler(observer) {
+function sunSampler(observer, dip) {
     return (ut) => {
         const p = topoAltAzUnrefracted(sunGeoVectorEqj(ttDaysFromUt(ut)), ut, observer);
         return {
             ut, altDeg: p.altDeg, hourAngleDeg: p.hourAngleDeg,
-            riseSetAltDeg: upperLimbTargetDeg(SUN_RADIUS_KM, p.distanceAu)
+            riseSetAltDeg: dip + upperLimbTargetDeg(SUN_RADIUS_KM, p.distanceAu)
         };
     };
 }
-function moonSampler(observer) {
+function moonSampler(observer, dip) {
     return (ut) => {
         const p = topoAltAzUnrefracted(moonGeoVectorEqj(ttDaysFromUt(ut)), ut, observer);
         return {
             ut, altDeg: p.altDeg, hourAngleDeg: p.hourAngleDeg,
-            riseSetAltDeg: upperLimbTargetDeg(MOON_MEAN_RADIUS_KM, p.distanceAu)
+            riseSetAltDeg: dip + upperLimbTargetDeg(MOON_MEAN_RADIUS_KM, p.distanceAu)
         };
     };
 }
+function planetSampler(planet, observer, dip) {
+    return (ut) => {
+        const p = topoAltAzUnrefracted(planetGeoVectorEqj(planet, ttDaysFromUt(ut)), ut, observer);
+        return { ut, altDeg: p.altDeg, hourAngleDeg: p.hourAngleDeg, riseSetAltDeg: dip - HORIZON_REFRACTION_DEG };
+    };
+}
 function offsetDeg(s, level) {
     return s.altDeg - (level === null ? s.riseSetAltDeg : level);
 }
@@ -469,7 +477,7 @@ function flatCycle(observer) {
  * Sun rise, set, the three twilights and upper transit within the half-open
  * window `[startUtc, endUtc)`, sorted ascending.
  *
- * Rise and set are the unrefracted geometric centre altitude at −(34′ + the
+ * Rise and set use the supplied horizon dip minus (34′ + the
  * Sun's true semidiameter at distance) — the upper-limb convention with the
  * actual disc, the same rule the Moon gets; the twilights are centre altitude
  * −6°, −12° and −18° with no refraction term; transit is local hour angle
@@ -477,13 +485,13 @@ function flatCycle(observer) {
  * the crossings — while transit is reported regardless of whether the Sun is
  * above the horizon when it happens.
  */
-export function sunEvents(startUtc, endUtc, observer) {
+export function sunEvents(startUtc, endUtc, observer, heightAboveGroundM = 0) {
     assertSupported(startUtc);
     assertSupportedWindowEnd(endUtc);
-    assertObserver(observer);
+    const dip = horizonDip(observer, heightAboveGroundM);
     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, flatCycle(observer));
+    return searchAltitudeEvents(sunSampler(observer, dip), 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)`,
@@ -491,13 +499,24 @@ export function sunEvents(startUtc, endUtc, observer) {
  * so refraction (34′), topocentric parallax and the true semidiameter at the
  * Moon's distance are all included — the same upper-limb rule as the Sun's. An empty list is a valid answer.
  */
-export function moonEvents(startUtc, endUtc, observer) {
+export function moonEvents(startUtc, endUtc, observer, heightAboveGroundM = 0) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    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));
+}
+/** Rise/set of a point center at geometric altitude horizonDip minus 34 arcminutes. */
+export function planetEvents(planet, startUtc, endUtc, observer, heightAboveGroundM = 0) {
+    assertPlanet(planet);
     assertSupported(startUtc);
     assertSupportedWindowEnd(endUtc);
-    assertObserver(observer);
+    const dip = horizonDip(observer, heightAboveGroundM);
     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, flatCycle(observer));
+    const cycleDays = 0.9972695717592592;
+    return searchAltitudeEvents(planetSampler(planet, observer, dip), MOON_LEVELS, null, utDays(startUtc), utDays(endUtc), 360 / cycleDays, cycleDays, flatCycle(observer));
 }
 // -------------------------------------------------------------- moon phases
 /**

package/dist/globalSolar.d.ts

@@ -13,6 +13,12 @@ export interface GlobalSolarEclipse {
     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;
+    /** Geodetic latitude of greatest eclipse, degrees: the ground point, or for a partial eclipse the point on the Earth's limb nearest the axis, with the Sun on the horizon. */
+    greatestLatitudeDeg: number;
+    /** Longitude of greatest eclipse, degrees east in (−180, 180]. */
+    greatestLongitudeDeg: number;
+    /** Fraction of the Sun's disc area covered at greatest eclipse. */
+    greatestObscuration: number;
 }
 /** A point on a solar eclipse's central line: where the Moon's shadow axis meets the ground at one instant. */
 export interface SolarEclipseAxisPoint {

package/dist/globalSolar.js

@@ -30,6 +30,10 @@
 // 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.
+//
+// Neither is greatest eclipse for an axis that misses the Earth: upstream
+// reports no place at all, and this package reports the point on the limb
+// nearest the axis, where the Sun is on the horizon.
 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';
@@ -133,6 +137,24 @@ function axisGround(shadow, axis, u) {
     const px = u * v.x - e.x;
     const py = u * v.y - e.y;
     const pz = (u * v.z - e.z) * EARTH_FLATTENING;
+    const { latitudeDeg, longitudeDeg, o } = geodeticPlace(shadow, tt, px, py, pz);
+    // 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: the middle of `GeoidIntersect`, astronomy.ts ~8842 — geodetic
+ * latitude and longitude of a geocentric equator-of-date point in km, and the
+ * lunacentric EQJ vector toward it in AU.
+ */
+function geodeticPlace(shadow, tt, px, py, pz) {
     // Convert cartesian coordinates into geodetic latitude/longitude.
     const proj = Math.hypot(px, py) * EARTH_FLATTENING_SQUARED;
     let latitudeDeg;
@@ -153,16 +175,31 @@ function axisGround(shadow, axis, u) {
     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.
+    return { latitudeDeg, longitudeDeg, o };
+}
+/**
+ * Greatest eclipse when the axis misses the geoid: the point on the Earth's
+ * limb nearest the axis. In the dilated coordinates the geoid is a sphere, and
+ * the axis's closest approach to its center, scaled onto it, stands for that point.
+ * The axis runs perpendicular to the radius there, so it lies in the sphere's
+ * tangent plane; dilation maps tangent planes to tangent planes, so on the
+ * ellipsoid the axis lies in the geodetic horizon and the Sun's center is at
+ * geometric altitude zero, as the catalog tabulates. The observer there sees
+ * what the local search would: a total or annular phase only inside the
+ * umbra, which a non-central eclipse can graze.
+ */
+function limbGround(shadow, axis) {
+    const { tt, v, e, A, B } = axis;
+    const u = -B / (2 * A);
+    const cx = u * v.x - e.x;
+    const cy = u * v.y - e.y;
+    const cz = u * v.z - e.z;
+    const scale = EARTH_EQUATORIAL_RADIUS_KM / Math.sqrt(cx * cx + cy * cy + cz * cz);
+    const { latitudeDeg, longitudeDeg, o } = geodeticPlace(shadow, tt, cx * scale, cy * scale, cz * scale * EARTH_FLATTENING);
     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 };
+    const obscuration = (surface.r < Math.abs(surface.k) && eclipseKindFromUmbra(surface.k) === 'total')
+        ? 1.0 : solarEclipseObscuration(shadow.dir, o);
+    return { latitudeDeg, longitudeDeg, obscuration };
 }
 /**
  * UPSTREAM: `GeoidIntersect`'s choice of root — where the axis first meets
@@ -201,13 +238,18 @@ function grazingGround(shadow) {
 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 };
+        // This is a partial solar eclipse: no one stands on the axis, and
+        // greatest eclipse is on the limb nearest it.
+        const limb = limbGround(shadow, dilatedAxis(shadow));
+        return {
+            kind: 'partial', peak, axisDistanceKm: shadow.r, latitudeDeg: null, longitudeDeg: null, obscuration: null,
+            greatestLatitudeDeg: limb.latitudeDeg, greatestLongitudeDeg: limb.longitudeDeg, greatestObscuration: limb.obscuration
+        };
     }
     return {
         kind: ground.kind, peak, axisDistanceKm: shadow.r,
-        latitudeDeg: ground.latitudeDeg, longitudeDeg: ground.longitudeDeg, obscuration: ground.obscuration
+        latitudeDeg: ground.latitudeDeg, longitudeDeg: ground.longitudeDeg, obscuration: ground.obscuration,
+        greatestLatitudeDeg: ground.latitudeDeg, greatestLongitudeDeg: ground.longitudeDeg, greatestObscuration: ground.obscuration
     };
 }
 /**

package/dist/horizon.d.ts

@@ -0,0 +1,3 @@
+import { Observer } from './types.js';
+/** Apparent horizon altitude below the horizontal plane; eye height is measured above the unobstructed surface. */
+export declare function horizonDip(observer: Observer, heightAboveGroundM: number): number;

package/dist/horizon.js

@@ -0,0 +1,24 @@
+import { assertObserver } from './types.js';
+import { DEG2RAD, RAD2DEG, EARTH_FLATTENING, EARTH_EQUATORIAL_RADIUS_KM } from './nutation.js';
+/** Apparent horizon altitude below the horizontal plane; eye height is measured above the unobstructed surface. */
+export function horizonDip(observer, heightAboveGroundM) {
+    assertObserver(observer);
+    const elevation = observer.elevationM ?? 0;
+    const ground = elevation - heightAboveGroundM;
+    if (!(heightAboveGroundM >= 0 && heightAboveGroundM <= 10000) || !(ground >= -500 && ground <= 10000))
+        throw new RangeError('eye height or ground elevation out of range');
+    if (heightAboveGroundM === 0)
+        return 0;
+    // HorizonDipAngle: https://github.com/cosinekitty/astronomy/blob/865d3da7d8112bbc7911238052c6af4aaf877181/source/js/astronomy.ts#L5437.
+    const phi = observer.latitudeDeg * DEG2RAD;
+    const sinphi = Math.sin(phi);
+    const cosphi = Math.cos(phi);
+    const c = 1 / Math.hypot(cosphi, sinphi * EARTH_FLATTENING);
+    const s = c * (EARTH_FLATTENING * EARTH_FLATTENING);
+    const htKm = ground / 1000;
+    const ach = EARTH_EQUATORIAL_RADIUS_KM * c + htKm;
+    const ash = EARTH_EQUATORIAL_RADIUS_KM * s + htKm;
+    const radiusM = 1000 * Math.hypot(ach * cosphi, ash * sinphi);
+    const k = 0.175 * Math.pow(1 - (6.5e-3 / 283.15) * (elevation - (2 / 3) * heightAboveGroundM), 3.256);
+    return RAD2DEG * -(Math.sqrt(2 * (1 - k) * heightAboveGroundM / radiusM) / (1 - k));
+}

package/dist/illumination.d.ts

@@ -1,3 +1,4 @@
+import { Vec3 } from './nutation.js';
 /** Moon illumination at an instant. `phase` is 0 at new moon, 0.5 at full. */
 export interface MoonIllumination {
     fraction: number;
@@ -5,6 +6,8 @@ export interface MoonIllumination {
     phase: number;
     waxing: boolean;
 }
+/** UPSTREAM: `AngleBetween`, astronomy.ts lines 256-273 — angle between two vectors, [0, 180]. */
+export declare function angleBetweenDeg(a: Vec3, b: Vec3): 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

@@ -14,7 +14,7 @@ import { DEG2RAD, PrecessDirection, RAD2DEG, earthTilt, eclipticToEquatorial, gy
 import { moonGeoVectorEqj } from './moon.js';
 import { earthHelioVector, sunGeoVectorEqj } from './sun.js';
 /** UPSTREAM: `AngleBetween`, astronomy.ts lines 256-273 — angle between two vectors, [0, 180]. */
-function angleBetweenDeg(a, b) {
+export function angleBetweenDeg(a, b) {
     const aa = a.x * a.x + a.y * a.y + a.z * a.z;
     const bb = b.x * b.x + b.y * b.y + b.z * b.z;
     const dot = (a.x * b.x + a.y * b.y + a.z * b.z) / Math.sqrt(aa * bb);

package/dist/index.d.ts

@@ -1,4 +1,7 @@
-export type { Observer } from './types.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';
@@ -6,8 +9,8 @@ export type { AltAz } from './transforms.js';
 export { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
 export type { MoonIllumination } from './illumination.js';
 export { moonIllumination } from './illumination.js';
-export type { SunEvent, SunEventKind, MoonEvent, MoonEventKind, MoonPhaseEvent, MoonPhaseName } from './events.js';
-export { sunEvents, moonEvents, searchMoonPhases } from './events.js';
+export type { SunEvent, SunEventKind, MoonEvent, MoonEventKind, MoonPhaseEvent, MoonPhaseName, PlanetEvent, PlanetEventKind } from './events.js';
+export { sunEvents, moonEvents, searchMoonPhases, planetEvents } 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,8 +1,10 @@
+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 { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
 export { moonIllumination } from './illumination.js';
-export { sunEvents, moonEvents, searchMoonPhases } from './events.js';
+export { sunEvents, moonEvents, searchMoonPhases, planetEvents } 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/planetModels.d.ts

@@ -0,0 +1,5 @@
+import { type Planet } from './types.js';
+import { type Vec3 } from './nutation.js';
+/** INTERNAL: geometric Sun-centered vector in AU, J2000 mean equator. */
+export declare function planetHelioVector(planet: Planet, tt: number): Vec3;
+export declare function planetGeoVectorEqj(planet: Planet, tt: number, aberration?: boolean): Vec3;