caelus 0.11.0 → 0.13.0

package/dist/src/core.d.ts

@@ -59,9 +59,40 @@ export interface EngineData {
     /** Fixed-star catalog (HYG-derived; ICRS J2000 + proper motions). */
     fixedStars?: import("./stars.js").StarPack;
 }
+/**
+ * Convert a UT calendar date and time to a Julian Day (UT) — the time
+ * coordinate the engine consumes. Pass the result to {@link Engine.position},
+ * {@link Engine.longitude}, {@link Engine.chartAt}, and the event/derived
+ * functions; {@link Engine.chart} takes the calendar fields directly instead.
+ *
+ * Arguments are **UT**, not local civil time — convert a local time to UT
+ * first (see the `caelus-birth` package). Uses the proleptic Gregorian
+ * calendar.
+ *
+ * @param y Year in UT, e.g. `1990`.
+ * @param mo Month, `1`–`12`.
+ * @param d Day of month, `1`–`31`.
+ * @param h Hour, `0`–`23`. Defaults to `0`.
+ * @param mi Minute, `0`–`59`. Defaults to `0`.
+ * @param s Second, `0`–`59`. Defaults to `0`.
+ * @returns The Julian Day in UT (a fractional day count).
+ * @example
+ * ```ts
+ * const jd = julianDay(2025, 6, 1, 12, 0, 0); // 2025-06-01 12:00 UT
+ * engine.longitude("sun", jd);
+ * ```
+ */
 export declare function julianDay(y: number, mo: number, d: number, h?: number, mi?: number, s?: number): number;
-/** TT - UT1 in seconds. Observed IERS 1955-2025, E&M polynomials before,
- *  gentle extrapolation after (Earth's rotation sped up post-2016). */
+/**
+ * ΔT (TT − UT1) in seconds at a given instant — the gap between Terrestrial
+ * Time and universal time. Observed IERS values 1955–2025, Espenak–Meeus
+ * polynomials before, and a gentle extrapolation after (Earth's rotation sped
+ * up post-2016). The engine applies this for you; call it directly only for
+ * timescale work.
+ *
+ * @param jdUt Julian Day (UT).
+ * @returns ΔT in seconds.
+ */
 export declare function deltaT(jdUt: number): number;
 export declare function jdTT(jdUt: number): number;
 export declare function vsopHeliocentric(series: VsopSeries, jde: number): [number, number, number];

package/dist/src/core.js

@@ -17,6 +17,29 @@ export function mod(a, b) {
     return r !== 0 && (r < 0) !== (b < 0) ? r + b : r;
 }
 // ---------------------------------------------------------------- timescale
