@openwaters/almanac 0.6.0 → 0.8.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, any Sun altitude, upper and lower transits, Moon phase and orientation, planetary brightness, lunar and solar eclipses, and fixed-star altitude and azimuth from catalog positions, computed from pure geometry with zero network and zero runtime data files.
 
 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,13 @@ 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: **34 workloads**
 cover positions, a 228-hour sky track, short/year/polar event windows, full-range
 moon phases, next/previous/range lunar, solar, and global solar eclipse searches,
 including empty windows, solar obscuration over a 228-hour track, and the central
-line of the 2024-04-08 eclipse.
+line of the 2024-04-08 eclipse, five-planet sky tracks, planetary rise/set, a
+year of golden-hour crossings and Sun and Moon transits, and a 228-hour Moon
+orientation track.
 
 Event searches find altitude extrema with Brent's method and altitude crossings
 with a cosine-seeded secant solver, each root proven inside a half-second
@@ -49,10 +51,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|suncalc)/'
 ```
 
-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, planetary, and SunCalc-parity workloads absent from that base. Use `--skip '^(solar|global|planets|suncalc)/'` when the base predates 0.4.0, which is when the solar eclipse workloads arrived. For a base that lacks only the SunCalc-parity APIs, use `--skip '^suncalc/'`.
 
 CI runs the harness on code changes and fails on **median regressions over 20%**.
 Results include timing tables, raw samples, checksums, and revision/toolchain
@@ -64,6 +66,10 @@ background task; use shorter windows for interactive queries.
 
 ## Usage
 
+Migrating from SunCalc: [`docs/migrating-from-suncalc.md`](docs/migrating-from-suncalc.md) maps every SunCalc call to Almanac and gives drop-in `getTimes` and `getMoonTimes` adapters. Migrating from Solar: [`docs/migrating-from-solar.md`](docs/migrating-from-solar.md). How Almanac compares with SunCalc, Astronomy Engine, astronomia, Solar, SwiftAA, and EDSunriseSet, and when each is the better choice: [`docs/comparison.md`](docs/comparison.md).
+
+Migrating from the Solar Swift library: [`docs/migrating-from-solar.md`](docs/migrating-from-solar.md) maps every Solar property to Almanac and gives a drop-in `Solar` adapter.
+
 ### TypeScript
 
 ```bash
@@ -98,10 +104,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.8.0")
 ```
 
 ```swift
