@openwaters/almanac 0.6.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.6.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:

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/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;

package/dist/planetModels.js

@@ -0,0 +1,467 @@
+import { earthHelioVector, vsopRotate, vsopSphereToRect } from './sun.js';
+import { C_AUDAY, PI2 } from './nutation.js';
+// VsopFormula / CalcVsop: pinned astronomy.ts#L3191 / #L3255.
+function vsopFormula(formula, t, clampAngle) {
+    let tpower = 1, coord = 0;
+    for (const series of formula) {
+        let sum = 0;
+        for (const [ampl, phas, freq] of series)
+            sum += ampl * Math.cos(phas + (t * freq));
+        let incr = tpower * sum;
+        if (clampAngle)
+            incr %= PI2;
+        coord += incr;
+        tpower *= t;
+    }
+    return coord;
+}
+/** INTERNAL: geometric Sun-centered vector in AU, J2000 mean equator. */
+export function planetHelioVector(planet, tt) {
+    if (planet === 'earth')
+        return earthHelioVector(tt);
+    const model = models[planet], t = tt / 365250;
+    const lon = vsopFormula(model[0], t, true);
+    const lat = vsopFormula(model[1], t, false);
+    const rad = vsopFormula(model[2], t, false);
+    return vsopRotate(vsopSphereToRect(lon, lat, rad));
+}
+// BackdatePosition / BodyPosition / CorrectLightTravel: pinned astronomy.ts#L4170–L4313.
+export function planetGeoVectorEqj(planet, tt, aberration = true) {
+    let ltime = tt, dt = 0;
+    const fixedEarth = aberration ? null : earthHelioVector(tt);
+    for (let iter = 0; iter < 10; ++iter) {
+        // Backdating Earth along with the planet supplies upstream's aberration correction.
+        const earth = fixedEarth ?? earthHelioVector(ltime), target = planetHelioVector(planet, ltime);
+        const pos = { x: target.x - earth.x, y: target.y - earth.y, z: target.z - earth.z };
+        const lt = Math.sqrt(pos.x * pos.x + pos.y * pos.y + pos.z * pos.z) / C_AUDAY;
+        if (lt > 1)
+            throw new Error('Object is too distant for light-travel solver.');
+        const next = tt - lt;
+        dt = Math.abs(next - ltime);
+        if (dt < 1e-9)
+            return pos;
+        ltime = next;
+    }
+    throw new Error(`Light-travel time solver did not converge: dt = ${dt}`);
+}
+const models = {
+    mercury: [
+        [
+            [
+                [4.40250710144, 0.00000000000, 0.00000000000],
+                [0.40989414977, 1.48302034195, 26087.90314157420],
+                [0.05046294200, 4.47785489551, 52175.80628314840],
+                [0.00855346844, 1.16520322459, 78263.70942472259],
+                [0.00165590362, 4.11969163423, 104351.61256629678],
+                [0.00034561897, 0.77930768443, 130439.51570787099],
+                [0.00007583476, 3.71348404924, 156527.41884944518]
+            ],
+            [
+                [26087.90313685529, 0.00000000000, 0.00000000000],
+                [0.01131199811, 6.21874197797, 26087.90314157420],
+                [0.00292242298, 3.04449355541, 52175.80628314840],
+                [0.00075775081, 6.08568821653, 78263.70942472259],
+                [0.00019676525, 2.80965111777, 104351.61256629678]
+            ]
+        ],
+        [
+            [
+                [0.11737528961, 1.98357498767, 26087.90314157420],
+                [0.02388076996, 5.03738959686, 52175.80628314840],
+                [0.01222839532, 3.14159265359, 0.00000000000],
+                [0.00543251810, 1.79644363964, 78263.70942472259],
+                [0.00129778770, 4.83232503958, 104351.61256629678],
+                [0.00031866927, 1.58088495658, 130439.51570787099],
+                [0.00007963301, 4.60972126127, 156527.41884944518]
+            ],
+            [
+                [0.00274646065, 3.95008450011, 26087.90314157420],
+                [0.00099737713, 3.14159265359, 0.00000000000]
+            ]
+        ],
+        [
+            [
+                [0.39528271651, 0.00000000000, 0.00000000000],
+                [0.07834131818, 6.19233722598, 26087.90314157420],
+                [0.00795525558, 2.95989690104, 52175.80628314840],
+                [0.00121281764, 6.01064153797, 78263.70942472259],
+                [0.00021921969, 2.77820093972, 104351.61256629678],
+                [0.00004354065, 5.82894543774, 130439.51570787099]
+            ],
+            [
+                [0.00217347740, 4.65617158665, 26087.90314157420],
+                [0.00044141826, 1.42385544001, 52175.80628314840]
+            ]
+        ]
+    ],
+    venus: [
+        [
+            [
+                [3.17614666774, 0.00000000000, 0.00000000000],
+                [0.01353968419, 5.59313319619, 10213.28554621100],
+                [0.00089891645, 5.30650047764, 20426.57109242200],
+                [0.00005477194, 4.41630661466, 7860.41939243920],
+                [0.00003455741, 2.69964447820, 11790.62908865880],
+                [0.00002372061, 2.99377542079, 3930.20969621960],
+                [0.00001317168, 5.18668228402, 26.29831979980],
+                [0.00001664146, 4.25018630147, 1577.34354244780],
+                [0.00001438387, 4.15745084182, 9683.59458111640],
+                [0.00001200521, 6.15357116043, 30639.85663863300]
+            ],
+            [
+                [10213.28554621638, 0.00000000000, 0.00000000000],
+                [0.00095617813, 2.46406511110, 10213.28554621100],
+                [0.00007787201, 0.62478482220, 20426.57109242200]
+            ]
+        ],
+        [
+            [
+                [0.05923638472, 0.26702775812, 10213.28554621100],
+                [0.00040107978, 1.14737178112, 20426.57109242200],
+                [0.00032814918, 3.14159265359, 0.00000000000]
+            ],
+            [
+                [0.00287821243, 1.88964962838, 10213.28554621100]
+            ]
+        ],
+        [
+            [
+                [0.72334820891, 0.00000000000, 0.00000000000],
+                [0.00489824182, 4.02151831717, 10213.28554621100],
+                [0.00001658058, 4.90206728031, 20426.57109242200],
+                [0.00001378043, 1.12846591367, 11790.62908865880],
+                [0.00001632096, 2.84548795207, 7860.41939243920],
+                [0.00000498395, 2.58682193892, 9683.59458111640],
+                [0.00000221985, 2.01346696541, 19367.18916223280],
+                [0.00000237454, 2.55136053886, 15720.83878487840]
+            ],
+            [
+                [0.00034551041, 0.89198706276, 10213.28554621100]
+            ]
+        ]
+    ],
+    mars: [
+        [
+            [
+                [6.20347711581, 0.00000000000, 0.00000000000],
+                [0.18656368093, 5.05037100270, 3340.61242669980],
+                [0.01108216816, 5.40099836344, 6681.22485339960],
+                [0.00091798406, 5.75478744667, 10021.83728009940],
+                [0.00027744987, 5.97049513147, 3.52311834900],
+                [0.00010610235, 2.93958560338, 2281.23049651060],
+                [0.00012315897, 0.84956094002, 2810.92146160520],
+                [0.00008926784, 4.15697846427, 0.01725365220],
+                [0.00008715691, 6.11005153139, 13362.44970679920],
+                [0.00006797556, 0.36462229657, 398.14900340820],
+                [0.00007774872, 3.33968761376, 5621.84292321040],
+                [0.00003575078, 1.66186505710, 2544.31441988340],
+                [0.00004161108, 0.22814971327, 2942.46342329160],
+                [0.00003075252, 0.85696614132, 191.44826611160],
+                [0.00002628117, 0.64806124465, 3337.08930835080],
+                [0.00002937546, 6.07893711402, 0.06731030280],
+                [0.00002389414, 5.03896442664, 796.29800681640],
+                [0.00002579844, 0.02996736156, 3344.13554504880],
+                [0.00001528141, 1.14979301996, 6151.53388830500],
+                [0.00001798806, 0.65634057445, 529.69096509460],
+                [0.00001264357, 3.62275122593, 5092.15195811580],
+                [0.00001286228, 3.06796065034, 2146.16541647520],
+                [0.00001546404, 2.91579701718, 1751.53953141600],
+                [0.00001024902, 3.69334099279, 8962.45534991020],
+                [0.00000891566, 0.18293837498, 16703.06213349900],
+                [0.00000858759, 2.40093811940, 2914.01423582380],
+                [0.00000832715, 2.46418619474, 3340.59517304760],
+                [0.00000832720, 4.49495782139, 3340.62968035200],
+                [0.00000712902, 3.66335473479, 1059.38193018920],
+                [0.00000748723, 3.82248614017, 155.42039943420],
+                [0.00000723861, 0.67497311481, 3738.76143010800],
+                [0.00000635548, 2.92182225127, 8432.76438481560],
+                [0.00000655162, 0.48864064125, 3127.31333126180],
+                [0.00000550474, 3.81001042328, 0.98032106820],
+                [0.00000552750, 4.47479317037, 1748.01641306700],
+                [0.00000425966, 0.55364317304, 6283.07584999140],
+                [0.00000415131, 0.49662285038, 213.29909543800],
+                [0.00000472167, 3.62547124025, 1194.44701022460],
+                [0.00000306551, 0.38052848348, 6684.74797174860],
+                [0.00000312141, 0.99853944405, 6677.70173505060],
+                [0.00000293198, 4.22131299634, 20.77539549240],
+                [0.00000302375, 4.48618007156, 3532.06069281140],
+                [0.00000274027, 0.54222167059, 3340.54511639700],
+                [0.00000281079, 5.88163521788, 1349.86740965880],
+                [0.00000231183, 1.28242156993, 3870.30339179440],
+                [0.00000283602, 5.76885434940, 3149.16416058820],
+                [0.00000236117, 5.75503217933, 3333.49887969900],
+                [0.00000274033, 0.13372524985, 3340.67973700260],
+                [0.00000299395, 2.78323740866, 6254.62666252360]
+            ],
+            [
+                [3340.61242700512, 0.00000000000, 0.00000000000],
+                [0.01457554523, 3.60433733236, 3340.61242669980],
+                [0.00168414711, 3.92318567804, 6681.22485339960],
+                [0.00020622975, 4.26108844583, 10021.83728009940],
+                [0.00003452392, 4.73210393190, 3.52311834900],
+                [0.00002586332, 4.60670058555, 13362.44970679920],
+                [0.00000841535, 4.45864030426, 2281.23049651060]
+            ],
+            [
+                [0.00058152577, 2.04961712429, 3340.61242669980],
+                [0.00013459579, 2.45738706163, 6681.22485339960]
+            ]
+        ],
+        [
+            [
+                [0.03197134986, 3.76832042431, 3340.61242669980],
+                [0.00298033234, 4.10616996305, 6681.22485339960],
+                [0.00289104742, 0.00000000000, 0.00000000000],
+                [0.00031365539, 4.44651053090, 10021.83728009940],
+                [0.00003484100, 4.78812549260, 13362.44970679920]
+            ],
+            [
+                [0.00217310991, 6.04472194776, 3340.61242669980],
+                [0.00020976948, 3.14159265359, 0.00000000000],
+                [0.00012834709, 1.60810667915, 6681.22485339960]
+            ]
+        ],
+        [
+            [
+                [1.53033488271, 0.00000000000, 0.00000000000],
+                [0.14184953160, 3.47971283528, 3340.61242669980],
+                [0.00660776362, 3.81783443019, 6681.22485339960],
+                [0.00046179117, 4.15595316782, 10021.83728009940],
+                [0.00008109733, 5.55958416318, 2810.92146160520],
+                [0.00007485318, 1.77239078402, 5621.84292321040],
+                [0.00005523191, 1.36436303770, 2281.23049651060],
+                [0.00003825160, 4.49407183687, 13362.44970679920],
+                [0.00002306537, 0.09081579001, 2544.31441988340],
+                [0.00001999396, 5.36059617709, 3337.08930835080],
+                [0.00002484394, 4.92545639920, 2942.46342329160],
+                [0.00001960195, 4.74249437639, 3344.13554504880],
+                [0.00001167119, 2.11260868341, 5092.15195811580],
+                [0.00001102816, 5.00908403998, 398.14900340820],
+                [0.00000899066, 4.40791133207, 529.69096509460],
+                [0.00000992252, 5.83861961952, 6151.53388830500],
+                [0.00000807354, 2.10217065501, 1059.38193018920],
+                [0.00000797915, 3.44839203899, 796.29800681640],
+                [0.00000740975, 1.49906336885, 2146.16541647520]
+            ],
+            [
+                [0.01107433345, 2.03250524857, 3340.61242669980],
+                [0.00103175887, 2.37071847807, 6681.22485339960],
+                [0.00012877200, 0.00000000000, 0.00000000000],
+                [0.00010815880, 2.70888095665, 10021.83728009940]
+            ],
+            [
+                [0.00044242249, 0.47930604954, 3340.61242669980],
+                [0.00008138042, 0.86998389204, 6681.22485339960]
+            ]
+        ]
+    ],
+    jupiter: [
+        [
+            [
+                [0.59954691494, 0.00000000000, 0.00000000000],
+                [0.09695898719, 5.06191793158, 529.69096509460],
+                [0.00573610142, 1.44406205629, 7.11354700080],
+                [0.00306389205, 5.41734730184, 1059.38193018920],
+                [0.00097178296, 4.14264726552, 632.78373931320],
+                [0.00072903078, 3.64042916389, 522.57741809380],
+                [0.00064263975, 3.41145165351, 103.09277421860],
+                [0.00039806064, 2.29376740788, 419.48464387520],
+                [0.00038857767, 1.27231755835, 316.39186965660],
+                [0.00027964629, 1.78454591820, 536.80451209540],
+                [0.00013589730, 5.77481040790, 1589.07289528380],
+                [0.00008246349, 3.58227925840, 206.18554843720],
+                [0.00008768704, 3.63000308199, 949.17560896980],
+                [0.00007368042, 5.08101194270, 735.87651353180],
+                [0.00006263150, 0.02497628807, 213.29909543800],
+                [0.00006114062, 4.51319998626, 1162.47470440780],
+                [0.00004905396, 1.32084470588, 110.20632121940],
+                [0.00005305285, 1.30671216791, 14.22709400160],
+                [0.00005305441, 4.18625634012, 1052.26838318840],
+                [0.00004647248, 4.69958103684, 3.93215326310],
+                [0.00003045023, 4.31676431084, 426.59819087600],
+                [0.00002609999, 1.56667394063, 846.08283475120],
+                [0.00002028191, 1.06376530715, 3.18139373770],
+                [0.00001764763, 2.14148655117, 1066.49547719000],
+                [0.00001722972, 3.88036268267, 1265.56747862640],
+                [0.00001920945, 0.97168196472, 639.89728631400],
+                [0.00001633223, 3.58201833555, 515.46387109300],
+                [0.00001431999, 4.29685556046, 625.67019231240],
+                [0.00000973272, 4.09764549134, 95.97922721780]
+            ],
+            [
+                [529.69096508814, 0.00000000000, 0.00000000000],
+                [0.00489503243, 4.22082939470, 529.69096509460],
+                [0.00228917222, 6.02646855621, 7.11354700080],
+                [0.00030099479, 4.54540782858, 1059.38193018920],
+                [0.00020720920, 5.45943156902, 522.57741809380],
+                [0.00012103653, 0.16994816098, 536.80451209540],
+                [0.00006067987, 4.42422292017, 103.09277421860],
+                [0.00005433968, 3.98480737746, 419.48464387520],
+                [0.00004237744, 5.89008707199, 14.22709400160]
+            ],
+            [
+                [0.00047233601, 4.32148536482, 7.11354700080],
+                [0.00030649436, 2.92977788700, 529.69096509460],
+                [0.00014837605, 3.14159265359, 0.00000000000]
+            ]
+        ],
+        [
+            [
+                [0.02268615702, 3.55852606721, 529.69096509460],
+                [0.00109971634, 3.90809347197, 1059.38193018920],
+                [0.00110090358, 0.00000000000, 0.00000000000],
+                [0.00008101428, 3.60509572885, 522.57741809380],
+                [0.00006043996, 4.25883108339, 1589.07289528380],
+                [0.00006437782, 0.30627119215, 536.80451209540]
+            ],
+            [
+                [0.00078203446, 1.52377859742, 529.69096509460]
+            ]
+        ],
+        [
+            [
+                [5.20887429326, 0.00000000000, 0.00000000000],
+                [0.25209327119, 3.49108639871, 529.69096509460],
+                [0.00610599976, 3.84115365948, 1059.38193018920],
+                [0.00282029458, 2.57419881293, 632.78373931320],
+                [0.00187647346, 2.07590383214, 522.57741809380],
+                [0.00086792905, 0.71001145545, 419.48464387520],
+                [0.00072062974, 0.21465724607, 536.80451209540],
+                [0.00065517248, 5.97995884790, 316.39186965660],
+                [0.00029134542, 1.67759379655, 103.09277421860],
+                [0.00030135335, 2.16132003734, 949.17560896980],
+                [0.00023453271, 3.54023522184, 735.87651353180],
+                [0.00022283743, 4.19362594399, 1589.07289528380],
+                [0.00023947298, 0.27458037480, 7.11354700080],
+                [0.00013032614, 2.96042965363, 1162.47470440780],
+                [0.00009703360, 1.90669633585, 206.18554843720],
+                [0.00012749023, 2.71550286592, 1052.26838318840],
+                [0.00007057931, 2.18184839926, 1265.56747862640],
+                [0.00006137703, 6.26418240033, 846.08283475120],
+                [0.00002616976, 2.00994012876, 1581.95934828300]
+            ],
+            [
+                [0.01271801520, 2.64937512894, 529.69096509460],
+                [0.00061661816, 3.00076460387, 1059.38193018920],
+                [0.00053443713, 3.89717383175, 522.57741809380],
+                [0.00031185171, 4.88276958012, 536.80451209540],
+                [0.00041390269, 0.00000000000, 0.00000000000]
+            ]
+        ]
+    ],
+    saturn: [
+        [
+            [
+                [0.87401354025, 0.00000000000, 0.00000000000],
+                [0.11107659762, 3.96205090159, 213.29909543800],
+                [0.01414150957, 4.58581516874, 7.11354700080],
+                [0.00398379389, 0.52112032699, 206.18554843720],
+                [0.00350769243, 3.30329907896, 426.59819087600],
+                [0.00206816305, 0.24658372002, 103.09277421860],
+                [0.00079271300, 3.84007056878, 220.41264243880],
+                [0.00023990355, 4.66976924553, 110.20632121940],
+                [0.00016573588, 0.43719228296, 419.48464387520],
+                [0.00014906995, 5.76903183869, 316.39186965660],
+                [0.00015820290, 0.93809155235, 632.78373931320],
+                [0.00014609559, 1.56518472000, 3.93215326310],
+                [0.00013160301, 4.44891291899, 14.22709400160],
+                [0.00015053543, 2.71669915667, 639.89728631400],
+                [0.00013005299, 5.98119023644, 11.04570026390],
+                [0.00010725067, 3.12939523827, 202.25339517410],
+                [0.00005863206, 0.23656938524, 529.69096509460],
+                [0.00005227757, 4.20783365759, 3.18139373770],
+                [0.00006126317, 1.76328667907, 277.03499374140],
+                [0.00005019687, 3.17787728405, 433.71173787680],
+                [0.00004592550, 0.61977744975, 199.07200143640],
+                [0.00004005867, 2.24479718502, 63.73589830340],
+                [0.00002953796, 0.98280366998, 95.97922721780],
+                [0.00003873670, 3.22283226966, 138.51749687070],
+                [0.00002461186, 2.03163875071, 735.87651353180],
+                [0.00003269484, 0.77492638211, 949.17560896980],
+                [0.00001758145, 3.26580109940, 522.57741809380],
+                [0.00001640172, 5.50504453050, 846.08283475120],
+                [0.00001391327, 4.02333150505, 323.50541665740],
+                [0.00001580648, 4.37265307169, 309.27832265580],
+                [0.00001123498, 2.83726798446, 415.55249061210],
+                [0.00001017275, 3.71700135395, 227.52618943960],
+                [0.00000848642, 3.19150170830, 209.36694217490]
+            ],
+            [
+                [213.29909521690, 0.00000000000, 0.00000000000],
+                [0.01297370862, 1.82834923978, 213.29909543800],
+                [0.00564345393, 2.88499717272, 7.11354700080],
+                [0.00093734369, 1.06311793502, 426.59819087600],
+                [0.00107674962, 2.27769131009, 206.18554843720],
+                [0.00040244455, 2.04108104671, 220.41264243880],
+                [0.00019941774, 1.27954390470, 103.09277421860],
+                [0.00010511678, 2.74880342130, 14.22709400160],
+                [0.00006416106, 0.38238295041, 639.89728631400],
+                [0.00004848994, 2.43037610229, 419.48464387520],
+                [0.00004056892, 2.92133209468, 110.20632121940],
+                [0.00003768635, 3.64965330780, 3.93215326310]
+            ],
+            [
+                [0.00116441330, 1.17988132879, 7.11354700080],
+                [0.00091841837, 0.07325195840, 213.29909543800],
+                [0.00036661728, 0.00000000000, 0.00000000000],
+                [0.00015274496, 4.06493179167, 206.18554843720]
+            ]
+        ],
+        [
+            [
+                [0.04330678039, 3.60284428399, 213.29909543800],
+                [0.00240348302, 2.85238489373, 426.59819087600],
+                [0.00084745939, 0.00000000000, 0.00000000000],
+                [0.00030863357, 3.48441504555, 220.41264243880],
+                [0.00034116062, 0.57297307557, 206.18554843720],
+                [0.00014734070, 2.11846596715, 639.89728631400],
+                [0.00009916667, 5.79003188904, 419.48464387520],
+                [0.00006993564, 4.73604689720, 7.11354700080],
+                [0.00004807588, 5.43305312061, 316.39186965660]
+            ],
+            [
+                [0.00198927992, 4.93901017903, 213.29909543800],
+                [0.00036947916, 3.14159265359, 0.00000000000],
+                [0.00017966989, 0.51979431110, 426.59819087600]
+            ]
+        ],
+        [
+            [
+                [9.55758135486, 0.00000000000, 0.00000000000],
+                [0.52921382865, 2.39226219573, 213.29909543800],
+                [0.01873679867, 5.23549604660, 206.18554843720],
+                [0.01464663929, 1.64763042902, 426.59819087600],
+                [0.00821891141, 5.93520042303, 316.39186965660],
+                [0.00547506923, 5.01532618980, 103.09277421860],
+                [0.00371684650, 2.27114821115, 220.41264243880],
+                [0.00361778765, 3.13904301847, 7.11354700080],
+                [0.00140617506, 5.70406606781, 632.78373931320],
+                [0.00108974848, 3.29313390175, 110.20632121940],
+                [0.00069006962, 5.94099540992, 419.48464387520],
+                [0.00061053367, 0.94037691801, 639.89728631400],
+                [0.00048913294, 1.55733638681, 202.25339517410],
+                [0.00034143772, 0.19519102597, 277.03499374140],
+                [0.00032401773, 5.47084567016, 949.17560896980],
+                [0.00020936596, 0.46349251129, 735.87651353180],
+                [0.00009796004, 5.20477537945, 1265.56747862640],
+                [0.00011993338, 5.98050967385, 846.08283475120],
+                [0.00020839300, 1.52102476129, 433.71173787680],
+                [0.00015298404, 3.05943814940, 529.69096509460],
+                [0.00006465823, 0.17732249942, 1052.26838318840],
+                [0.00011380257, 1.73105427040, 522.57741809380],
+                [0.00003419618, 4.94550542171, 1581.95934828300]
+            ],
+            [
+                [0.06182981340, 0.25843511480, 213.29909543800],
+                [0.00506577242, 0.71114625261, 206.18554843720],
+                [0.00341394029, 5.79635741658, 426.59819087600],
+                [0.00188491195, 0.47215589652, 220.41264243880],
+                [0.00186261486, 3.14159265359, 0.00000000000],
+                [0.00143891146, 1.40744822888, 7.11354700080]
+            ],
+            [
+                [0.00436902572, 4.78671677509, 213.29909543800]
+            ]
+        ]
+    ]
+};