+/**
+ * Convert a UT calendar date and time to a Julian Day (UT) — the time
+ * coordinate the engine consumes. Pass the result to {@link Engine.position},
+ * {@link Engine.longitude}, {@link Engine.chartAt}, and the event/derived
+ * functions; {@link Engine.chart} takes the calendar fields directly instead.
+ *
+ * Arguments are **UT**, not local civil time — convert a local time to UT
+ * first (see the `caelus-birth` package). Uses the proleptic Gregorian
+ * calendar.
+ *
+ * @param y Year in UT, e.g. `1990`.
+ * @param mo Month, `1`–`12`.
+ * @param d Day of month, `1`–`31`.
+ * @param h Hour, `0`–`23`. Defaults to `0`.
+ * @param mi Minute, `0`–`59`. Defaults to `0`.
+ * @param s Second, `0`–`59`. Defaults to `0`.
+ * @returns The Julian Day in UT (a fractional day count).
+ * @example
+ * ```ts
+ * const jd = julianDay(2025, 6, 1, 12, 0, 0); // 2025-06-01 12:00 UT
+ * engine.longitude("sun", jd);
+ * ```
+ */
 export function julianDay(y, mo, d, h = 0, mi = 0, s = 0) {
     const frac = (h + mi / 60.0 + s / 3600.0) / 24.0;
     if (mo <= 2) {
@@ -33,8 +56,16 @@ const DT_OBS = [
     [1980, 50.5], [1985, 54.3], [1990, 56.9], [1995, 60.8], [2000, 63.8],
     [2005, 64.7], [2010, 66.1], [2015, 67.6], [2020, 69.4], [2025, 69.2],
 ];
-/** TT - UT1 in seconds. Observed IERS 1955-2025, E&M polynomials before,
- *  gentle extrapolation after (Earth's rotation sped up post-2016). */
+/**
+ * ΔT (TT − UT1) in seconds at a given instant — the gap between Terrestrial
+ * Time and universal time. Observed IERS values 1955–2025, Espenak–Meeus
+ * polynomials before, and a gentle extrapolation after (Earth's rotation sped
+ * up post-2016). The engine applies this for you; call it directly only for
+ * timescale work.
+ *
+ * @param jdUt Julian Day (UT).
+ * @returns ΔT in seconds.
+ */
 export function deltaT(jdUt) {
     const y = 2000.0 + (jdUt - J2000) / 365.25;
     if (y >= 1955 && y <= 2025) {

package/dist/src/derived.d.ts

@@ -5,11 +5,50 @@ export declare function midpointLon(a: number, b: number): number;
 /** UT JDs in [jdStart, jdEnd] when `body` returns to its natal longitude.
  *  Outer-planet returns can show three crossings around a retrograde loop. */
 export declare function returns(engine: Engine, body: BodyId, natalJd: number, jdStart: number, jdEnd: number, zodiac?: Zodiac, maxHits?: number): number[];
+/**
+ * Solar-return instants in `[jdStart, jdEnd]`: the times the Sun returns to its
+ * natal longitude (about once a year). Build a chart at each with
+ * {@link Engine.chartAt} for the solar-return chart.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param natalJd Natal Julian Day (UT) — defines the target Sun longitude.
+ * @param jdStart Start of the search window, Julian Day (UT).
+ * @param jdEnd End of the search window, Julian Day (UT).
+ * @param zodiac Zodiac for the longitude match. Defaults to tropical.
+ * @returns Return instants as Julian Days (UT), sorted.
+ * @example
+ * ```ts
+ * const natal = julianDay(1990, 6, 10, 14, 30);
+ * const [thisYear] = solarReturn(engine, natal, julianDay(2025, 1, 1), julianDay(2026, 1, 1));
+ * const returnChart = engine.chartAt(thisYear, 27.95, -82.46);
+ * ```
+ * @see {@link lunarReturn} for the monthly Moon return.
+ */
 export declare function solarReturn(engine: Engine, natalJd: number, jdStart: number, jdEnd: number, zodiac?: Zodiac): number[];
 export declare function lunarReturn(engine: Engine, natalJd: number, jdStart: number, jdEnd: number, zodiac?: Zodiac): number[];
 /** The JD whose real positions are the secondary-progressed positions for the
  *  age (targetJd - natalJd): one day of motion per year of life. */
 export declare function progressedJd(natalJd: number, targetJd: number, yearLength?: number): number;
+/**
+ * Secondary-progressed longitude of a body for a given target date: the
+ * "day-for-a-year" method, where one day of real motion after birth maps to one
+ * year of life. Equivalent to taking the body's longitude at
+ * {@link progressedJd}.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param body A body id from {@link Engine.bodies}.
+ * @param natalJd Natal Julian Day (UT).
+ * @param targetJd The date to progress to, Julian Day (UT).
+ * @param yearLength Days per year of life. Defaults to the tropical year.
+ * @param zodiac Zodiac for the result. Defaults to tropical.
+ * @returns The progressed ecliptic longitude in degrees, `[0, 360)`.
+ * @example
+ * ```ts
+ * const natal = julianDay(1990, 6, 10, 14, 30);
+ * progressedLongitude(engine, "moon", natal, julianDay(2025, 6, 10));
+ * ```
+ * @see {@link solarArc} and {@link directedLongitude} for solar-arc directions.
+ */
 export declare function progressedLongitude(engine: Engine, body: BodyId, natalJd: number, targetJd: number, yearLength?: number, zodiac?: Zodiac): number;
 /** Solar-arc direction angle (degrees, forward): how far the secondary-
  *  progressed Sun has moved from the natal Sun. Add it to any natal longitude. */
@@ -24,6 +63,22 @@ export declare function compositeLongitudes(engine: Engine, jdA: number, jdB: nu
 export declare function davisonParams(jdA: number, jdB: number, latA: number, lonEastA: number, latB: number, lonEastB: number): [number, number, number];
 /** The nth-harmonic longitude of a point: lon * n, wrapped to 360. */
 export declare function harmonicLongitude(lon: number, n: number): number;
+/**
+ * The nth-harmonic chart: each body's longitude multiplied by `n` and wrapped
+ * to `[0, 360)`. The 5th harmonic surfaces quintiles, the 9th the navamsa, and
+ * so on.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Julian Day (UT).
+ * @param bodies The bodies to include.
+ * @param n The harmonic number, e.g. `5` or `9`.
+ * @param zodiac Zodiac for the base longitudes. Defaults to tropical.
+ * @returns Harmonic longitudes in degrees, keyed by body id.
+ * @example
+ * ```ts
+ * harmonicChart(engine, jd, ["sun", "moon", "venus"], 5); // quintile harmonic
+ * ```
+ */
 export declare function harmonicChart(engine: Engine, jd: number, bodies: BodyId[], n: number, zodiac?: Zodiac): Record<string, number>;
 /** Reflection across the solstice (Cancer-Capricorn) axis. */
 export declare function antiscion(lon: number): number;
@@ -37,15 +92,49 @@ export interface DeclinationPair {
     b: string;
     kind: DeclinationKind;
 }
+/**
+ * Parallels and contraparallels among a set of bodies at an instant: pairs
+ * whose declinations are equal (parallel) or equal and opposite
+ * (contraparallel) within `orb` — the declination analogue of conjunction and
+ * opposition.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param bodies The bodies to compare.
+ * @param jd Julian Day (UT).
+ * @param orb Declination orb in degrees. Defaults to `1.0`.
+ * @returns {@link DeclinationPair}s `{ a, b, kind }`, where `kind` is
+ *   `"parallel"` or `"contraparallel"`.
+ */
 export declare function declinationAspects(engine: Engine, bodies: BodyId[], jd: number, orb?: number): DeclinationPair[];
 /** |declination| minus the mean obliquity, degrees. Positive = out of bounds. */
 export declare function outOfBoundsMargin(engine: Engine, body: BodyId, jd: number): number;
 export declare function outOfBounds(engine: Engine, body: BodyId, jd: number): boolean;
-/** Essential dignities of `body` in `sign`: domicile, exaltation, detriment,
- *  fall (the last two are the signs opposite domicile and exaltation). */
+/**
+ * Essential dignities a body holds in a sign: any of `"domicile"`,
+ * `"exaltation"`, `"detriment"`, `"fall"` (the last two are the signs opposite
+ * domicile and exaltation). Empty when the body is peregrine there.
+ *
+ * @param body Body id, e.g. `"mars"`.
+ * @param sign A sign index `0`–`11` (Aries = 0) or its name, e.g. `"Aries"`.
+ * @returns The dignities held, in the order above; empty if none.
+ * @example
+ * ```ts
+ * dignities("mars", "Aries"); // ["domicile"]
+ * dignities("sun", "Libra");  // ["fall"]
+ * ```
+ */
 export declare function dignities(body: string, sign: number | string): string[];
 export declare function dignityOf(engine: Engine, body: BodyId, jd: number, zodiac?: Zodiac): string[];
 /** Diurnal when the Sun is above the horizon at the given place. */
 export declare function isDayChart(engine: Engine, jd: number, lat: number, lonEast: number): boolean;
+/**
+ * The sect a body belongs to: `"diurnal"` (Sun, Jupiter, Saturn),
+ * `"nocturnal"` (Moon, Venus, Mars), or `null` for Mercury and bodies without a
+ * fixed sect. Whether a chart is itself day or night — the Sun above or below
+ * the horizon — is a separate question.
+ *
+ * @param body Body id.
+ * @returns `"diurnal"`, `"nocturnal"`, or `null`.
+ */
 export declare function planetarySect(body: string): "diurnal" | "nocturnal" | null;
 export declare function inSect(body: string, dayChart: boolean): boolean | null;

package/dist/src/derived.js

@@ -25,6 +25,25 @@ export function returns(engine, body, natalJd, jdStart, jdEnd, zodiac = "tropica
     const natalLon = engine.longitude(body, natalJd, { zodiac });
     return crossings(engine, body, natalLon, jdStart, jdEnd, zodiac, maxHits);
 }
+/**
+ * Solar-return instants in `[jdStart, jdEnd]`: the times the Sun returns to its
+ * natal longitude (about once a year). Build a chart at each with
+ * {@link Engine.chartAt} for the solar-return chart.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param natalJd Natal Julian Day (UT) — defines the target Sun longitude.
+ * @param jdStart Start of the search window, Julian Day (UT).
+ * @param jdEnd End of the search window, Julian Day (UT).
+ * @param zodiac Zodiac for the longitude match. Defaults to tropical.
+ * @returns Return instants as Julian Days (UT), sorted.
+ * @example
+ * ```ts
+ * const natal = julianDay(1990, 6, 10, 14, 30);
+ * const [thisYear] = solarReturn(engine, natal, julianDay(2025, 1, 1), julianDay(2026, 1, 1));
+ * const returnChart = engine.chartAt(thisYear, 27.95, -82.46);
+ * ```
+ * @see {@link lunarReturn} for the monthly Moon return.
+ */
 export function solarReturn(engine, natalJd, jdStart, jdEnd, zodiac = "tropical") {
     return returns(engine, "sun", natalJd, jdStart, jdEnd, zodiac);
 }
@@ -37,6 +56,26 @@ export function lunarReturn(engine, natalJd, jdStart, jdEnd, zodiac = "tropical"
 export function progressedJd(natalJd, targetJd, yearLength = TROPICAL_YEAR) {
     return natalJd + (targetJd - natalJd) / yearLength;
 }
+/**
+ * Secondary-progressed longitude of a body for a given target date: the
+ * "day-for-a-year" method, where one day of real motion after birth maps to one
+ * year of life. Equivalent to taking the body's longitude at
+ * {@link progressedJd}.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param body A body id from {@link Engine.bodies}.
+ * @param natalJd Natal Julian Day (UT).
+ * @param targetJd The date to progress to, Julian Day (UT).
+ * @param yearLength Days per year of life. Defaults to the tropical year.
+ * @param zodiac Zodiac for the result. Defaults to tropical.
+ * @returns The progressed ecliptic longitude in degrees, `[0, 360)`.
+ * @example
+ * ```ts
+ * const natal = julianDay(1990, 6, 10, 14, 30);
+ * progressedLongitude(engine, "moon", natal, julianDay(2025, 6, 10));
+ * ```
+ * @see {@link solarArc} and {@link directedLongitude} for solar-arc directions.
+ */
 export function progressedLongitude(engine, body, natalJd, targetJd, yearLength = TROPICAL_YEAR, zodiac = "tropical") {
     return engine.longitude(body, progressedJd(natalJd, targetJd, yearLength), { zodiac });
 }
@@ -82,6 +121,22 @@ export function davisonParams(jdA, jdB, latA, lonEastA, latB, lonEastB) {
 export function harmonicLongitude(lon, n) {
     return mod(lon * n, 360);
 }
+/**
+ * The nth-harmonic chart: each body's longitude multiplied by `n` and wrapped
+ * to `[0, 360)`. The 5th harmonic surfaces quintiles, the 9th the navamsa, and
+ * so on.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Julian Day (UT).
+ * @param bodies The bodies to include.
+ * @param n The harmonic number, e.g. `5` or `9`.
+ * @param zodiac Zodiac for the base longitudes. Defaults to tropical.
+ * @returns Harmonic longitudes in degrees, keyed by body id.
+ * @example
+ * ```ts
+ * harmonicChart(engine, jd, ["sun", "moon", "venus"], 5); // quintile harmonic
+ * ```
+ */
 export function harmonicChart(engine, jd, bodies, n, zodiac = "tropical") {
     const out = {};
     for (const b of bodies)
@@ -105,6 +160,19 @@ export function declinationAspect(decA, decB, orb = 1.0) {
         return "contraparallel";
     return null;
 }
+/**
+ * Parallels and contraparallels among a set of bodies at an instant: pairs
+ * whose declinations are equal (parallel) or equal and opposite
+ * (contraparallel) within `orb` — the declination analogue of conjunction and
+ * opposition.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param bodies The bodies to compare.
+ * @param jd Julian Day (UT).
+ * @param orb Declination orb in degrees. Defaults to `1.0`.
+ * @returns {@link DeclinationPair}s `{ a, b, kind }`, where `kind` is
+ *   `"parallel"` or `"contraparallel"`.
+ */
 export function declinationAspects(engine, bodies, jd, orb = 1.0) {
     const decs = {};
     for (const b of bodies)
@@ -140,8 +208,20 @@ const EXALTATION = {
 function signIndex(sign) {
     return typeof sign === "number" ? sign : SIGNS.indexOf(sign);
 }
-/** Essential dignities of `body` in `sign`: domicile, exaltation, detriment,
- *  fall (the last two are the signs opposite domicile and exaltation). */
+/**
+ * Essential dignities a body holds in a sign: any of `"domicile"`,
+ * `"exaltation"`, `"detriment"`, `"fall"` (the last two are the signs opposite
+ * domicile and exaltation). Empty when the body is peregrine there.
+ *
+ * @param body Body id, e.g. `"mars"`.
+ * @param sign A sign index `0`–`11` (Aries = 0) or its name, e.g. `"Aries"`.
+ * @returns The dignities held, in the order above; empty if none.
+ * @example
+ * ```ts
+ * dignities("mars", "Aries"); // ["domicile"]
+ * dignities("sun", "Libra");  // ["fall"]
+ * ```
+ */
 export function dignities(body, sign) {
     const idx = signIndex(sign);
     const dom = DOMICILE[body] ?? [];
@@ -169,6 +249,15 @@ export function isDayChart(engine, jd, lat, lonEast) {
     const [, alt] = azAlt(engine.data, sun.lon, sun.lat, jd, lat, lonEast);
     return alt > 0;
 }
+/**
+ * The sect a body belongs to: `"diurnal"` (Sun, Jupiter, Saturn),
+ * `"nocturnal"` (Moon, Venus, Mars), or `null` for Mercury and bodies without a
+ * fixed sect. Whether a chart is itself day or night — the Sun above or below
+ * the horizon — is a separate question.
+ *
+ * @param body Body id.
+ * @returns `"diurnal"`, `"nocturnal"`, or `null`.
+ */
 export function planetarySect(body) {
     if (DIURNAL.has(body))
         return "diurnal";

package/dist/src/directions.d.ts

@@ -0,0 +1,27 @@
+import { Engine, BodyId } from "./chart.js";
+/** Degrees of arc that equal one year of life, per time key. */
+export declare const KEYS: Record<string, number>;
+export declare const TRADITIONAL: BodyId[];
+export interface DirectionArcs {
+    mc: number;
+    ic: number;
+    asc: number | null;
+    dsc: number | null;
+}
+/** Direct primary-direction arcs (degrees, [0, 360)) of a body at right
+ *  ascension `alpha` and declination `delta` to the four angles, for latitude
+ *  `phi` and right ascension of the MC `ramc`. `asc`/`dsc` are null when the
+ *  body is circumpolar. */
+export declare function directionArcs(alpha: number, delta: number, ramc: number, phi: number): DirectionArcs;
+/** Years of life corresponding to an arc of direction under a time key. */
+export declare function directionYears(arc: number, key?: string): number;
+export interface PrimaryDirection {
+    body: string;
+    angle: "MC" | "IC" | "ASC" | "DSC";
+    arc: number;
+    years: number;
+    jd: number;
+}
+/** Direct primary directions of the bodies to the four angles within
+ *  `maxYears`, by the given time key, sorted by years. */
+export declare function primaryDirections(engine: Engine, natalJd: number, lat: number, lonEast: number, bodies?: BodyId[], key?: string, maxYears?: number, yearLength?: number): PrimaryDirection[];

package/dist/src/directions.js

@@ -0,0 +1,69 @@
+/**
+ * astroengine directions -- primary directions to the angles.
+ *
+ * Primary (mundane) directions carry a planet, by the diurnal rotation of the
+ * sphere, to one of the four angles; the arc of rotation, converted by a time
+ * key, gives the age of the direction. This covers the well-defined subset:
+ * direct directions of a body to the MC, IC, Ascendant, and Descendant.
+ *
+ * For a body at right ascension alpha and declination delta, latitude phi, and
+ * right ascension of the MC (ramc): arc to MC = alpha - ramc; to IC = that
+ * - 180; to the Ascendant = alpha - AD - ramc - 90; to the Descendant =
+ * alpha + AD - ramc + 90, where AD = asin(tan phi * tan delta) is the
+ * ascensional difference. A circumpolar body (|tan phi * tan delta| > 1) has no
+ * oblique ascension, so its Ascendant/Descendant directions are undefined. Time
+ * keys: Ptolemy 1 deg = 1 year, Naibod 0.9856473 deg = 1 year. Mirrors the
+ * Python reference (astroengine/directions.py); the golden fixtures pin them.
+ */
+import { angles } from "./houses.js";
+const RAD = Math.PI / 180;
+const DEG = 180 / Math.PI;
+/** Degrees of arc that equal one year of life, per time key. */
+export const KEYS = { ptolemy: 1.0, naibod: 0.9856473 };
+export const TRADITIONAL = ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn"];
+const YEAR_DAYS = 365.2422;
+const mod360 = (x) => ((x % 360) + 360) % 360;
+/** Direct primary-direction arcs (degrees, [0, 360)) of a body at right
+ *  ascension `alpha` and declination `delta` to the four angles, for latitude
+ *  `phi` and right ascension of the MC `ramc`. `asc`/`dsc` are null when the
+ *  body is circumpolar. */
+export function directionArcs(alpha, delta, ramc, phi) {
+    const arcMc = mod360(alpha - ramc);
+    const arcIc = mod360(alpha - ramc - 180);
+    const t = Math.tan(phi * RAD) * Math.tan(delta * RAD);
+    if (Math.abs(t) > 1)
+        return { mc: arcMc, ic: arcIc, asc: null, dsc: null };
+    const ad = Math.asin(t) * DEG;
+    return {
+        mc: arcMc, ic: arcIc,
+        asc: mod360(alpha - ad - ramc - 90),
+        dsc: mod360(alpha + ad - ramc + 90),
+    };
+}
+/** Years of life corresponding to an arc of direction under a time key. */
+export function directionYears(arc, key = "naibod") {
+    return arc / KEYS[key];
+}
+/** Direct primary directions of the bodies to the four angles within
+ *  `maxYears`, by the given time key, sorted by years. */
+export function primaryDirections(engine, natalJd, lat, lonEast, bodies = TRADITIONAL, key = "naibod", maxYears = 90, yearLength = YEAR_DAYS) {
+    const armc = angles(engine.data, natalJd, lat, lonEast)[2];
+    const ramc = armc * DEG;
+    const out = [];
+    const ANGLES = ["mc", "ic", "asc", "dsc"];
+    for (const b of bodies) {
+        const p = engine.position(b, natalJd);
+        const arcs = directionArcs(p.ra, p.dec, ramc, lat);
+        for (const angle of ANGLES) {
+            const arc = arcs[angle];
+            if (arc === null)
+                continue;
+            const years = directionYears(arc, key);
+            if (years <= maxYears) {
+                out.push({ body: b, angle: angle.toUpperCase(), arc, years, jd: natalJd + years * yearLength });
+            }
+        }
+    }
+    out.sort((a, b) => a.years - b.years);
+    return out;
+}

package/dist/src/eclipses.d.ts

@@ -20,5 +20,21 @@ export interface SolarEclipse {
 }
 /** Lunar eclipses in [jdStart, jdEnd] (UT JDs). */
 export declare function lunarEclipses(engine: Engine, jdStart: number, jdEnd: number): LunarEclipse[];
-/** Solar eclipses (global circumstances) in [jdStart, jdEnd] (UT JDs). */
+/**
+ * Solar eclipses in `[jdStart, jdEnd]`, with global circumstances (not
+ * local visibility). Each new Moon in the window is tested for an eclipse and,
+ * when found, classified by the Moon's shadow geometry.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jdStart Start of the window, Julian Day (UT).
+ * @param jdEnd End of the window, Julian Day (UT).
+ * @returns {@link SolarEclipse} records: `tMax` (greatest eclipse, JD UT),
+ *   `type` (`"total"`/`"annular"`/`"hybrid"`/`"partial"`), `gamma` (minimum
+ *   shadow-axis distance in Earth radii), and the `begin`/`end` JDs.
+ * @example
+ * ```ts
+ * const eclipses = solarEclipses(engine, julianDay(2025, 1, 1), julianDay(2030, 1, 1));
+ * eclipses[0].type; // e.g. "partial"
+ * ```
+ */
 export declare function solarEclipses(engine: Engine, jdStart: number, jdEnd: number): SolarEclipse[];

package/dist/src/eclipses.js

@@ -131,7 +131,23 @@ export function lunarEclipses(engine, jdStart, jdEnd) {
     }
     return out;
 }
-/** Solar eclipses (global circumstances) in [jdStart, jdEnd] (UT JDs). */
+/**
+ * Solar eclipses in `[jdStart, jdEnd]`, with global circumstances (not
+ * local visibility). Each new Moon in the window is tested for an eclipse and,
+ * when found, classified by the Moon's shadow geometry.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jdStart Start of the window, Julian Day (UT).
+ * @param jdEnd End of the window, Julian Day (UT).
+ * @returns {@link SolarEclipse} records: `tMax` (greatest eclipse, JD UT),
+ *   `type` (`"total"`/`"annular"`/`"hybrid"`/`"partial"`), `gamma` (minimum
+ *   shadow-axis distance in Earth radii), and the `begin`/`end` JDs.
+ * @example
+ * ```ts
+ * const eclipses = solarEclipses(engine, julianDay(2025, 1, 1), julianDay(2030, 1, 1));
+ * eclipses[0].type; // e.g. "partial"
+ * ```
+ */
 export function solarEclipses(engine, jdStart, jdEnd) {
     const out = [];
     for (const tNew of syzygies(engine, jdStart - 1, jdEnd + 1, 0.0)) {

package/dist/src/events.d.ts

@@ -8,22 +8,68 @@ export interface RiseSetOptions {
     /** Rise/set of the disc center instead of the upper limb. */
     discCenter?: boolean;
 }
-/** Next rise/set/meridian transit (UT JD) after jdStart, or null when the
- *  event does not occur in the window (polar day/night). */
+/**
+ * The next rise, set, or meridian transit of a body after `jdStart`, as a
+ * Julian Day (UT). Accounts for the body's apparent radius, atmospheric
+ * refraction, and observer altitude.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param body A body id from {@link Engine.bodies}.
+ * @param jdStart Search start, Julian Day (UT). The result is the first event
+ *   strictly after this instant.
+ * @param latDeg Observer latitude in degrees, north positive.
+ * @param lonDeg Observer longitude in degrees, east positive.
+ * @param kind `"rise"`, `"set"`, `"mtransit"` (upper/meridian transit), or
+ *   `"itransit"` (lower transit). Defaults to `"rise"`.
+ * @param opts `altM` (observer altitude, m), `pressure` (hPa), `tempC`, and
+ *   `searchDays` (how far ahead to look; defaults to 2).
+ * @returns The event time as a Julian Day (UT), or `null` when it does not
+ *   occur in the window (e.g. polar day or night).
+ * @example
+ * ```ts
+ * // Next sunrise over London after 2025-06-01
+ * const jd = riseSet(engine, "sun", julianDay(2025, 6, 1), 51.5, -0.13, "rise");
+ * ```
+ */
 export declare function riseSet(engine: Engine, body: BodyId, jdStart: number, latDeg: number, lonDeg: number, kind?: RiseKind, opts?: RiseSetOptions): number | null;
 /** UT JDs where the body's apparent longitude crosses targetLon (degrees)
  *  in [jdStart, jdEnd]. Retrograde bodies can cross a degree three times;
  *  every crossing is returned in time order. */
 export declare function crossings(engine: Engine, body: BodyId, targetLon: number, jdStart: number, jdEnd: number, zodiac?: Zodiac, maxHits?: number): number[];
 export type PhaseName = "new" | "first_quarter" | "full" | "last_quarter";
-/** New/first-quarter/full/last-quarter times in [jdStart, jdEnd], sorted. */
+/**
+ * Every principal lunar phase (new, first quarter, full, last quarter) within
+ * `[jdStart, jdEnd]`, sorted by time. Found from the Sun–Moon elongation
+ * crossing 0°/90°/180°/270°.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jdStart Start of the window, Julian Day (UT).
+ * @param jdEnd End of the window, Julian Day (UT).
+ * @param maxHits Cap on the number of phases returned. Defaults to 60.
+ * @returns Sorted `[jdUt, phase]` pairs, where `phase` is one of
+ *   {@link PhaseName}.
+ * @example
+ * ```ts
+ * const phases = lunarPhases(engine, julianDay(2025, 1, 1), julianDay(2025, 2, 1));
+ * // [[jd, "new"], [jd, "first_quarter"], ...]
+ * ```
+ */
 export declare function lunarPhases(engine: Engine, jdStart: number, jdEnd: number, maxHits?: number): Array<[number, PhaseName]>;
 /** Times the body stations (speed crosses zero): [jdUt, direction the body
  *  turns]. Sun and Moon never station. Station timing is ill-conditioned:
  *  expect minute-level differences between ephemerides. */
 export declare function stations(engine: Engine, body: BodyId, jdStart: number, jdEnd: number, maxHits?: number): Array<[number, "retrograde" | "direct"]>;
-/** Gauquelin sector (1..36, float) from rise/set times of the disc center
- *  with refraction (Swiss Ephemeris method 3). Sectors run from rise: 1-18
- *  above the horizon, 19-36 below. Null in polar no-rise/no-set
- *  conditions. */
+/**
+ * The Gauquelin sector of a body (1–36, fractional) from the rise/set times of
+ * the disc centre with refraction (Swiss Ephemeris method 3). Sectors run from
+ * rise: 1–18 above the horizon, 19–36 below.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param body A body id from {@link Engine.bodies}.
+ * @param jdUt Julian Day (UT).
+ * @param latDeg Observer latitude in degrees, north positive.
+ * @param lonDeg Observer longitude in degrees, east positive.
+ * @returns The sector in `[1, 37)`, or `null` in polar no-rise/no-set
+ *   conditions.
+ */
 export declare function gauquelinSector(engine: Engine, body: BodyId, jdUt: number, latDeg: number, lonDeg: number): number | null;

package/dist/src/events.js

@@ -44,8 +44,29 @@ function bisect(f, a, b, iters = 45) {
     }
     return (a + b) / 2;
 }
-/** Next rise/set/meridian transit (UT JD) after jdStart, or null when the
- *  event does not occur in the window (polar day/night). */
+/**
+ * The next rise, set, or meridian transit of a body after `jdStart`, as a
+ * Julian Day (UT). Accounts for the body's apparent radius, atmospheric
+ * refraction, and observer altitude.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param body A body id from {@link Engine.bodies}.
+ * @param jdStart Search start, Julian Day (UT). The result is the first event
+ *   strictly after this instant.
+ * @param latDeg Observer latitude in degrees, north positive.
+ * @param lonDeg Observer longitude in degrees, east positive.
+ * @param kind `"rise"`, `"set"`, `"mtransit"` (upper/meridian transit), or
+ *   `"itransit"` (lower transit). Defaults to `"rise"`.
+ * @param opts `altM` (observer altitude, m), `pressure` (hPa), `tempC`, and
+ *   `searchDays` (how far ahead to look; defaults to 2).
+ * @returns The event time as a Julian Day (UT), or `null` when it does not
+ *   occur in the window (e.g. polar day or night).
+ * @example
+ * ```ts
+ * // Next sunrise over London after 2025-06-01
+ * const jd = riseSet(engine, "sun", julianDay(2025, 6, 1), 51.5, -0.13, "rise");
+ * ```
+ */
 export function riseSet(engine, body, jdStart, latDeg, lonDeg, kind = "rise", opts = {}) {
     const altM = opts.altM ?? 0.0;
     const pressure = opts.pressure ?? 1013.25;
@@ -110,7 +131,23 @@ export function crossings(engine, body, targetLon, jdStart, jdEnd, zodiac = "tro
     }
     return out;
 }
-/** New/first-quarter/full/last-quarter times in [jdStart, jdEnd], sorted. */
+/**
+ * Every principal lunar phase (new, first quarter, full, last quarter) within
+ * `[jdStart, jdEnd]`, sorted by time. Found from the Sun–Moon elongation
+ * crossing 0°/90°/180°/270°.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jdStart Start of the window, Julian Day (UT).
+ * @param jdEnd End of the window, Julian Day (UT).
+ * @param maxHits Cap on the number of phases returned. Defaults to 60.
+ * @returns Sorted `[jdUt, phase]` pairs, where `phase` is one of
+ *   {@link PhaseName}.
+ * @example
+ * ```ts
+ * const phases = lunarPhases(engine, julianDay(2025, 1, 1), julianDay(2025, 2, 1));
+ * // [[jd, "new"], [jd, "first_quarter"], ...]
+ * ```
+ */
 export function lunarPhases(engine, jdStart, jdEnd, maxHits = 60) {
     const elong = (t) => mod(engine.longitude("moon", t) - engine.longitude("sun", t), 360);
     const names = [
@@ -154,10 +191,19 @@ export function stations(engine, body, jdStart, jdEnd, maxHits = 30) {
     }
     return out;
 }
-/** Gauquelin sector (1..36, float) from rise/set times of the disc center
- *  with refraction (Swiss Ephemeris method 3). Sectors run from rise: 1-18
- *  above the horizon, 19-36 below. Null in polar no-rise/no-set
- *  conditions. */
+/**
+ * The Gauquelin sector of a body (1–36, fractional) from the rise/set times of
+ * the disc centre with refraction (Swiss Ephemeris method 3). Sectors run from
+ * rise: 1–18 above the horizon, 19–36 below.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param body A body id from {@link Engine.bodies}.
+ * @param jdUt Julian Day (UT).
+ * @param latDeg Observer latitude in degrees, north positive.
+ * @param lonDeg Observer longitude in degrees, east positive.
+ * @returns The sector in `[1, 37)`, or `null` in polar no-rise/no-set
+ *   conditions.
+ */
 export function gauquelinSector(engine, body, jdUt, latDeg, lonDeg) {
     const surrounding = (kind) => {
         let t = riseSet(engine, body, jdUt - 1.3, latDeg, lonDeg, kind, { discCenter: true });