caelus 0.11.0 → 0.13.0

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/releasing.d.ts

@@ -0,0 +1,32 @@
+import { Engine, Zodiac } from "./chart.js";
+/** Period length in 360-day years for each sign, Aries..Pisces. */
+export declare const ZR_PERIODS: readonly [15, 8, 20, 25, 19, 20, 8, 15, 12, 27, 30, 12];
+/** Days per period unit at each level (each a twelfth of the one above). */
+export declare const LEVEL_UNIT: Record<number, number>;
+export interface ZrPeriod {
+    level: number;
+    sign: string;
+    lord: string;
+    start: number;
+    end: number;
+    /** True when this period is the loosing of the bond (jumped to the opposite sign). */
+    lb: boolean;
+}
+/** Flat timeline of releasing periods down to `maxLevel` over `horizonYears`
+ *  (360-day years) from birth. */
+export declare function zrRelease(lotSign: number, natalJd: number, maxLevel?: number, horizonYears?: number): ZrPeriod[];
+export interface ZrActive {
+    l1: string;
+    l2: string;
+    l3: string;
+    l4: string;
+}
+/** The L1..L4 releasing signs active at `targetJd`; null outside the span. */
+export declare function zrActive(lotSign: number, natalJd: number, targetJd: number): ZrActive | null;
+/** Zodiacal releasing active at `targetJd`, releasing from the Lot of Spirit
+ *  (default) or Fortune of the natal chart. */
+export declare function zrAt(engine: Engine, natalJd: number, targetJd: number, lat: number, lonEast: number, lot?: "spirit" | "fortune", zodiac?: Zodiac): {
+    lot: string;
+    lot_sign: string;
+    day: boolean;
+} & Partial<ZrActive>;

package/dist/src/releasing.js

