caelus 0.10.0 → 0.12.0

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

@@ -0,0 +1,88 @@
+import { Engine, BodyId, Zodiac } from "./chart.js";
+import { RankedMoment } from "./scan.js";
+export declare const DEFAULT_BODIES: string[];
+/**
+ * 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]`. 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;
+}
+/**
+ * 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 — 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;
+    end: number;
+    step: number;
+    limit?: number;
+}
+/**
+ * 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[];

package/dist/src/features.js

@@ -0,0 +1,119 @@
+/**
+ * astroengine features -- a chart as a feature vector, similarity between
+ * charts, and search for when the sky most resembles a target configuration.
+ *
+ * Each body's ecliptic longitude is circular, so it contributes a unit-circle
+ * point (cos, sin), optionally weighted. Cosine similarity between two such
+ * vectors is a weighted mean of cos(delta-longitude) per body: 1 when the
+ * configurations coincide, falling off as bodies diverge. The deterministic
+ * substrate for matching, retrieving, and searching chart configurations.
+ * Mirrors the Python reference (astroengine/features.py); the golden pins them.
+ */
+import { DEG } from "./core.js";
+import { rankMoments } from "./scan.js";
+export const DEFAULT_BODIES = ["sun", "moon", "mercury", "venus", "mars",
+    "jupiter", "saturn", "uranus", "neptune", "pluto"];
+/**
+ * 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 function featureVector(weightedLons) {
+    const out = [];
+    for (const [lon, w] of weightedLons) {
+        const r = lon * DEG;
+        out.push(w * Math.cos(r), w * Math.sin(r));
+    }
+    return out;
+}
+/**
+ * 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 function cosineSimilarity(a, b) {
+    let dot = 0, na = 0, nb = 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/**
+ * 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 function chartFeatures(engine, jdUt, opts = {}) {
+    const bodies = opts.bodies ?? DEFAULT_BODIES;
+    const zodiac = opts.zodiac ?? "tropical";
+    const wl = bodies.map((b) => [
+        engine.longitude(b, jdUt, { zodiac }),
+        opts.weights?.[b] ?? 1.0,
+    ]);
+    return featureVector(wl);
+}
+/**
+ * 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 function configurationFit(engine, jdUt, target, opts = {}) {
+    return cosineSimilarity(chartFeatures(engine, jdUt, opts), target);
+}
+/**
+ * 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 function searchConfigurations(engine, target, opts) {
+    return rankMoments({ start: opts.start, end: opts.end, step: opts.step, limit: opts.limit }, (jd) => configurationFit(engine, jd, target, opts));
+}

package/dist/src/houses.d.ts

@@ -41,9 +41,18 @@ export declare function housesPolichPage(armc: number, phi: number, eps: number)
 /** Vehlow: equal houses with the ASC at the middle of house 1. */
 export declare function housesVehlow(armc: number, phi: number, eps: number): number[];
 /**
- * Placidus cusps via the classic iterative scheme. Semi-arc derivation:
- * for ALL four intermediate cusps RA = ARMC + offset + f*AD with
- * AD = asin(tan(phi) tan(dec)); offsets 30/60/120/150, f = 1/3,2/3,2/3,1/3.
- * Undefined above the polar circles (as Placidus itself is).
+ * Placidus house cusps via the classic iterative semi-arc scheme: for all four
+ * intermediate cusps RA = ARMC + offset + f·AD with AD = asin(tan φ · tan δ);
+ * offsets 30/60/120/150, f = 1/3, 2/3, 2/3, 1/3. Undefined above the polar
+ * circles, as Placidus itself is.
+ *
+ * Low-level: {@link Engine.chart} calls this for you when the house system is
+ * `"placidus"`, falling back to whole-sign near the poles. Inputs and outputs
+ * are in **radians**.
+ *
+ * @param armc Right ascension of the MC, in radians.
+ * @param phi Geographic latitude, in radians.
+ * @param eps Obliquity of the ecliptic, in radians.
+ * @returns The twelve cusp longitudes in radians, house 1 (Ascendant) first.
  */
 export declare function housesPlacidus(armc: number, phi: number, eps: number): number[];