package/dist/planets.d.ts

@@ -0,0 +1,32 @@
+import { type Planet, type Observer } from './types.js';
+import { type AltAz } from './transforms.js';
+/** Geometric Sun-centered AU vector in the fixed J2000 mean equatorial frame. */
+export interface HeliocentricPosition {
+    xAu: number;
+    yAu: number;
+    zAu: number;
+}
+/** Apparent geocentric position on the true equator and equinox of date. */
+export interface PlanetPosition {
+    raDeg: number;
+    decDeg: number;
+    distanceAu: number;
+}
+/** Geometric phase and approximate airless visual magnitude, plus apparent solar separation. */
+export interface PlanetIllumination {
+    fraction: number;
+    phaseAngleDeg: number;
+    magnitude: number;
+    elongationDeg: number;
+}
+export declare function planetIlluminationAtTT(planet: Planet, tt: number): PlanetIllumination;
+/** Approximate airless magnitude includes Saturn's rings; elongation is apparent separation from the Sun. */
+export declare function planetIllumination(planet: Planet, time: Date): PlanetIllumination;
+/** INTERNAL: TT-labeled evidence bypasses the civil-time Delta-T conversion. */
+export declare function planetApparentAtTT(planet: Planet, tt: number): PlanetPosition;
+/** Geometric position at the requested instant; accepts Earth. */
+export declare function planetHeliocentricPosition(planet: Planet, time: Date): HeliocentricPosition;
+/** Apparent geocentric position with light-time, aberration, precession, and nutation. */
+export declare function planetPosition(planet: Planet, time: Date): PlanetPosition;
+/** Refracted topocentric position; altitude remains relative to the horizontal plane. */
+export declare function planetAltAz(planet: Planet, time: Date, observer: Observer): AltAz;