@@ -0,0 +1,109 @@
+/**
+ * astroengine releasing -- zodiacal releasing (aphesis), the Hellenistic
+ * time-lord technique from Vettius Valens, released from a Lot (usually Spirit
+ * or Fortune).
+ *
+ * From the Lot's sign, periods release sign by sign. A sign's period length is
+ * its planetary minor years (Aries 15, Taurus 8, Gemini 20, Cancer 25, Leo 19,
+ * Virgo 20, Libra 8, Scorpio 15, Sagittarius 12, Capricorn 27, Aquarius 30,
+ * Pisces 12). Convention: 360-day years, each level a twelfth of the one above
+ * (L1 = period x 360 days, L2 = x 30, L3 = x 2.5, L4 = x 2.5/12). Within a
+ * period the next level releases from the same sign and fills it (last
+ * sub-period truncates at the boundary); when a sub-level returns to the sign it
+ * began on it looses the bond, jumping to the opposite sign (+6) once. Mirrors
+ * the Python reference (astroengine/releasing.py); the golden fixtures pin the
+ * two together.
+ */
+import { SIGNS } from "./chart.js";
+import { isDayChart } from "./derived.js";
+import { lotSpirit, lotFortune } from "./lots.js";
+import { SIGN_RULERS } from "./profections.js";
+/** Period length in 360-day years for each sign, Aries..Pisces. */
+export const ZR_PERIODS = [15, 8, 20, 25, 19, 20, 8, 15, 12, 27, 30, 12];
+/** Days per period unit at each level (each a twelfth of the one above). */
+export const LEVEL_UNIT = { 1: 360, 2: 30, 3: 2.5, 4: 2.5 / 12 };
+const FULL_CYCLE = ZR_PERIODS.reduce((a, b) => a + b, 0) * 360; // one full L1 cycle, days
+const EPS = 1e-9;
+function release(out, level, maxLevel, startSign, spanStart, spanEnd, horizon) {
+    const unit = LEVEL_UNIT[level];
+    let sign = startSign;
+    let lb = false;
+    let pendingLb = false;
+    let cur = spanStart;
+    while (cur < spanEnd - EPS && cur < horizon - EPS) {
+        const plen = ZR_PERIODS[sign] * unit;
+        const subEnd = Math.min(cur + plen, spanEnd, horizon);
+        out.push({ level, sign: SIGNS[sign], lord: SIGN_RULERS[sign], start: cur, end: subEnd, lb: pendingLb });
+        if (level < maxLevel) {
+            release(out, level + 1, maxLevel, sign, cur, Math.min(cur + plen, spanEnd), horizon);
+        }
+        cur += plen;
+        pendingLb = false;
+        const nxt = (sign + 1) % 12;
+        if (nxt === startSign && !lb) {
+            sign = (startSign + 6) % 12;
+            lb = true;
+            pendingLb = true;
+        }
+        else {
+            sign = nxt;
+        }
+    }
+}
+/** Flat timeline of releasing periods down to `maxLevel` over `horizonYears`
+ *  (360-day years) from birth. */
+export function zrRelease(lotSign, natalJd, maxLevel = 2, horizonYears = 100) {
+    const out = [];
+    const horizon = natalJd + horizonYears * 360;
+    release(out, 1, maxLevel, lotSign, natalJd, natalJd + FULL_CYCLE, horizon);
+    return out;
+}
+/** The (sign, start, end) of the sub-period containing `target`, or null. */
+function subAt(unit, startSign, spanStart, spanEnd, target) {
+    let sign = startSign;
+    let lb = false;
+    let cur = spanStart;
+    while (cur < spanEnd - EPS) {
+        const plen = ZR_PERIODS[sign] * unit;
+        const subEnd = Math.min(cur + plen, spanEnd);
+        if (cur <= target && target < subEnd)
+            return [sign, cur, subEnd];
+        cur += plen;
+        const nxt = (sign + 1) % 12;
+        if (nxt === startSign && !lb) {
+            sign = (startSign + 6) % 12;
+            lb = true;
+        }
+        else
+            sign = nxt;
+    }
+    return null;
+}
+/** The L1..L4 releasing signs active at `targetJd`; null outside the span. */
+export function zrActive(lotSign, natalJd, targetJd) {
+    const l1 = subAt(360, lotSign, natalJd, natalJd + FULL_CYCLE, targetJd);
+    if (l1 === null)
+        return null;
+    const l2 = subAt(30, l1[0], l1[1], l1[2], targetJd);
+    if (l2 === null)
+        return null;
+    const l3 = subAt(2.5, l2[0], l2[1], l2[2], targetJd);
+    if (l3 === null)
+        return null;
+    const l4 = subAt(2.5 / 12, l3[0], l3[1], l3[2], targetJd);
+    if (l4 === null)
+        return null;
+    return { l1: SIGNS[l1[0]], l2: SIGNS[l2[0]], l3: SIGNS[l3[0]], l4: SIGNS[l4[0]] };
+}
+/** Zodiacal releasing active at `targetJd`, releasing from the Lot of Spirit
+ *  (default) or Fortune of the natal chart. */
+export function zrAt(engine, natalJd, targetJd, lat, lonEast, lot = "spirit", zodiac = "tropical") {
+    const asc = engine.chartAt(natalJd, lat, lonEast, { zodiac }).angles.asc;
+    const day = isDayChart(engine, natalJd, lat, lonEast);
+    const sun = engine.longitude("sun", natalJd, { zodiac });
+    const moon = engine.longitude("moon", natalJd, { zodiac });
+    const lotLon = (lot === "spirit" ? lotSpirit : lotFortune)(asc, sun, moon, day);
+    const lotSign = ((Math.floor(lotLon / 30) % 12) + 12) % 12;
+    const active = zrActive(lotSign, natalJd, targetJd) ?? {};
+    return { lot, lot_sign: SIGNS[lotSign], day, ...active };
+}

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/dist/src/vargas.d.ts