package/dist/src/houses.js

@@ -257,10 +257,19 @@ export function housesVehlow(armc, phi, eps) {
     return Array.from({ length: 12 }, (_, i) => mod(asc - 15 * DEG + i * 30 * DEG, TWO_PI));
 }
 /**
- * Placidus cusps via the classic iterative scheme. Semi-arc derivation:
- * for ALL four intermediate cusps RA = ARMC + offset + f*AD with
- * AD = asin(tan(phi) tan(dec)); offsets 30/60/120/150, f = 1/3,2/3,2/3,1/3.
- * Undefined above the polar circles (as Placidus itself is).
+ * Placidus house cusps via the classic iterative semi-arc scheme: for all four
+ * intermediate cusps RA = ARMC + offset + f·AD with AD = asin(tan φ · tan δ);
+ * offsets 30/60/120/150, f = 1/3, 2/3, 2/3, 1/3. Undefined above the polar
+ * circles, as Placidus itself is.
+ *
+ * Low-level: {@link Engine.chart} calls this for you when the house system is
+ * `"placidus"`, falling back to whole-sign near the poles. Inputs and outputs
+ * are in **radians**.
+ *
+ * @param armc Right ascension of the MC, in radians.
+ * @param phi Geographic latitude, in radians.
+ * @param eps Obliquity of the ecliptic, in radians.
+ * @returns The twelve cusp longitudes in radians, house 1 (Ascendant) first.
  */
 export function housesPlacidus(armc, phi, eps) {
     const cusp = (offsetDeg, f) => {

package/dist/src/index.d.ts

@@ -13,3 +13,5 @@ export * from "./scan.js";
 export * from "./spherical.js";
 export * from "./astrocartography.js";
 export * from "./ephemeris.js";
+export * from "./features.js";
+export * from "./compiler.js";

package/dist/src/index.js

@@ -13,3 +13,5 @@ export * from "./scan.js";
 export * from "./spherical.js";
 export * from "./astrocartography.js";
 export * from "./ephemeris.js";
+export * from "./features.js";
+export * from "./compiler.js";

package/dist/src/pheno.d.ts

@@ -19,8 +19,22 @@ export interface Pheno {
     diameter: number;
     magnitude: number;
 }
-/** Phase angle (deg), illuminated fraction, elongation (deg), apparent
- *  diameter (deg), apparent magnitude. */
+/**
+ * Photometric and apparent-geometry quantities for a body at an instant: its
+ * phase angle, illuminated fraction, elongation from the Sun, apparent disc
+ * diameter, and apparent visual magnitude.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param body A body with known physical dimensions (Sun, Moon, the planets).
+ * @param jdUt Julian Day (UT).
+ * @returns A {@link Pheno}: `phaseAngle` (deg), `phase` (lit fraction `0`–`1`),
+ *   `elongation` (deg), `diameter` (deg), and `magnitude`.
+ * @throws Error if `body` has no photometric data.
+ * @example
+ * ```ts
+ * pheno(engine, "venus", julianDay(2025, 6, 1)).phase; // illuminated fraction
+ * ```
+ */
 export declare function pheno(engine: Engine, body: BodyId, jdUt: number): Pheno;
 /** Apparent minus mean solar time, minutes (Meeus ch. 28). */
 export declare function equationOfTime(engine: Engine, jdUt: number): number;

package/dist/src/pheno.js

@@ -66,8 +66,22 @@ function magnitude(body, a, r, dlt, jde, lonDeg, latDeg) {
             return x - 1.01;
     }
 }
-/** Phase angle (deg), illuminated fraction, elongation (deg), apparent
- *  diameter (deg), apparent magnitude. */
+/**
+ * Photometric and apparent-geometry quantities for a body at an instant: its
+ * phase angle, illuminated fraction, elongation from the Sun, apparent disc
+ * diameter, and apparent visual magnitude.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param body A body with known physical dimensions (Sun, Moon, the planets).
+ * @param jdUt Julian Day (UT).
+ * @returns A {@link Pheno}: `phaseAngle` (deg), `phase` (lit fraction `0`–`1`),
+ *   `elongation` (deg), `diameter` (deg), and `magnitude`.
+ * @throws Error if `body` has no photometric data.
+ * @example
+ * ```ts
+ * pheno(engine, "venus", julianDay(2025, 6, 1)).phase; // illuminated fraction
+ * ```
+ */
 export function pheno(engine, body, jdUt) {
     if (DIAMETER_KM[body] === undefined) {
         throw new Error(`pheno not available for '${body}'`);

package/dist/src/query.d.ts

@@ -6,8 +6,26 @@ export interface Predicate {
     (engine: Engine, t: number): number;
     bodies: Set<string>;
 }
-/** True while `body` is within `orb` deg of an exact `kind` aspect to
- *  `target` -- a fixed ecliptic longitude (deg) or another body name. */
+/**
+ * A {@link Predicate} that holds while `body` is within `orb` degrees of an
+ * exact aspect to `target`. Feed it to {@link when} to find the time windows,
+ * or compose it with {@link allOf}/{@link anyOf}.
+ *
+ * @param body The transiting body.
+ * @param kind Aspect name, e.g. `"conjunction"`, `"square"`, `"trine"`,
+ *   `"opposition"`, `"sextile"`.
+ * @param target The aspect target: a fixed ecliptic longitude in degrees (e.g.
+ *   a natal point) or another body id (a mutual aspect).
+ * @param orb Half-width of the window in degrees. Defaults to `1.0`.
+ * @param zodiac Zodiac for the longitudes. Defaults to tropical.
+ * @returns A predicate, true while within orb of the exact aspect.
+ * @throws Error if `kind` is not a known aspect.
+ * @example
+ * ```ts
+ * const natalSun = 79.3;
+ * when(engine, aspect("saturn", "square", natalSun, 1), jd0, jd1); // Saturn squares
+ * ```
+ */
 export declare function aspect(body: BodyId, kind: string, target: number | BodyId, orb?: number, zodiac?: Zodiac): Predicate;
 /** True while `body` is in `sign` (index 0=Aries..11=Pisces, or name). */
 export declare function inSign(body: BodyId, sign: number | string, zodiac?: Zodiac): Predicate;
@@ -25,8 +43,31 @@ export interface WhenOptions {
     step?: number;
     maxIntervals?: number;
 }
-/** Time intervals (jdStartUt, jdEndUt) in [jdStart, jdEnd] where `predicate`
- *  is true. Endpoints touching the range bounds are clamped. The scan step
- *  defaults to 0.125 d when a fast body (Moon, nodes, Lilith) is involved
- *  and 1 d otherwise. */
+/**
+ * Solve for the time intervals within `[jdStart, jdEnd]` (UT Julian Days) where
+ * a {@link Predicate} holds. Predicates compose from {@link aspect},
+ * {@link inSign}, {@link retrograde}, {@link notRetrograde}, and the
+ * {@link allOf}/{@link anyOf} combinators, so one call answers questions like
+ * "when is Venus in Taurus while Mercury is direct?".
+ *
+ * Returned intervals are sorted and disjoint; endpoints touching the range
+ * bounds are clamped. The scan step defaults to 0.125 d when a fast body (Moon,
+ * nodes, Lilith) is involved and 1 d otherwise — override it with `opts.step`.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param predicate A celestial predicate (see {@link aspect}, {@link inSign}).
+ * @param jdStart Start of the search window, Julian Day (UT).
+ * @param jdEnd End of the search window, Julian Day (UT).
+ * @param opts `step` (scan resolution in days) and `maxIntervals`.
+ * @returns Sorted, disjoint `[startUt, endUt]` intervals where the predicate is
+ *   true.
+ * @example
+ * ```ts
+ * const windows = when(
+ *   engine,
+ *   allOf(inSign("venus", "Taurus"), notRetrograde("mercury")),
+ *   julianDay(2025, 1, 1), julianDay(2026, 1, 1),
+ * );
+ * ```
+ */
 export declare function when(engine: Engine, predicate: Predicate, jdStart: number, jdEnd: number, opts?: WhenOptions): Interval[];

package/dist/src/query.js

@@ -35,8 +35,26 @@ function mk(fn, bodies) {
     return p;
 }
 // ---------------------------------------------------------------- predicates
-/** True while `body` is within `orb` deg of an exact `kind` aspect to
- *  `target` -- a fixed ecliptic longitude (deg) or another body name. */
+/**
+ * A {@link Predicate} that holds while `body` is within `orb` degrees of an
+ * exact aspect to `target`. Feed it to {@link when} to find the time windows,
+ * or compose it with {@link allOf}/{@link anyOf}.
+ *
+ * @param body The transiting body.
+ * @param kind Aspect name, e.g. `"conjunction"`, `"square"`, `"trine"`,
+ *   `"opposition"`, `"sextile"`.
+ * @param target The aspect target: a fixed ecliptic longitude in degrees (e.g.
+ *   a natal point) or another body id (a mutual aspect).
+ * @param orb Half-width of the window in degrees. Defaults to `1.0`.
+ * @param zodiac Zodiac for the longitudes. Defaults to tropical.
+ * @returns A predicate, true while within orb of the exact aspect.
+ * @throws Error if `kind` is not a known aspect.
+ * @example
+ * ```ts
+ * const natalSun = 79.3;
+ * when(engine, aspect("saturn", "square", natalSun, 1), jd0, jd1); // Saturn squares
+ * ```
+ */
 export function aspect(body, kind, target, orb = 1.0, zodiac = "tropical") {
     const ang = QUERY_ASPECTS[kind];
     if (ang === undefined)
@@ -117,10 +135,33 @@ function bisect(f, a, b, tol = 1e-6) {
     }
     return 0.5 * (a + b);
 }
-/** Time intervals (jdStartUt, jdEndUt) in [jdStart, jdEnd] where `predicate`
- *  is true. Endpoints touching the range bounds are clamped. The scan step
- *  defaults to 0.125 d when a fast body (Moon, nodes, Lilith) is involved
- *  and 1 d otherwise. */
+/**
+ * Solve for the time intervals within `[jdStart, jdEnd]` (UT Julian Days) where
+ * a {@link Predicate} holds. Predicates compose from {@link aspect},
+ * {@link inSign}, {@link retrograde}, {@link notRetrograde}, and the
+ * {@link allOf}/{@link anyOf} combinators, so one call answers questions like
+ * "when is Venus in Taurus while Mercury is direct?".
+ *
+ * Returned intervals are sorted and disjoint; endpoints touching the range
+ * bounds are clamped. The scan step defaults to 0.125 d when a fast body (Moon,
+ * nodes, Lilith) is involved and 1 d otherwise — override it with `opts.step`.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param predicate A celestial predicate (see {@link aspect}, {@link inSign}).
+ * @param jdStart Start of the search window, Julian Day (UT).
+ * @param jdEnd End of the search window, Julian Day (UT).
+ * @param opts `step` (scan resolution in days) and `maxIntervals`.
+ * @returns Sorted, disjoint `[startUt, endUt]` intervals where the predicate is
+ *   true.
+ * @example
+ * ```ts
+ * const windows = when(
+ *   engine,
+ *   allOf(inSign("venus", "Taurus"), notRetrograde("mercury")),
+ *   julianDay(2025, 1, 1), julianDay(2026, 1, 1),
+ * );
+ * ```
+ */
 export function when(engine, predicate, jdStart, jdEnd, opts = {}) {
     let step = opts.step;
     if (step === undefined) {

package/dist/src/turbo.d.ts

@@ -9,12 +9,46 @@ export interface TurboPack {
     zodiac: string;
     bodies: Record<string, TurboBody>;
 }
+/**
+ * Runtime evaluator for a **turbo pack** — a segmented Chebyshev fit of the
+ * engine's apparent longitude over a fixed range and body set. Evaluating a
+ * longitude costs a couple dozen multiply-adds, so a century-scale transit scan
+ * that calls it tens of thousands of times runs in milliseconds. Construct one
+ * from a pack you minted offline; it does no fitting, no I/O, and needs no
+ * {@link Engine}.
+ *
+ * @example
+ * ```ts
+ * const turbo = new Turbo(pack); // a TurboPack generated for your range/bodies
+ * if (turbo.has("mars")) turbo.longitude("mars", jd);
+ * ```
+ */
 export declare class Turbo {
+    /** Start of the pack's valid Julian Day (UT) range. */
     readonly jd0: number;
+    /** End of the pack's valid Julian Day (UT) range. */
     readonly jd1: number;
     private readonly bodies;
+    /**
+     * @param pack A {@link TurboPack}: the fitted segments plus its `jd0`/`jd1`
+     *   range, minted offline for your bodies and span.
+     */
     constructor(pack: TurboPack);
+    /**
+     * Whether this pack can evaluate a given body.
+     *
+     * @param body Body id to test.
+     * @returns `true` if {@link Turbo.longitude} accepts `body`.
+     */
     has(body: string): boolean;
-    /** Apparent ecliptic longitude (degrees) from the turbo pack. */
+    /**
+     * Apparent ecliptic longitude (degrees) of a body from the turbo pack, in the
+     * pack's own zodiac. The hot path for bulk scans.
+     *
+     * @param body A body id the pack contains (see {@link Turbo.has}).
+     * @param jd Julian Day (UT), within `[jd0, jd1]`.
+     * @returns Ecliptic longitude in degrees, `[0, 360)`.
+     * @throws Error if the pack lacks `body`, or `jd` is outside `[jd0, jd1]`.
+     */
     longitude(body: string, jd: number): number;
 }

package/dist/src/turbo.js

@@ -22,19 +22,53 @@ function clenshaw(coeffs, x) {
     }
     return x * b0 - b1 + coeffs[0];
 }
+/**
+ * Runtime evaluator for a **turbo pack** — a segmented Chebyshev fit of the
+ * engine's apparent longitude over a fixed range and body set. Evaluating a
+ * longitude costs a couple dozen multiply-adds, so a century-scale transit scan
+ * that calls it tens of thousands of times runs in milliseconds. Construct one
+ * from a pack you minted offline; it does no fitting, no I/O, and needs no
+ * {@link Engine}.
+ *
+ * @example
+ * ```ts
+ * const turbo = new Turbo(pack); // a TurboPack generated for your range/bodies
+ * if (turbo.has("mars")) turbo.longitude("mars", jd);
+ * ```
+ */
 export class Turbo {
+    /** Start of the pack's valid Julian Day (UT) range. */
     jd0;
+    /** End of the pack's valid Julian Day (UT) range. */
     jd1;
     bodies;
+    /**
+     * @param pack A {@link TurboPack}: the fitted segments plus its `jd0`/`jd1`
+     *   range, minted offline for your bodies and span.
+     */
     constructor(pack) {
         this.jd0 = pack.jd0;
         this.jd1 = pack.jd1;
         this.bodies = pack.bodies;
     }
+    /**
+     * Whether this pack can evaluate a given body.
+     *
+     * @param body Body id to test.
+     * @returns `true` if {@link Turbo.longitude} accepts `body`.
+     */
     has(body) {
         return body in this.bodies;
     }
-    /** Apparent ecliptic longitude (degrees) from the turbo pack. */
+    /**
+     * Apparent ecliptic longitude (degrees) of a body from the turbo pack, in the
+     * pack's own zodiac. The hot path for bulk scans.
+     *
+     * @param body A body id the pack contains (see {@link Turbo.has}).
+     * @param jd Julian Day (UT), within `[jd0, jd1]`.
+     * @returns Ecliptic longitude in degrees, `[0, 360)`.
+     * @throws Error if the pack lacks `body`, or `jd` is outside `[jd0, jd1]`.
+     */
     longitude(body, jd) {
         const b = this.bodies[body];
         if (!b)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caelus",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Astrological ephemeris engine. MIT, no AGPL, no ephemeris files. Checked against Swiss Ephemeris.",
   "type": "module",
   "main": "dist/src/index.js",