package/dist/planets.js

@@ -0,0 +1,104 @@
+import { assertPlanet, assertSupported, assertObserver } from './types.js';
+import { ttDays, ttDaysFromUt, utDays } from './time.js';
+import { gyration, PrecessDirection, equatorialFromVector, DEG2RAD, RAD2DEG, earthTilt, eclipticToEquatorial } from './nutation.js';
+import { planetHelioVector, planetGeoVectorEqj } from './planetModels.js';
+import { topoAltAzUnrefracted, refract } from './transforms.js';
+import { angleBetweenDeg } from './illumination.js';
+import { earthHelioVector, sunGeoVectorEqj } from './sun.js';
+// VisualMagnitude: https://github.com/cosinekitty/astronomy/blob/865d3da7d8112bbc7911238052c6af4aaf877181/source/js/astronomy.ts#L4901.
+function visualMagnitude(planet, phase, helioDist, geoDist) {
+    let c0, c1 = 0, c2 = 0, c3 = 0;
+    switch (planet) {
+        case 'mercury':
+            c0 = -0.60;
+            c1 = 4.98;
+            c2 = -4.88;
+            c3 = 3.02;
+            break;
+        case 'venus':
+            if (phase < 163.6) {
+                c0 = -4.47;
+                c1 = 1.03;
+                c2 = 0.57;
+                c3 = 0.13;
+            }
+            else {
+                c0 = 0.98;
+                c1 = -1.02;
+            }
+            break;
+        case 'mars':
+            c0 = -1.52;
+            c1 = 1.60;
+            break;
+        case 'jupiter':
+            c0 = -9.40;
+            c1 = 0.50;
+            break;
+        default: throw new Error('unsupported planet in visualMagnitude');
+    }
+    const x = phase / 100;
+    let mag = c0 + x * (c1 + x * (c2 + x * c3));
+    mag += 5 * Math.log10(helioDist * geoDist);
+    return mag;
+}
+// SaturnMagnitude: pinned astronomy.ts#L4927; Ecliptic: #L3013.
+function saturnMagnitude(phase, helioDist, geoDist, gc, tt) {
+    const ecl = eclipticToEquatorial(-earthTilt(tt).tobl, gyration(gc, tt, PrecessDirection.From2000));
+    const lat = RAD2DEG * Math.atan2(ecl.z, Math.hypot(ecl.x, ecl.y));
+    let lon = RAD2DEG * Math.atan2(ecl.y, ecl.x);
+    if (lon < 0)
+        lon += 360;
+    const ir = DEG2RAD * 28.06, nr = DEG2RAD * (169.51 + (3.82e-5 * tt));
+    const tilt = Math.asin(Math.sin(DEG2RAD * lat) * Math.cos(ir) - Math.cos(DEG2RAD * lat) * Math.sin(ir) * Math.sin(DEG2RAD * lon - nr));
+    const sinTilt = Math.sin(Math.abs(tilt));
+    let mag = -9 + 0.044 * phase;
+    mag += sinTilt * (-2.6 + 1.2 * sinTilt);
+    mag += 5 * Math.log10(helioDist * geoDist);
+    return mag;
+}
+// Illumination: pinned astronomy.ts#L5066; AngleFromSun: #L4869.
+export function planetIlluminationAtTT(planet, tt) {
+    const earth = earthHelioVector(tt), hc = planetHelioVector(planet, tt);
+    const gc = { x: hc.x - earth.x, y: hc.y - earth.y, z: hc.z - earth.z };
+    const phaseAngleDeg = angleBetweenDeg(gc, hc);
+    const helioDist = Math.sqrt(hc.x * hc.x + hc.y * hc.y + hc.z * hc.z);
+    const geoDist = Math.sqrt(gc.x * gc.x + gc.y * gc.y + gc.z * gc.z);
+    const magnitude = planet === 'saturn' ? saturnMagnitude(phaseAngleDeg, helioDist, geoDist, gc, tt) : visualMagnitude(planet, phaseAngleDeg, helioDist, geoDist);
+    return { fraction: (1 + Math.cos(DEG2RAD * phaseAngleDeg)) / 2, phaseAngleDeg, magnitude,
+        elongationDeg: angleBetweenDeg(sunGeoVectorEqj(tt), planetGeoVectorEqj(planet, tt)) };
+}
+/** Approximate airless magnitude includes Saturn's rings; elongation is apparent separation from the Sun. */
+export function planetIllumination(planet, time) {
+    assertPlanet(planet);
+    assertSupported(time);
+    return planetIlluminationAtTT(planet, ttDays(time));
+}
+/** INTERNAL: TT-labeled evidence bypasses the civil-time Delta-T conversion. */
+export function planetApparentAtTT(planet, tt) {
+    const direction = equatorialFromVector(gyration(planetGeoVectorEqj(planet, tt), tt, PrecessDirection.From2000));
+    // Aberration changes direction, not physical range; keep Earth at reception for distance.
+    const range = planetGeoVectorEqj(planet, tt, false);
+    return { raDeg: direction.raDeg, decDeg: direction.decDeg, distanceAu: Math.hypot(range.x, range.y, range.z) };
+}
+/** Geometric position at the requested instant; accepts Earth. */
+export function planetHeliocentricPosition(planet, time) {
+    assertPlanet(planet, true);
+    assertSupported(time);
+    const p = planetHelioVector(planet, ttDays(time));
+    return { xAu: p.x, yAu: p.y, zAu: p.z };
+}
+/** Apparent geocentric position with light-time, aberration, precession, and nutation. */
+export function planetPosition(planet, time) {
+    assertPlanet(planet);
+    assertSupported(time);
+    return planetApparentAtTT(planet, ttDays(time));
+}
+/** Refracted topocentric position; altitude remains relative to the horizontal plane. */
+export function planetAltAz(planet, time, observer) {
+    assertPlanet(planet);
+    assertSupported(time);
+    assertObserver(observer);
+    const ut = utDays(time);
+    return refract(topoAltAzUnrefracted(planetGeoVectorEqj(planet, ttDaysFromUt(ut)), ut, observer));
+}