@@ -0,0 +1,32 @@
+/**
+ * astroengine vargas -- Vedic divisional charts (vargas).
+ *
+ * A varga D-n divides each 30-degree sign into n equal parts and maps each part
+ * to a sign by a classical (Parashari) rule. This covers the unambiguous,
+ * textbook set: D1 (rasi), D3 (drekkana), D9 (navamsa), D10 (dasamsa), and D12
+ * (dwadasamsa); the contested hora (D2) and unequal trimsamsa (D30) are left to
+ * a later step. Rules (rasi/div 0-based; an "odd sign" is the 1st, 3rd, ... =
+ * even rasi index): D1 the sign; D3 (rasi + 4*div); D9 element start
+ * ([Aries, Capricorn, Libra, Cancer] by element) + div; D10 odd (rasi + div),
+ * even (rasi + 8 + div); D12 (rasi + div). Computed from rasi = floor(lon/30)
+ * and div = floor(within/(30/n)) so sign boundaries stay robust and
+ * `Math.floor` matches Python's `math.floor`. Built on the validated sidereal
+ * longitudes. Mirrors the Python reference (astroengine/vargas.py).
+ */
+import { Engine, BodyId, Zodiac } from "./chart.js";
+/** Supported divisions. */
+export declare const VARGA_DIVISIONS: readonly [1, 3, 9, 10, 12];
+export interface Varga {
+    varga: number;
+    rasi: string;
+    rasi_index: number;
+    sign: string;
+    sign_index: number;
+    division: number;
+}
+/** The varga D-n placement of a sidereal longitude. */
+export declare function varga(siderealLon: number, n: number): Varga;
+/** The varga D-n of a body (default the Moon) at jd, in a sidereal zodiac. */
+export declare function vargaAt(engine: Engine, jdUt: number, n: number, body?: BodyId, zodiac?: Zodiac): Varga;
+/** The full divisional chart D-n at jd: the varga sign of each body. */
+export declare function vargaChart(engine: Engine, jdUt: number, n: number, bodies?: BodyId[], zodiac?: Zodiac): Record<string, Varga>;

package/dist/src/vargas.js

@@ -0,0 +1,52 @@
+/**
+ * astroengine vargas -- Vedic divisional charts (vargas).
+ *
+ * A varga D-n divides each 30-degree sign into n equal parts and maps each part
+ * to a sign by a classical (Parashari) rule. This covers the unambiguous,
+ * textbook set: D1 (rasi), D3 (drekkana), D9 (navamsa), D10 (dasamsa), and D12
+ * (dwadasamsa); the contested hora (D2) and unequal trimsamsa (D30) are left to
+ * a later step. Rules (rasi/div 0-based; an "odd sign" is the 1st, 3rd, ... =
+ * even rasi index): D1 the sign; D3 (rasi + 4*div); D9 element start
+ * ([Aries, Capricorn, Libra, Cancer] by element) + div; D10 odd (rasi + div),
+ * even (rasi + 8 + div); D12 (rasi + div). Computed from rasi = floor(lon/30)
+ * and div = floor(within/(30/n)) so sign boundaries stay robust and
+ * `Math.floor` matches Python's `math.floor`. Built on the validated sidereal
+ * longitudes. Mirrors the Python reference (astroengine/vargas.py).
+ */
+import { BODIES, SIGNS } from "./chart.js";
+/** Element start sign for the navamsa (fire, earth, air, water by rasi % 4). */
+const NAVAMSA_START = [0, 9, 6, 3];
+/** Supported divisions. */
+export const VARGA_DIVISIONS = [1, 3, 9, 10, 12];
+function vargaSign(rasi, div, n) {
+    switch (n) {
+        case 1: return rasi;
+        case 3: return (rasi + 4 * div) % 12;
+        case 9: return (NAVAMSA_START[rasi % 4] + div) % 12;
+        case 10: return rasi % 2 === 0 ? (rasi + div) % 12 : (rasi + 8 + div) % 12;
+        case 12: return (rasi + div) % 12;
+        default: throw new Error(`unsupported varga D${n}`);
+    }
+}
+/** The varga D-n placement of a sidereal longitude. */
+export function varga(siderealLon, n) {
+    const lon = ((siderealLon % 360) + 360) % 360;
+    const rasi = Math.floor(lon / 30) % 12;
+    const within = lon - rasi * 30;
+    let div = Math.floor(within / (30 / n));
+    if (div >= n)
+        div = n - 1; // guard a boundary rounding to n
+    const s = vargaSign(rasi, div, n);
+    return { varga: n, rasi: SIGNS[rasi], rasi_index: rasi, sign: SIGNS[s], sign_index: s, division: div + 1 };
+}
+/** The varga D-n of a body (default the Moon) at jd, in a sidereal zodiac. */
+export function vargaAt(engine, jdUt, n, body = "moon", zodiac = "sidereal:lahiri") {
+    return varga(engine.longitude(body, jdUt, { zodiac }), n);
+}
+/** The full divisional chart D-n at jd: the varga sign of each body. */
+export function vargaChart(engine, jdUt, n, bodies = BODIES, zodiac = "sidereal:lahiri") {
+    const out = {};
+    for (const b of bodies)
+        out[b] = varga(engine.longitude(b, jdUt, { zodiac }), n);
+    return out;
+}