@@ -134,6 +151,65 @@ 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)
 ```
 
+### Golden hour, transits, and the Moon's tilt
+
+`sunAltitudeEvents` finds the Sun's center crossing any altitude, with the twilight convention, so `6` gives golden hour and `-6` civil twilight. `sunTransits` and `moonTransits` give each body's highest (`upper`) and lowest (`lower`) meridian crossings. `moonOrientation` turns the Moon's disc: subtracting the parallactic angle from the bright-limb angle gives the bright limb's direction from the zenith.
+
+```ts
+import { sunAltitudeEvents, sunTransits, moonTransits, moonOrientation } from '@openwaters/almanac';
+const golden = sunAltitudeEvents(today, tomorrow, observer, 6);       // 'rising' ends morning golden hour, 'falling' starts the evening one
+const solarMidnight = sunTransits(today, tomorrow, observer).find(e => e.kind === 'lower');
+const moonHighest = moonTransits(today, tomorrow, observer).find(e => e.kind === 'upper');
+const { brightLimbAngleDeg, parallacticAngleDeg } = moonOrientation(today, observer);
+const brightLimbFromZenithDeg = brightLimbAngleDeg - parallacticAngleDeg;
+```
+
+```swift
+let golden = try sunAltitudeEvents(from: today, to: tomorrow, observer: observer, altitudeDeg: 6)
+let solarMidnight = try sunTransits(from: today, to: tomorrow, observer: observer).first { $0.kind == .lower }
+let moonHighest = try moonTransits(from: today, to: tomorrow, observer: observer).first { $0.kind == .upper }
+let orientation = try moonOrientation(at: today, observer: observer)
+let brightLimbFromZenithDeg = orientation.brightLimbAngleDeg - orientation.parallacticAngleDeg
+```
+
+### Planetary views
+
+Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune have geometric Sun-centered positions in AU, in fixed J2000 equatorial coordinates. Place the Sun at `(0, 0, 0)` and orient the scene's camera for the desired view:
+
+```ts
+import { planetHeliocentricPosition, planetAltAz, planetIllumination, planetEvents,
+  horizonDip, sunAltAz } from '@openwaters/almanac';
+import type { Planet } from '@openwaters/almanac';
+
+const planets: Planet[] = ['mercury', 'venus', 'earth', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune'];
+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,24 @@ 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;
+}
+/** The Sun's center crossing a caller-chosen altitude, upward or downward. */
+export type AltitudeEventKind = 'rising' | 'falling';
+export interface AltitudeEvent {
+    time: Date;
+    kind: AltitudeEventKind;
+}
+/** A body crossing the local meridian: highest at `upper`, lowest at `lower`. */
+export type TransitEventKind = 'upper' | 'lower';
+export interface TransitEvent {
+    time: Date;
+    kind: TransitEventKind;
+}
 /** A quarter lunar phase. */
 export type MoonPhaseName = 'new' | 'firstQuarter' | 'full' | 'lastQuarter';
 export interface MoonPhaseEvent {
@@ -41,7 +59,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 +67,36 @@ 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[];
+/**
+ * The Sun's unrefracted geometric center crossing `altitudeDeg` within the
+ * half-open window `[startUtc, endUtc)`, sorted ascending: `rising` upward,
+ * `falling` downward. The twilight convention, so `-6` returns the civil
+ * twilight instants. A window with no crossing, as in polar day or night,
+ * returns an empty list.
+ */
+export declare function sunAltitudeEvents(startUtc: Date, endUtc: Date, observer: Observer, altitudeDeg: number): AltitudeEvent[];
+/**
+ * The Sun's upper (local hour angle 0) and lower (180°) transits within the
+ * half-open window `[startUtc, endUtc)`, sorted ascending, whether or not the
+ * Sun is above the horizon. The upper transit is `sunEvents`' `transit`.
+ */
+export declare function sunTransits(startUtc: Date, endUtc: Date, observer: Observer): TransitEvent[];
+/**
+ * The Moon's upper and lower transits within the half-open window
+ * `[startUtc, endUtc)`, sorted ascending, from the topocentric hour angle, so
+ * parallax is included, whether or not the Moon is above the horizon.
+ */
+export declare function moonTransits(startUtc: Date, endUtc: Date, observer: Observer): TransitEvent[];
 /**
  * UPSTREAM: `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 { assertObserver, assertPlanet, assertSupported, assertSupportedWindowEnd, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
 import { dateFromUt, ttDaysFromUt, utDays } from './time.js';
 import { DEG2RAD, KM_PER_AU, RAD2DEG } from './nutation.js';
 import { topoAltAzUnrefracted } from './transforms.js';
 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);
 }
@@ -404,9 +412,12 @@ function secantCrossing(f, a, b, s0, s1, targetDeg) {
  * solving every monotonic segment between consecutive extrema for every target
  * level. The chain starts a full cycle before `startUt` so the segment
  * containing the window's first instant is covered, and runs one extremum past
- * `endUt` so an event just inside the window's end is too.
+ * `endUt` so an event just inside the window's end is too. `transitKind` is
+ * emitted at each hour angle 0 and `lowerTransitKind` at each hour angle 180.
+ * With no levels the extrema are never refined: the hour-angle chain alone
+ * places the transits.
  */
-function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRateDegPerDay, cycleDays, flatCycle) {
+function searchAltitudeEvents(sample, levels, transitKind, lowerTransitKind, startUt, endUt, haRateDegPerDay, cycleDays, flatCycle) {
     const extremumHalfWidthDays = flatCycle ? cycleDays / 2 : EXTREMUM_HALF_WIDTH_DAYS;
     const found = [];
     const emit = (ut, kind) => {
@@ -430,7 +441,8 @@ function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRat
         // extremum we are not allowed to probe past. The segment up to it is
         // still monotonic, so any crossing inside the window is still found.
         const s1 = atRangeEnd ? sample(MAX_UT)
-            : refineExtremum(sample, nextEst, nextIsMax, extremumHalfWidthDays, s0.ut, flatCycle);
+            : levels.length === 0 ? sample(nextEst)
+                : refineExtremum(sample, nextEst, nextIsMax, extremumHalfWidthDays, s0.ut, flatCycle);
         assertReached(s1.ut > s0.ut, 'extremum chain ordering');
         // Earlier extrema still establish the chain, but their crossings cannot be emitted.
         if (quantizedUt(s1.ut) >= startUt) {
@@ -442,8 +454,9 @@ function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRat
                 emit(solveCrossing(sample, spec.level, s0, s1), g1 > 0 ? spec.rising : spec.falling);
             }
         }
-        if (nextIsMax && transitKind !== null && !atRangeEnd)
-            emit(nextEst, transitKind);
+        const transit = nextIsMax ? transitKind : lowerTransitKind;
+        if (transit !== null && !atRangeEnd)
+            emit(nextEst, transit);
         s0 = s1;
         if (atRangeEnd)
             break;
@@ -469,7 +482,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 +490,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', null, utDays(startUtc), utDays(endUtc), SUN_HA_RATE_DEG_PER_DAY, SUN_CYCLE_DAYS, flatCycle(observer));
 }
 /**
  * Moonrise and moonset within the half-open window `[startUtc, endUtc)`,
@@ -491,13 +504,68 @@ 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, 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);
+    const dip = horizonDip(observer, heightAboveGroundM);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    const cycleDays = 0.9972695717592592;
+    return searchAltitudeEvents(planetSampler(planet, observer, dip), MOON_LEVELS, null, null, utDays(startUtc), utDays(endUtc), 360 / cycleDays, cycleDays, flatCycle(observer));
+}
+/**
+ * The Sun's unrefracted geometric center crossing `altitudeDeg` within the
+ * half-open window `[startUtc, endUtc)`, sorted ascending: `rising` upward,
+ * `falling` downward. The twilight convention, so `-6` returns the civil
+ * twilight instants. A window with no crossing, as in polar day or night,
+ * returns an empty list.
+ */
+export function sunAltitudeEvents(startUtc, endUtc, observer, altitudeDeg) {
+    if (!(altitudeDeg >= -90 && altitudeDeg <= 90))
+        throw new RangeError(`altitudeDeg out of range: ${altitudeDeg}`);
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    assertObserver(observer);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    const levels = [{ level: altitudeDeg, rising: 'rising', falling: 'falling' }];
+    return searchAltitudeEvents(sunSampler(observer, 0), levels, null, null, utDays(startUtc), utDays(endUtc), SUN_HA_RATE_DEG_PER_DAY, SUN_CYCLE_DAYS, flatCycle(observer));
+}
+/**
+ * The Sun's upper (local hour angle 0) and lower (180°) transits within the
+ * half-open window `[startUtc, endUtc)`, sorted ascending, whether or not the
+ * Sun is above the horizon. The upper transit is `sunEvents`' `transit`.
+ */
+export function sunTransits(startUtc, endUtc, observer) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    assertObserver(observer);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    return searchAltitudeEvents(sunSampler(observer, 0), [], 'upper', 'lower', utDays(startUtc), utDays(endUtc), SUN_HA_RATE_DEG_PER_DAY, SUN_CYCLE_DAYS, flatCycle(observer));
+}
+/**
+ * The Moon's upper and lower transits within the half-open window
+ * `[startUtc, endUtc)`, sorted ascending, from the topocentric hour angle, so
+ * parallax is included, whether or not the Moon is above the horizon.
+ */
+export function moonTransits(startUtc, endUtc, observer) {
     assertSupported(startUtc);
     assertSupportedWindowEnd(endUtc);
     assertObserver(observer);
     if (startUtc.getTime() >= endUtc.getTime())
         return [];
-    return searchAltitudeEvents(moonSampler(observer), MOON_LEVELS, null, utDays(startUtc), utDays(endUtc), MOON_HA_RATE_DEG_PER_DAY, MOON_CYCLE_DAYS, flatCycle(observer));
+    return searchAltitudeEvents(moonSampler(observer, 0), [], 'upper', 'lower', utDays(startUtc), utDays(endUtc), MOON_HA_RATE_DEG_PER_DAY, MOON_CYCLE_DAYS, 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,5 @@
+import { Observer } from './types.js';
+import { Vec3 } from './nutation.js';
 /** Moon illumination at an instant. `phase` is 0 at new moon, 0.5 at full. */
 export interface MoonIllumination {
     fraction: number;
@@ -5,6 +7,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
@@ -30,3 +34,21 @@ export declare function moonIlluminationAtTT(tt: number): MoonIllumination;
  * phase (0 = new, 0.5 = full, `waxing` = phase < 0.5).
  */
 export declare function moonIllumination(time: Date): MoonIllumination;
+/**
+ * How the Moon's disc is turned on the observer's sky. `brightLimbAngleDeg` is
+ * the position angle of the bright limb's midpoint from celestial north
+ * through east, in [0, 360); `parallacticAngleDeg` is the angle at the Moon
+ * from celestial north to the observer's zenith, in (-180, 180]. Their
+ * difference is the bright limb's angle from the zenith.
+ */
+export interface MoonOrientation {
+    brightLimbAngleDeg: number;
+    parallacticAngleDeg: number;
+}
+/**
+ * The Moon's orientation at an instant: the bright limb from the apparent
+ * topocentric Moon and the apparent geocentric Sun (Meeus, Astronomical
+ * Algorithms, 48.5), and the parallactic angle from the Moon's topocentric
+ * hour angle and declination at the observer's geodetic latitude (Meeus 14.1).
+ */
+export declare function moonOrientation(time: Date, observer: Observer): MoonOrientation;

package/dist/illumination.js

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

package/dist/index.d.ts

@@ -1,13 +1,16 @@
-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';
 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 { MoonIllumination, MoonOrientation } from './illumination.js';
+export { moonIllumination, moonOrientation } from './illumination.js';
+export type { SunEvent, SunEventKind, MoonEvent, MoonEventKind, MoonPhaseEvent, MoonPhaseName, PlanetEvent, PlanetEventKind, AltitudeEvent, AltitudeEventKind, TransitEvent, TransitEventKind } from './events.js';
+export { sunEvents, moonEvents, searchMoonPhases, planetEvents, sunAltitudeEvents, sunTransits, moonTransits } from './events.js';
 export 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 { moonIllumination, moonOrientation } from './illumination.js';
+export { sunEvents, moonEvents, searchMoonPhases, planetEvents, sunAltitudeEvents, sunTransits, moonTransits } from './events.js';
 export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';
 export { nextSolarEclipse, previousSolarEclipse, solarEclipses, solarObscuration } from './solar.js';
 export { nextGlobalSolarEclipse, previousGlobalSolarEclipse, globalSolarEclipses, solarEclipseAxisPoint, solarEclipseCentralLine } from './globalSolar.js';

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