package/dist/solar.d.ts

@@ -67,7 +67,7 @@ export declare function eclipseKindFromUmbra(k: number): 'total' | 'annular';
  *      interval, or if no visible eclipse remains before the end of it.
  * @throws {RangeError} if `after` is invalid or `observer` is out of range.
  */
-export declare function nextSolarEclipse(after: Date, observer: Observer): SolarEclipse;
+export declare function nextSolarEclipse(after: Date, observer: Observer, heightAboveGroundM?: number): SolarEclipse;
 /**
  * The last solar eclipse `observer` can see whose peak falls strictly before
  * `before`, skipping peaks within 100 ms of it, just as `nextSolarEclipse`
@@ -77,6 +77,6 @@ export declare function nextSolarEclipse(after: Date, observer: Observer): Solar
  *      interval, or if no visible eclipse remains after the start of it.
  * @throws {RangeError} if `before` is invalid or `observer` is out of range.
  */
-export declare function previousSolarEclipse(before: Date, observer: Observer): SolarEclipse;
+export declare function previousSolarEclipse(before: Date, observer: Observer, heightAboveGroundM?: number): SolarEclipse;
 /** Solar eclipses `observer` can see with peaks in `[startUtc, endUtc)`, sorted ascending. Contacts may fall outside the window. */