package/dist/src/vedic.d.ts

@@ -0,0 +1,66 @@
+/**
+ * astroengine vedic -- the Vedic/Jyotish layer: nakshatras and the Vimshottari
+ * dasha, built on the already-validated sidereal longitudes.
+ *
+ * A nakshatra is one of 27 equal lunar mansions of 13 deg 20' in the sidereal
+ * zodiac, each with four padas and a ruling planet cycling Ketu, Venus, Sun,
+ * Moon, Mars, Rahu, Jupiter, Saturn, Mercury. The Vimshottari dasha is a
+ * 120-year sequence of planetary periods in that order; the starting dasha is
+ * the lord of the Moon's birth nakshatra, with the elapsed portion set by how
+ * far the Moon has moved through it. Mahadashas subdivide into antardashas and
+ * pratyantardashas of the nine lords, proportional to their years. Nakshatra
+ * placement is exact division of the sidereal longitude; the dasha year is a
+ * fixed 365.25 days by default (the common Jyotish convention). Mirrors the
+ * Python reference (astroengine/vedic.py); the golden fixtures pin the two.
+ */
+import { Engine, BodyId, Zodiac } from "./chart.js";
+export declare const NAKSHATRAS: readonly ["Ashwini", "Bharani", "Krittika", "Rohini", "Mrigashira", "Ardra", "Punarvasu", "Pushya", "Ashlesha", "Magha", "Purva Phalguni", "Uttara Phalguni", "Hasta", "Chitra", "Swati", "Vishakha", "Anuradha", "Jyeshtha", "Mula", "Purva Ashadha", "Uttara Ashadha", "Shravana", "Dhanishta", "Shatabhisha", "Purva Bhadrapada", "Uttara Bhadrapada", "Revati"];
+/** The Vimshottari order and each lord's period in years (totalling 120). */
+export declare const VIMSHOTTARI_ORDER: readonly ["ketu", "venus", "sun", "moon", "mars", "rahu", "jupiter", "saturn", "mercury"];
+export declare const VIMSHOTTARI_YEARS: Record<(typeof VIMSHOTTARI_ORDER)[number], number>;
+export declare const NAK_SPAN: number;
+export declare const DASHA_YEAR = 365.25;
+export interface Nakshatra {
+    index: number;
+    name: string;
+    pada: number;
+    lord: string;
+    /** Degrees into the nakshatra, 0..13.333. */
+    pos: number;
+}
+/** The nakshatra of a sidereal longitude. */
+export declare function nakshatra(siderealLon: number): Nakshatra;
+/** The nakshatra of a body (default the Moon) at jd, in a sidereal zodiac. */
+export declare function nakshatraAt(engine: Engine, jdUt: number, body?: BodyId, zodiac?: Zodiac): Nakshatra;
+export interface DashaSub {
+    lord: string;
+    start: number;
+    end: number;
+}
+export interface Dasha {
+    level: number;
+    lord: string;
+    start: number;
+    end: number;
+    sub: DashaSub[];
+}
+export interface DashaTimeline {
+    start_lord: string;
+    balance_years: number;
+    dashas: Dasha[];
+}
+/** The Vimshottari dasha timeline from the Moon's sidereal longitude. */
+export declare function vimshottariDashas(moonLon: number, natalJd: number, levels?: number, yearLength?: number, count?: number): DashaTimeline;
+export interface DashaActive {
+    maha: string;
+    antar: string | null;
+    pratyantar: string | null;
+}
+/** The mahadasha, antardasha, and pratyantardasha lords active at targetJd. */
+export declare function vimshottariActive(moonLon: number, natalJd: number, targetJd: number, yearLength?: number): DashaActive | null;
+/** Vimshottari dasha active at targetJd, from the natal Moon's nakshatra. */
+export declare function vimshottariAt(engine: Engine, natalJd: number, targetJd: number, zodiac?: Zodiac, yearLength?: number): {
+    moon_nakshatra: string;
+    moon_pada: number;
+    start_lord: string;
+} & Partial<DashaActive>;

