caelus 0.11.0 → 0.12.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/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 });

package/dist/src/features.d.ts

@@ -1,19 +1,63 @@
 import { Engine, BodyId, Zodiac } from "./chart.js";
 import { RankedMoment } from "./scan.js";
 export declare const DEFAULT_BODIES: string[];
-/** Flat vector [w*cos(lon), w*sin(lon), ...] for the given (longitude, weight)
- *  pairs, in order. */
+/**
+ * Build a feature vector from explicit `(longitude, weight)` pairs: each pair
+ * contributes a weighted unit-circle point `[w·cos(lon), w·sin(lon)]`. The
+ * low-level primitive behind {@link chartFeatures}; most callers want that.
+ *
+ * @param weightedLons `[longitudeDeg, weight]` pairs, in the order they should
+ *   appear in the vector.
+ * @returns A flat vector, two entries per pair.
+ */
 export declare function featureVector(weightedLons: [number, number][]): number[];
-/** Cosine similarity of two feature vectors, in [-1, 1]. */
+/**
+ * Cosine similarity of two feature vectors, in `[-1, 1]`. For vectors from
+ * {@link chartFeatures} this is a weighted mean of `cos(Δlongitude)` per body:
+ * `1` when the configurations coincide, falling off as bodies diverge.
+ *
+ * @param a First feature vector.
+ * @param b Second feature vector (compared over the shorter length).
+ * @returns Similarity in `[-1, 1]`; `0` if either vector is all zeros.
+ */
 export declare function cosineSimilarity(a: number[], b: number[]): number;
 export interface FeatureOptions {
     bodies?: BodyId[];
     weights?: Record<string, number>;
     zodiac?: Zodiac;
 }
-/** Feature vector for the sky at jdUt over an ordered set of bodies. */
+/**
+ * Encode the sky at an instant as a feature vector: each body's ecliptic
+ * longitude becomes a weighted unit-circle point. The deterministic substrate
+ * for matching and searching chart configurations — compare two with
+ * {@link cosineSimilarity}, or rank a time range against one with
+ * {@link searchConfigurations}.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jdUt Julian Day in UT.
+ * @param opts `bodies` (ordered; defaults to the ten major bodies), per-body
+ *   `weights`, and `zodiac` (tropical by default).
+ * @returns A flat vector `[w·cos(lon), w·sin(lon), ...]`, two entries per body
+ *   in `bodies` order.
+ * @example
+ * ```ts
+ * const target = chartFeatures(engine, julianDay(2000, 1, 1));
+ * const now = chartFeatures(engine, julianDay(2025, 6, 1));
+ * cosineSimilarity(now, target); // 1 = identical configuration
+ * ```
+ */
 export declare function chartFeatures(engine: Engine, jdUt: number, opts?: FeatureOptions): number[];
-/** Similarity between the sky at jdUt and a target feature vector. */
+/**
+ * Similarity between the sky at `jdUt` and a target feature vector — shorthand
+ * for `cosineSimilarity(chartFeatures(engine, jdUt, opts), target)`. The scoring
+ * function {@link searchConfigurations} maximizes.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jdUt Julian Day in UT.
+ * @param target A target feature vector from {@link chartFeatures}.
+ * @param opts {@link FeatureOptions} — must match those used to build `target`.
+ * @returns Cosine similarity in `[-1, 1]`.
+ */
 export declare function configurationFit(engine: Engine, jdUt: number, target: number[], opts?: FeatureOptions): number;
 export interface SearchConfigOptions extends FeatureOptions {
     start: number;
@@ -21,6 +65,24 @@ export interface SearchConfigOptions extends FeatureOptions {
     step: number;
     limit?: number;
 }
-/** Rank the instants in [start, end] by how closely the sky resembles `target`
- *  (a feature vector), best first. Realization search over the feature space. */
+/**
+ * Rank the instants in `[start, end]` by how closely the sky resembles a
+ * `target` feature vector, best first — a realization search over the feature
+ * space. Build `target` with {@link chartFeatures} (e.g. from a natal chart).
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param target A target feature vector from {@link chartFeatures}.
+ * @param opts `start`/`end` (Julian Days, UT) and `step` (days) define the
+ *   scan, `limit` caps the results, plus the {@link FeatureOptions} (`bodies`,
+ *   `weights`, `zodiac`) — which must match those used to build `target`.
+ * @returns Ranked `{ jd, score }` moments, highest similarity first.
+ * @example
+ * ```ts
+ * const natal = chartFeatures(engine, julianDay(1990, 6, 10, 14, 30));
+ * const matches = searchConfigurations(engine, natal, {
+ *   start: julianDay(2025, 1, 1), end: julianDay(2026, 1, 1), step: 1, limit: 5,
+ * });
+ * matches[0].jd; // best-matching instant
+ * ```
+ */
 export declare function searchConfigurations(engine: Engine, target: number[], opts: SearchConfigOptions): RankedMoment[];