-export declare function solarEclipses(startUtc: Date, endUtc: Date, observer: Observer): SolarEclipse[];
+export declare function solarEclipses(startUtc: Date, endUtc: Date, observer: Observer, heightAboveGroundM?: number): SolarEclipse[];

package/dist/solar.js

@@ -34,6 +34,7 @@ import { moonGeoVectorEqj } from './moon.js';
 import { sunGeoVectorEqj } from './sun.js';
 import { observerGeoVectorEqj, refractionDeg, topoAltAzUnrefracted } from './transforms.js';
 import { MOON_MEAN_RADIUS_KM, SUN_RADIUS_KM, search, searchMoonPhase } from './events.js';
+import { horizonDip } from './horizon.js';
 import { calcShadow, moonEclipticLatitudeDeg, PRUNE_LATITUDE_DEG, SAME_ECLIPSE_MS, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP } from './eclipse.js';
 /** UPSTREAM: `SUN_RADIUS_AU` and `MOON_POLAR_RADIUS_AU`, astronomy.ts 135 and 149-150.
  *  INTERNAL: `MOON_POLAR_RADIUS_KM` is shared with globalSolar.ts. */
@@ -66,7 +67,7 @@ function localMoonShadow(ut, observer) {
     return calcShadow(MOON_MEAN_RADIUS_KM, ut, o, hm);
 }
 /** UPSTREAM: `AngleBetween`, astronomy.ts ~256 — degrees. */