package/dist/src/vedic.js

@@ -0,0 +1,101 @@
+export const NAKSHATRAS = [
+    "Ashwini", "Bharani", "Krittika", "Rohini", "Mrigashira", "Ardra",
+    "Punarvasu", "Pushya", "Ashlesha", "Magha", "Purva Phalguni",
+    "Uttara Phalguni", "Hasta", "Chitra", "Swati", "Vishakha", "Anuradha",
+    "Jyeshtha", "Mula", "Purva Ashadha", "Uttara Ashadha", "Shravana",
+    "Dhanishta", "Shatabhisha", "Purva Bhadrapada", "Uttara Bhadrapada", "Revati",
+];
+/** The Vimshottari order and each lord's period in years (totalling 120). */
+export const VIMSHOTTARI_ORDER = [
+    "ketu", "venus", "sun", "moon", "mars", "rahu", "jupiter", "saturn", "mercury",
+];
+export const VIMSHOTTARI_YEARS = {
+    ketu: 7, venus: 20, sun: 6, moon: 10, mars: 7, rahu: 18, jupiter: 16, saturn: 19, mercury: 17,
+};
+export const NAK_SPAN = 360 / 27; // 13 deg 20'
+const VIMSHOTTARI_TOTAL = 120;
+export const DASHA_YEAR = 365.25; // days per dasha-year (common Jyotish convention)
+function mod360(x) {
+    return ((x % 360) + 360) % 360;
+}
+/** The nakshatra of a sidereal longitude. */
+export function nakshatra(siderealLon) {
+    const lon = mod360(siderealLon);
+    const i = Math.floor(lon / NAK_SPAN) % 27;
+    const pos = lon - i * NAK_SPAN;
+    const pada = Math.floor(pos / (NAK_SPAN / 4)) + 1;
+    return { index: i, name: NAKSHATRAS[i], pada, lord: VIMSHOTTARI_ORDER[i % 9], pos };
+}
+/** The nakshatra of a body (default the Moon) at jd, in a sidereal zodiac. */
+export function nakshatraAt(engine, jdUt, body = "moon", zodiac = "sidereal:lahiri") {
+    return nakshatra(engine.longitude(body, jdUt, { zodiac }));
+}
+/** The Vimshottari dasha timeline from the Moon's sidereal longitude. */
+export function vimshottariDashas(moonLon, natalJd, levels = 2, yearLength = DASHA_YEAR, count = 9) {
+    const lon = mod360(moonLon);
+    const nakI = Math.floor(lon / NAK_SPAN) % 27;
+    const pos = lon - nakI * NAK_SPAN;
+    const startLord = VIMSHOTTARI_ORDER[nakI % 9];
+    const elapsed = pos / NAK_SPAN;
+    const y0 = VIMSHOTTARI_YEARS[startLord];
+    const li = VIMSHOTTARI_ORDER.indexOf(startLord);
+    let t = natalJd - elapsed * y0 * yearLength;
+    const dashas = [];
+    for (let k = 0; k < count; k++) {
+        const lord = VIMSHOTTARI_ORDER[(li + k) % 9];
+        const years = VIMSHOTTARI_YEARS[lord];
+        const span = years * yearLength;
+        const maha = { level: 1, lord, start: t, end: t + span, sub: [] };
+        if (levels >= 2) {
+            const sli = VIMSHOTTARI_ORDER.indexOf(lord);
+            let st = t;
+            for (let j = 0; j < 9; j++) {
+                const sl = VIMSHOTTARI_ORDER[(sli + j) % 9];
+                const subSpan = (years * VIMSHOTTARI_YEARS[sl] / VIMSHOTTARI_TOTAL) * yearLength;
+                maha.sub.push({ lord: sl, start: st, end: st + subSpan });
+                st += subSpan;
+            }
+        }
+        dashas.push(maha);
+        t += span;
+    }
+    return { start_lord: startLord, balance_years: (1 - elapsed) * y0, dashas };
+}
+function activeIn(periods, target) {
+    return periods.find((p) => p.start <= target && target < p.end) ?? null;
+}
+/** The mahadasha, antardasha, and pratyantardasha lords active at targetJd. */
+export function vimshottariActive(moonLon, natalJd, targetJd, yearLength = DASHA_YEAR) {
+    const timeline = vimshottariDashas(moonLon, natalJd, 2, yearLength, 10).dashas;
+    const maha = activeIn(timeline, targetJd);
+    if (maha === null)
+        return null;
+    const antar = activeIn(maha.sub, targetJd);
+    if (antar === null)
+        return { maha: maha.lord, antar: null, pratyantar: null };
+    const ay = VIMSHOTTARI_YEARS[maha.lord]
+        * VIMSHOTTARI_YEARS[antar.lord] / VIMSHOTTARI_TOTAL;
+    const sli = VIMSHOTTARI_ORDER.indexOf(antar.lord);
+    let st = antar.start;
+    let pratyantar = null;
+    for (let j = 0; j < 9; j++) {
+        const sl = VIMSHOTTARI_ORDER[(sli + j) % 9];
+        const span = (ay * VIMSHOTTARI_YEARS[sl] / VIMSHOTTARI_TOTAL) * yearLength;
+        if (st <= targetJd && targetJd < st + span) {
+            pratyantar = sl;
+            break;
+        }
+        st += span;
+    }
+    return { maha: maha.lord, antar: antar.lord, pratyantar };
+}
+/** Vimshottari dasha active at targetJd, from the natal Moon's nakshatra. */
+export function vimshottariAt(engine, natalJd, targetJd, zodiac = "sidereal:lahiri", yearLength = DASHA_YEAR) {
+    const moonLon = engine.longitude("moon", natalJd, { zodiac });
+    const nak = nakshatra(moonLon);
+    const active = vimshottariActive(moonLon, natalJd, targetJd, yearLength) ?? {};
+    return {
+        moon_nakshatra: nak.name, moon_pada: nak.pada,
+        start_lord: VIMSHOTTARI_ORDER[nak.index % 9], ...active,
+    };
+}

