caelus 0.10.0 → 0.12.0

package/dist/src/compiler.js

@@ -0,0 +1,152 @@
+/**
+ * astroengine compiler -- synthesize a chart form from geometric constraints.
+ *
+ * The inverse of (time, place) -> chart: given weighted geometric constraints
+ * (aspects between bodies, sign or degree placements), find the body longitudes
+ * that best satisfy them, and report how well they can be. If the best fit is
+ * still poor, the form is geometrically impossible -- a valid result.
+ *
+ * The loss / constraint math is pure and mirrors the Python reference
+ * (astroengine/compiler.py), pinned by the golden. The optimizer is a
+ * deterministic coordinate descent with fixed low-discrepancy restarts.
+ */
+const PHI = 0.6180339887498949;
+function angDist(a, b) {
+    return Math.abs(((a - b + 180.0) % 360.0) - 180.0);
+}
+function signLoss(lon, sign) {
+    const lo = (((sign % 12) + 12) % 12) * 30.0;
+    const d = (((lon - lo) % 360.0) + 360.0) % 360.0;
+    if (d < 30.0)
+        return 0.0;
+    return Math.min(d - 30.0, 360.0 - d);
+}
+/**
+ * Degrees by which a single {@link Constraint} is unmet for a set of body
+ * longitudes — `0` when satisfied. The pure building block of {@link formLoss}
+ * and {@link compileForm}.
+ *
+ * @param lons Body longitudes in degrees, keyed by body id.
+ * @param c The constraint to score.
+ * @returns The unmet amount in degrees (`0` = satisfied).
+ */
+export function constraintLoss(lons, c) {
+    if (c.kind === "aspect")
+        return Math.abs(angDist(lons[c.a], lons[c.b]) - c.angle);
+    if (c.kind === "sign")
+        return signLoss(lons[c.body], c.sign);
+    return angDist(lons[c.body], c.degree);
+}
+/**
+ * Total weighted loss for a set of body longitudes — the sum of each
+ * constraint's {@link constraintLoss} times its weight. The objective
+ * {@link compileForm} minimizes.
+ *
+ * @param lons Body longitudes in degrees, keyed by body id.
+ * @param constraints The constraints to score.
+ * @returns The total weighted loss in degrees (`0` = all satisfied).
+ */
+export function formLoss(lons, constraints) {
+    let total = 0;
+    for (const c of constraints)
+        total += (c.weight ?? 1.0) * constraintLoss(lons, c);
+    return total;
+}
+function bodiesOf(constraints) {
+    const s = new Set();
+    for (const c of constraints) {
+        if (c.kind === "aspect") {
+            s.add(c.a);
+            s.add(c.b);
+        }
+        else
+            s.add(c.body);
+    }
+    return [...s].sort();
+}
+function involves(c, body) {
+    return c.kind === "aspect" ? (c.a === body || c.b === body) : c.body === body;
+}
+function bodyLoss(lons, body, constraints) {
+    let total = 0;
+    for (const c of constraints)
+        if (involves(c, body))
+            total += (c.weight ?? 1.0) * constraintLoss(lons, c);
+    return total;
+}
+/**
+ * Synthesize a chart form from geometric constraints — the inverse of
+ * (time, place) → chart. Given weighted {@link Constraint}s (aspects between
+ * bodies, sign placements, exact degrees), find the body longitudes that best
+ * satisfy them via deterministic coordinate descent, and report how well they
+ * can be met. When even the best fit is poor, the form is flagged `impossible`
+ * — a valid, informative result.
+ *
+ * @param constraints The geometric constraints to satisfy; each may carry a
+ *   `weight` (default `1`).
+ * @param opts `restarts` and `iters` tune the optimizer (more = slower, more
+ *   thorough); `impossibleDeg` is the worst-constraint threshold in degrees
+ *   above which the form is impossible. Defaults: `12`, `8`, `5`.
+ * @returns A {@link CompiledForm}: solved `longitudes`, total `residual`,
+ *   `maxConstraintLoss`, the `impossible` flag, and each constraint annotated
+ *   with its `loss`.
+ * @example
+ * ```ts
+ * const form = compileForm([
+ *   { kind: "aspect", a: "sun", b: "moon", angle: 120 }, // trine
+ *   { kind: "sign", body: "sun", sign: 0 },              // Aries
+ * ]);
+ * form.impossible;     // false
+ * form.longitudes.sun; // a degree within Aries
+ * ```
+ */
+export function compileForm(constraints, opts = {}) {
+    const restarts = opts.restarts ?? 12;
+    const iters = opts.iters ?? 8;
+    const impossibleDeg = opts.impossibleDeg ?? 5.0;
+    const bodies = bodiesOf(constraints);
+    const n = Math.max(bodies.length, 1);
+    let best = null;
+    for (let r = 0; r < restarts; r++) {
+        const lons = {};
+        bodies.forEach((b, i) => { lons[b] = (((r * n + i + 1) * PHI) % 1.0) * 360.0; });
+        for (let it = 0; it < iters; it++) {
+            for (const b of bodies) {
+                let bestL = lons[b];
+                let bestE = bodyLoss(lons, b, constraints);
+                for (let i = 0; i < 360; i++) {
+                    lons[b] = i;
+                    const e = bodyLoss(lons, b, constraints);
+                    if (e < bestE) {
+                        bestE = e;
+                        bestL = i;
+                    }
+                }
+                for (let k = -20; k <= 20; k++) {
+                    const cand = (((bestL + k * 0.05) % 360.0) + 360.0) % 360.0;
+                    lons[b] = cand;
+                    const e = bodyLoss(lons, b, constraints);
+                    if (e < bestE) {
+                        bestE = e;
+                        bestL = cand;
+                    }
+                }
+                lons[b] = bestL;
+            }
+        }
+        const e = formLoss(lons, constraints);
+        if (best === null || e < best.e)
+            best = { e, lons: { ...lons } };
+    }
+    const lons = best.lons;
+    let maxLoss = 0;
+    for (const c of constraints)
+        maxLoss = Math.max(maxLoss, constraintLoss(lons, c));
+    return {
+        longitudes: lons,
+        residual: best.e,
+        maxConstraintLoss: maxLoss,
+        impossible: maxLoss > impossibleDeg,
+        constraints: constraints.map((c) => ({ ...c, loss: constraintLoss(lons, c) })),
+    };
+}

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