-function angleBetweenDeg(a, b) {
+function solarAngleBetweenDeg(a, b) {
     const aa = (a.x * a.x + a.y * a.y + a.z * a.z);
     if (Math.abs(aa) < 1.0e-8)
         throw new Error('almanac internal: AngleBetween first vector is too short');
@@ -131,7 +132,7 @@ function discObscuration(hm, lo) {
     // Calculate the apparent angular radius of the Moon for the observer.
     const moonRadius = Math.asin(MOON_POLAR_RADIUS_AU / Math.hypot(lo.x, lo.y, lo.z));
     // Calculate the apparent angular separation between the Sun's center and the Moon's center.
-    const sunMoonSeparation = angleBetweenDeg(lo, ho);
+    const sunMoonSeparation = solarAngleBetweenDeg(lo, ho);
     // Find the fraction of the Sun's apparent disc area that is covered by the Moon.
     return discOverlap(sunRadius, moonRadius, sunMoonSeparation * DEG2RAD);
 }
@@ -254,8 +255,8 @@ function buildSolarEclipse(shadow, observer) {
  * ponytail: three samples, not a sunrise search — a day that starts after C1
  * and ends before the peak still drops. Upgrade path: sunEvents over [c1, c4].
  */
-function seesAnyOfIt(e) {
-    return e.sunAltDeg.c1 > 0.0 || e.sunAltDeg.peak > 0.0 || e.sunAltDeg.c4 > 0.0;
+function seesAnyOfIt(e, dip) {
+    return e.sunAltDeg.c1 > dip || e.sunAltDeg.peak > dip || e.sunAltDeg.c4 > dip;
 }
 /**
  * The first solar eclipse `observer` can see whose peak falls strictly after
@@ -270,8 +271,8 @@ function seesAnyOfIt(e) {
  *      interval, or if no visible eclipse remains before the end of it.
  * @throws {RangeError} if `after` is invalid or `observer` is out of range.
  */
-export function nextSolarEclipse(after, observer) {
-    return nearestSolarEclipse(after, 1, observer);
+export function nextSolarEclipse(after, observer, heightAboveGroundM = 0) {
+    return nearestSolarEclipse(after, 1, observer, heightAboveGroundM);
 }
 /**
  * The last solar eclipse `observer` can see whose peak falls strictly before
@@ -282,30 +283,30 @@ export function nextSolarEclipse(after, observer) {
  *      interval, or if no visible eclipse remains after the start of it.
  * @throws {RangeError} if `before` is invalid or `observer` is out of range.
  */
-export function previousSolarEclipse(before, observer) {
-    return nearestSolarEclipse(before, -1, observer);
+export function previousSolarEclipse(before, observer, heightAboveGroundM = 0) {
+    return nearestSolarEclipse(before, -1, observer, heightAboveGroundM);
 }
 /** Solar eclipses `observer` can see with peaks in `[startUtc, endUtc)`, sorted ascending. Contacts may fall outside the window. */
-export function solarEclipses(startUtc, endUtc, observer) {
+export function solarEclipses(startUtc, endUtc, observer, heightAboveGroundM = 0) {
     assertSupported(startUtc);
     assertSupportedWindowEnd(endUtc);
-    assertObserver(observer);
-    return scanSolarEclipses(startUtc.getTime(), endUtc.getTime(), 1, false, observer);
+    const dip = horizonDip(observer, heightAboveGroundM);
+    return scanSolarEclipses(startUtc.getTime(), endUtc.getTime(), 1, false, observer, dip);
 }
-function nearestSolarEclipse(anchor, direction, observer) {
+function nearestSolarEclipse(anchor, direction, observer, heightAboveGroundM) {
     assertSupported(anchor);
-    assertObserver(observer);
+    const dip = horizonDip(observer, heightAboveGroundM);
     const ms = anchor.getTime();
     // No scan limit: walk to the supported boundary. A place can go years
     // without a visible solar eclipse, and a pruned new moon is cheap.
     const startMs = direction > 0 ? ms + SAME_ECLIPSE_MS + 1 : SUPPORTED_MIN;
     const endMs = direction > 0 ? SUPPORTED_MAX : ms - SAME_ECLIPSE_MS;
-    const found = scanSolarEclipses(startMs, endMs, direction, true, observer);
+    const found = scanSolarEclipses(startMs, endMs, direction, true, observer, dip);
     if (found.length)
         return found[0];
     throw new AlmanacOutOfRangeError();
 }
-function scanSolarEclipses(startMs, endMs, direction, firstOnly, observer) {
+function scanSolarEclipses(startMs, endMs, direction, firstOnly, observer, dip) {
     const found = [];
     if (startMs >= endMs)
         return found;
@@ -337,7 +338,7 @@ function scanSolarEclipses(startMs, endMs, direction, firstOnly, observer) {
         // This is at least a partial solar eclipse for the observer.
         const eclipse = buildSolarEclipse(shadow, observer);
         // Ignore any eclipse that happens completely at night.
-        if (!seesAnyOfIt(eclipse))
+        if (!seesAnyOfIt(eclipse, dip))
             continue;
         found.push(eclipse);
         if (firstOnly)

package/dist/sun.d.ts

@@ -7,6 +7,10 @@ type VsopModel = [VsopFormula, VsopFormula, VsopFormula];
  * below are checked against; exported for that test only.
  */
 export declare const vsopEarth: VsopModel;
+/** UPSTREAM: `VsopRotate`, astronomy.ts lines 3234-3241 — VSOP ecliptic to J2000 equatorial. */
+export declare function vsopRotate(eclip: Vec3): Vec3;
+/** UPSTREAM: `VsopSphereToRect`, astronomy.ts lines 3243-3253. */
+export declare function vsopSphereToRect(lon: number, lat: number, radius: number): Vec3;
 /**
  * UPSTREAM: `CalcVsop`, astronomy.ts lines 3255-3262, specialised to
  * `vsop.Earth` — i.e. `HelioVector(Body.Earth, time)`. J2000 mean equator (EQJ).

package/dist/sun.js

@@ -204,7 +204,7 @@ function earthRad(t) {
     return coord;
 }
 /** UPSTREAM: `VsopRotate`, astronomy.ts lines 3234-3241 — VSOP ecliptic to J2000 equatorial. */
-function vsopRotate(eclip) {
+export function vsopRotate(eclip) {
     return {
         x: eclip.x + 0.000000440360 * eclip.y - 0.000000190919 * eclip.z,
         y: -0.000000479966 * eclip.x + 0.917482137087 * eclip.y - 0.397776982902 * eclip.z,
@@ -212,7 +212,7 @@ function vsopRotate(eclip) {
     };
 }
 /** UPSTREAM: `VsopSphereToRect`, astronomy.ts lines 3243-3253. */
-function vsopSphereToRect(lon, lat, radius) {
+export function vsopSphereToRect(lon, lat, radius) {
     // Convert spherical coordinates to ecliptic cartesian coordinates.
     const r_coslat = radius * Math.cos(lat);
     const coslon = Math.cos(lon);

package/dist/transforms.d.ts

@@ -56,6 +56,7 @@ export declare function topoAltAzUnrefracted(bodyEqj: Vec3, ut: number, observer
  * altitude never drops below -90.
  */
 export declare function refractionDeg(altitudeDeg: number): number;
+export declare function refract(unrefracted: AltAz): AltAz;
 /**
  * Topocentric azimuth/altitude of the Sun — parallax (via the observer's
  * geocentric position, WGS-84 flattening, elevation) and atmospheric

package/dist/transforms.js

@@ -182,7 +182,7 @@ export function refractionDeg(altitudeDeg) {
     }
     return refr;
 }
-function refract(unrefracted) {
+export function refract(unrefracted) {
     return { azDeg: unrefracted.azDeg, altDeg: unrefracted.altDeg + refractionDeg(unrefracted.altDeg) };
 }
 /**

package/dist/types.d.ts

@@ -3,6 +3,9 @@ export interface Observer {
     longitudeDeg: number;
     elevationM?: number;
 }
+export type Planet = 'mercury' | 'venus' | 'earth' | 'mars' | 'jupiter' | 'saturn';
+/** INTERNAL: Earth has no planetary direction from an Earth-based observer. */
+export declare function assertPlanet(planet: Planet, earthAllowed?: boolean): void;
 export declare class AlmanacOutOfRangeError extends RangeError {
     constructor(msg?: string);
 }

package/dist/types.js

@@ -1,3 +1,8 @@
+/** INTERNAL: Earth has no planetary direction from an Earth-based observer. */
+export function assertPlanet(planet, earthAllowed = false) {
+    if (!['mercury', 'venus', 'earth', 'mars', 'jupiter', 'saturn'].includes(planet) || (!earthAllowed && planet === 'earth'))
+        throw new RangeError(`invalid planet: ${planet}`);
+}
 export class AlmanacOutOfRangeError extends RangeError {
     constructor(msg = 'time outside supported interval 1950-01-01T00:00Z ≤ t < 2101-01-01T00:00Z') { super(msg); this.name = 'AlmanacOutOfRangeError'; }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.6.0",
-  "description": "Offline sun & moon engine: positions, rise/set, moon phase, lunar and solar eclipses.",
+  "version": "0.7.0",
+  "description": "Offline astronomy: Sun, Moon and planet positions, apparent horizon, rise/set, phases and eclipses.",
   "license": "MIT",
   "repository": {
     "type": "git",