package/dist/src/yogas.d.ts

@@ -0,0 +1,26 @@
+/**
+ * astroengine yogas -- classical Vedic yogas (planetary combinations) judged on
+ * the sidereal rasi (D1) chart.
+ *
+ * Covers the well-defined, placement-based yogas with no textual variation: the
+ * five Pancha Mahapurusha yogas (a non-luminary in its own sign or exaltation
+ * AND in a kendra from the Ascendant -- Ruchaka/Mars, Bhadra/Mercury,
+ * Hamsa/Jupiter, Malavya/Venus, Shasha/Saturn); Gajakesari (Jupiter in a kendra
+ * from the Moon); Budha-Aditya (Sun and Mercury in one sign); and
+ * Chandra-Mangala (Moon and Mars in one sign). Own-sign/exaltation use the
+ * engine's `dignities`; houses are whole-sign from the Ascendant. The
+ * variant-laden yogas (Kemadruma, lordship-based raja/dhana) are left to a later
+ * step. Mirrors the Python reference (astroengine/yogas.py).
+ */
+import { Engine, BodyId, Zodiac } from "./chart.js";
+export declare const YOGA_PLANETS: BodyId[];
+export interface Yoga {
+    yoga: string;
+    planets: string[];
+}
+/** The placement yogas present in a chart. `signs` maps each of the seven
+ *  classical planets to its 0-based sign index; `ascSign` is the Ascendant's
+ *  sign index. */
+export declare function detectYogas(signs: Record<string, number>, ascSign: number): Yoga[];
+/** The placement yogas of a natal chart, from the sidereal rasi positions. */
+export declare function yogasAt(engine: Engine, natalJd: number, lat: number, lonEast: number, zodiac?: Zodiac): Yoga[];