caelus 0.2.1 → 0.4.0

package/dist/src/chart.js

@@ -1,10 +1,17 @@
 /** astroengine chart -- public API: natal charts, aspects, retrogrades. */
-import { DEG, mod, jdTT, julianDay, ChebSeries, planetApparent, sunApparent, moonApparentSeries, moonApparentPrecise, plutoApparent, chironApparent, meanNode, trueNodeSeries, trueNodePrecise, } from "./core.js";
+import { DEG, mod, jdTT, julianDay, ChebSeries, planetApparent, sunApparent, moonApparentSeries, moonApparentPrecise, plutoApparent, chironApparent, meanNode, trueNodeSeries, trueNodePrecise, equatorial, ayanamsa, AYANAMSA_J2000, meanLilith, topocentricEcl, oscApogeePrecise, oscApogeeSeries, KeplerOrbit, trueObliquity, nutation, plutoHeliocentric, vsopHeliocentric, precessEcliptic, J2000, } from "./core.js";
 import * as H from "./houses.js";
+const TWO_PI = 2 * Math.PI;
 export const BODIES = [
     "sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn",
     "uranus", "neptune", "pluto", "chiron", "mean_node", "true_node",
 ];
+/** Computable on request (not in the default chart set). */
+export const EXTRA_BODIES = ["mean_lilith", "true_lilith"];
+/** Points: excluded from aspect search by default. */
+const NOT_ASPECTABLE = new Set([
+    "mean_node", "true_node", "mean_lilith", "true_lilith",
+]);
 export const SIGNS = [
     "Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra",
     "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces",
@@ -15,106 +22,291 @@ export const ASPECTS = {
 export const DEFAULT_ORBS = {
     conjunction: 8, sextile: 4, square: 7, trine: 7, opposition: 8,
 };
+const KM_PER_AU = 149597870.7;
+function parseZodiac(zodiac) {
+    if (zodiac === "tropical")
+        return null;
+    if (zodiac.startsWith("sidereal:")) {
+        const mode = zodiac.slice("sidereal:".length);
+        if (AYANAMSA_J2000[mode] !== undefined)
+            return mode;
+    }
+    throw new Error(`unknown zodiac ${JSON.stringify(zodiac)}`);
+}
+const VSOP_BODIES = new Set([
+    "mercury", "venus", "earth", "mars", "jupiter", "saturn", "uranus", "neptune",
+]);
 export class Engine {
     data;
     moonCheb;
     chironCheb;
+    packs = new Map();
     constructor(data) {
         this.data = data;
         this.moonCheb = data.moonCheb ? new ChebSeries(data.moonCheb) : null;
         this.chironCheb = data.chiron ? new ChebSeries(data.chiron) : null;
     }
+    pack(body) {
+        let s = this.packs.get(body);
+        if (!s) {
+            const raw = this.data.chebPacks?.[body];
+            const kp = this.data.keplerPack;
+            if (raw)
+                s = new ChebSeries(raw);
+            else if (kp?.bodies[body])
+                s = new KeplerOrbit(kp.bodies[body], kp.epoch);
+            else
+                throw new Error(`no data loaded for body '${body}'`);
+            this.packs.set(body, s);
+        }
+        return s;
+    }
     moonInRange(jde) {
         return !!this.moonCheb
             && this.moonCheb.jd0 <= jde - 0.1 && jde + 0.1 <= this.moonCheb.jd1;
     }
-    /** Apparent geocentric ecliptic longitude (deg), true equinox of date. */
-    longitude(body, jdUt) {
-        const jde = jdTT(jdUt);
-        let lon;
-        if (body === "sun") {
-            [lon] = sunApparent(this.data, jde);
-        }
-        else if (body === "moon") {
-            [lon] = this.moonInRange(jde)
+    /** Body ids this engine can compute, given the data it was handed. */
+    bodies() {
+        return [
+            ...[...BODIES, ...EXTRA_BODIES].filter((b) => b !== "chiron" || this.chironCheb),
+            ...Object.keys(this.data.chebPacks ?? {}),
+            ...Object.keys(this.data.keplerPack?.bodies ?? {}),
+        ];
+    }
+    /** Apparent geocentric [lon rad, lat rad, dist AU | null] at TT jde.
+     *  Building block for the events module; chart consumers want
+     *  position() instead. */
+    ecliptic(body, jde) {
+        if (body === "sun")
+            return sunApparent(this.data, jde);
+        if (body === "moon") {
+            const [lon, lat, km] = this.moonInRange(jde)
                 ? moonApparentPrecise(this.data, this.moonCheb, jde)
                 : moonApparentSeries(this.data, jde);
+            return [lon, lat, km / KM_PER_AU];
+        }
+        if (body === "pluto")
+            return plutoApparent(this.data, jde);
+        if (body === "chiron") {
+            if (!this.chironCheb)
+                throw new Error("chiron data not loaded");
+            return chironApparent(this.data, this.chironCheb, jde);
+        }
+        if (body === "mean_node")
+            return [meanNode(this.data, jde), 0.0, null];
+        if (body === "true_node") {
+            return [
+                this.moonInRange(jde)
+                    ? trueNodePrecise(this.data, this.moonCheb, jde)
+                    : trueNodeSeries(this.data, jde),
+                0.0, null,
+            ];
+        }
+        if (body === "mean_lilith") {
+            const [lon, lat] = meanLilith(this.data, jde);
+            return [lon, lat, null];
         }
-        else if (body === "pluto") {
-            [lon] = plutoApparent(this.data, jde);
+        if (body === "true_lilith") {
+            const [lon, lat, km] = this.moonInRange(jde)
+                ? oscApogeePrecise(this.data, this.moonCheb, jde)
+                : oscApogeeSeries(this.data, jde);
+            return [lon, lat, km / KM_PER_AU];
+        }
+        if (this.data.chebPacks?.[body] || this.data.keplerPack?.bodies[body]) {
+            // same heliocentric pipeline as Chiron (Chebyshev or Kepler source)
+            return chironApparent(this.data, this.pack(body), jde);
+        }
+        if (this.data.vsop[body])
+            return planetApparent(this.data, body, jde);
+        throw new Error(`no data loaded for body '${body}'`);
+    }
+    lonOnly(body, jdUt, mode, topo) {
+        const jde = jdTT(jdUt);
+        let [lon, lat, dist] = this.ecliptic(body, jde);
+        if (topo !== null && dist !== null) {
+            const lst = mod(H.gast(this.data, jdUt) + topo.lonEast * DEG, TWO_PI);
+            [lon, lat, dist] = topocentricEcl(lon, lat, dist, lst, topo.lat * DEG, topo.altM ?? 0.0, trueObliquity(this.data, jde));
+        }
+        let lonDeg = lon / DEG;
+        if (mode !== null) {
+            lonDeg = mod(lonDeg - nutation(this.data, jde)[0] / DEG - ayanamsa(jde, mode), 360);
+        }
+        return lonDeg;
+    }
+    /** Apparent geocentric ecliptic longitude (deg). Tropical: true equinox
+     *  of date. Sidereal: mean equinox minus ayanamsa. */
+    longitude(body, jdUt, opts = {}) {
+        const mode = parseZodiac(opts.zodiac ?? "tropical");
+        const topo = opts.topocentric ? opts.observer ?? null : null;
+        return this.lonOnly(body, jdUt, mode, topo);
+    }
+    /** Geometric heliocentric ecliptic of date (deg, deg, AU). */
+    heliocentric(body, jdUt) {
+        const jde = jdTT(jdUt);
+        let l;
+        let b;
+        let r;
+        if (body === "pluto") {
+            [l, b, r] = plutoHeliocentric(this.data, jde);
+            [l, b] = precessEcliptic(l, b, J2000, jde);
         }
         else if (body === "chiron") {
             if (!this.chironCheb)
                 throw new Error("chiron data not loaded");
-            [lon] = chironApparent(this.data, this.chironCheb, jde);
+            const [x, y, z] = this.chironCheb.xyz(jde);
+            r = Math.sqrt(x * x + y * y + z * z);
+            l = mod(Math.atan2(y, x), TWO_PI);
+            b = Math.atan2(z, Math.hypot(x, y));
+            [l, b] = precessEcliptic(l, b, J2000, jde);
         }
-        else if (body === "mean_node") {
-            lon = meanNode(this.data, jde);
+        else if (this.data.chebPacks?.[body] || this.data.keplerPack?.bodies[body]) {
+            const [x, y, z] = this.pack(body).xyz(jde);
+            r = Math.sqrt(x * x + y * y + z * z);
+            l = mod(Math.atan2(y, x), TWO_PI);
+            b = Math.atan2(z, Math.hypot(x, y));
+            [l, b] = precessEcliptic(l, b, J2000, jde);
         }
-        else if (body === "true_node") {
-            lon = this.moonInRange(jde)
-                ? trueNodePrecise(this.data, this.moonCheb, jde)
-                : trueNodeSeries(this.data, jde);
+        else if (VSOP_BODIES.has(body) && this.data.vsop[body]) {
+            [l, b, r] = vsopHeliocentric(this.data.vsop[body], jde);
         }
         else {
-            [lon] = planetApparent(this.data, body, jde);
+            throw new Error(`no heliocentric position for '${body}'`);
         }
-        return lon / DEG;
+        return { lon: l / DEG, lat: b / DEG, dist: r };
     }
-    /** Longitude (deg) + speed (deg/day) + retrograde flag. */
-    position(body, jdUt) {
-        const h = 0.25;
-        const lon = this.longitude(body, jdUt);
-        const l0 = this.longitude(body, jdUt - h);
-        const l1 = this.longitude(body, jdUt + h);
+    /** Full position: lon/speed/retrograde/sign + lat, dist (AU), ra, dec. */
+    position(body, jdUt, opts = {}) {
+        const mode = parseZodiac(opts.zodiac ?? "tropical");
+        const topo = opts.topocentric ? opts.observer ?? null : null;
+        const jde = jdTT(jdUt);
+        let [lonR, latR, dist] = this.ecliptic(body, jde);
+        if (topo !== null && dist !== null) {
+            const lst = mod(H.gast(this.data, jdUt) + topo.lonEast * DEG, TWO_PI);
+            [lonR, latR, dist] = topocentricEcl(lonR, latR, dist, lst, topo.lat * DEG, topo.altM ?? 0.0, trueObliquity(this.data, jde));
+        }
+        const [ra, dec] = equatorial(lonR, latR, trueObliquity(this.data, jde));
+        let lon = lonR / DEG;
+        if (mode !== null) {
+            lon = mod(lon - nutation(this.data, jde)[0] / DEG - ayanamsa(jde, mode), 360);
+        }
+        const h = 0.25; // days; central difference
+        const l0 = this.lonOnly(body, jdUt - h, mode, topo);
+        const l1 = this.lonOnly(body, jdUt + h, mode, topo);
         const speed = (mod(l1 - l0 + 540, 360) - 180) / (2 * h);
         return {
             lon, speed, retrograde: speed < 0,
             sign: SIGNS[Math.floor(lon / 30)], signDeg: mod(lon, 30),
+            lat: latR / DEG, dist,
+            ra: ra / DEG, dec: dec / DEG,
         };
     }
-    /** Full natal chart. Time is UT. East longitude positive. */
-    chart(y, mo, d, h, mi, s, lat, lonEast, houseSystem = "placidus") {
+    /** Full natal chart. Time is UT. East longitude positive. The ninth
+     *  argument takes a house system name (0.2.x form) or a ChartOptions bag. */
+    chart(y, mo, d, h, mi, s, lat, lonEast, opts = "placidus") {
+        const o = typeof opts === "string" ? { houseSystem: opts } : opts;
+        const houseSystem = o.houseSystem ?? "placidus";
+        const zodiac = o.zodiac ?? "tropical";
+        const mode = parseZodiac(zodiac);
         const jdUt = julianDay(y, mo, d, h, mi, s);
+        const calc = {
+            zodiac,
+            topocentric: o.topocentric,
+            observer: o.topocentric ? o.observer ?? { lat, lonEast, altM: 0.0 } : undefined,
+        };
+        const names = [
+            ...BODIES, ...(o.bodies ?? []).filter((b) => !BODIES.includes(b)),
+        ];
         const bodies = {};
-        for (const b of BODIES)
-            bodies[b] = this.position(b, jdUt);
+        for (const b of names)
+            bodies[b] = this.position(b, jdUt, calc);
         const [asc, mc, armc, eps] = H.angles(this.data, jdUt, lat, lonEast);
+        const [vtx, east] = H.vertexEastPoint(armc, lat * DEG, eps);
         const phi = lat * DEG;
-        let cusps;
         let used = houseSystem;
-        if (houseSystem === "placidus") {
-            if (Math.abs(lat) < 66.0) {
+        let cusps;
+        try {
+            if (houseSystem === "placidus") {
+                if (Math.abs(lat) >= 66.0) {
+                    throw new RangeError("placidus undefined above polar circles");
+                }
                 cusps = H.housesPlacidus(armc, phi, eps);
             }
-            else {
-                used = "whole_sign"; // Placidus undefined above polar circles
+            else if (houseSystem === "porphyry") {
+                cusps = H.housesPorphyry(asc, mc);
+            }
+            else if (houseSystem === "equal") {
+                cusps = H.housesEqual(asc);
+            }
+            else if (houseSystem === "whole_sign") {
                 cusps = H.housesWholeSign(asc);
             }
+            else if (houseSystem === "koch") {
+                cusps = H.housesKoch(armc, phi, eps);
+            }
+            else if (houseSystem === "regiomontanus") {
+                cusps = H.housesRegiomontanus(armc, phi, eps);
+            }
+            else if (houseSystem === "campanus") {
+                cusps = H.housesCampanus(armc, phi, eps);
+            }
+            else if (houseSystem === "alcabitius") {
+                cusps = H.housesAlcabitius(armc, phi, eps);
+            }
+            else if (houseSystem === "morinus") {
+                cusps = H.housesMorinus(armc, phi, eps);
+            }
+            else if (houseSystem === "meridian") {
+                cusps = H.housesMeridian(armc, phi, eps);
+            }
+            else if (houseSystem === "polich_page") {
+                cusps = H.housesPolichPage(armc, phi, eps);
+            }
+            else if (houseSystem === "vehlow") {
+                cusps = H.housesVehlow(armc, phi, eps);
+            }
+            else {
+                throw new Error(`unknown house system '${houseSystem}'`);
+            }
         }
-        else if (houseSystem === "porphyry") {
-            cusps = H.housesPorphyry(asc, mc);
+        catch (err) {
+            if (!(err instanceof RangeError))
+                throw err;
+            used = "whole_sign"; // Placidus/Koch undefined above polar circles
+            cusps = H.housesWholeSign(asc);
         }
-        else if (houseSystem === "equal") {
-            cusps = H.housesEqual(asc);
+        const jde = jdTT(jdUt);
+        let shift = 0.0;
+        if (mode !== null) {
+            shift = nutation(this.data, jde)[0] / DEG + ayanamsa(jde, mode);
+        }
+        const outDeg = (rad) => mod(rad / DEG - shift, 360);
+        let cuspsDeg;
+        if (mode !== null && used === "whole_sign") {
+            // whole-sign cusps must stay sign-aligned in the sidereal zodiac
+            const first = Math.floor(outDeg(asc) / 30) * 30.0;
+            cuspsDeg = Array.from({ length: 12 }, (_, i) => mod(first + i * 30.0, 360));
         }
         else {
-            cusps = H.housesWholeSign(asc);
+            cuspsDeg = cusps.map(outDeg);
         }
         return {
             jdUt,
+            zodiac,
             houseSystem: used,
             houseSystemRequested: houseSystem,
             bodies,
-            angles: { asc: asc / DEG, mc: mc / DEG },
-            cusps: cusps.map((c) => c / DEG),
-            aspects: findAspects(bodies),
+            angles: {
+                asc: outDeg(asc), mc: outDeg(mc),
+                vertex: outDeg(vtx), eastPoint: outDeg(east),
+            },
+            cusps: cuspsDeg,
+            aspects: findAspects(bodies, o.orbs ?? DEFAULT_ORBS),
         };
     }
 }
 export function findAspects(bodies, orbs = DEFAULT_ORBS) {
     const out = [];
-    const names = Object.keys(bodies).filter((b) => !b.endsWith("_node"));
+    const names = Object.keys(bodies).filter((b) => !NOT_ASPECTABLE.has(b));
     for (let i = 0; i < names.length; i++) {
         for (let j = i + 1; j < names.length; j++) {
             const a = names[i];
@@ -134,5 +326,5 @@ export function fmtLon(deg) {
     const sign = SIGNS[Math.floor(deg / 30)];
     const d = mod(deg, 30);
     const m = mod(d, 1) * 60;
-    return `${String(Math.floor(d)).padStart(2)}\u00b0${String(Math.floor(m)).padStart(2, "0")}' ${sign}`;
+    return `${String(Math.floor(d)).padStart(2)}°${String(Math.floor(m)).padStart(2, "0")}' ${sign}`;
 }

package/dist/src/core.d.ts

@@ -26,6 +26,24 @@ export type ChebData = {
     scale?: number;
     segments: number[][][];
 };
+export type KeplerElements = {
+    a: number;
+    e: number;
+    i: number;
+    node: number;
+    peri: number;
+    M0: number;
+    n: number;
+};
+export type KeplerPack = {
+    epoch: number;
+    bodies: Record<string, KeplerElements>;
+};
+/** Anything that yields heliocentric ecliptic-J2000 xyz (AU) at a TT jd:
+ *  ChebSeries (fitted small bodies) or KeplerOrbit (Uranian bodies). */
+export interface XyzSource {
+    xyz(jd: number): [number, number, number];
+}
 export interface EngineData {
     vsop: Record<string, VsopSeries>;
     nutation: number[][];
@@ -33,6 +51,11 @@ export interface EngineData {
     pluto: number[][];
     chiron?: ChebData;
     moonCheb?: ChebData;
+    /** Heliocentric ecliptic-J2000 Chebyshev packs by body id (ceres,
+     *  pallas, juno, vesta, pholus, ...). Same pipeline as Chiron. */
+    chebPacks?: Record<string, ChebData>;
+    /** Hamburg-school (Uranian) constant-element orbits; see fit_uranian.py. */
+    keplerPack?: KeplerPack;
 }
 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,
@@ -68,5 +91,38 @@ export declare function trueNodePrecise(data: EngineData, cheb: ChebSeries, jde:
 export declare function meanNode(data: EngineData, jde: number): number;
 /** Osculating node from the series moon (fallback outside Chebyshev range). */
 export declare function trueNodeSeries(data: EngineData, jde: number): number;
+/** Ecliptic lon/lat -> right ascension, declination (all radians). */
+export declare function equatorial(lon: number, lat: number, eps: number): [number, number];
+/** Mean ayanamsa at J2000.0 (degrees) per mode. Standard epoch anchors
+ *  (matched to Swiss Ephemeris 2.10 to 1e-9 deg); propagation uses IAU 1976
+ *  ecliptic precession. Agreement with Swiss Ephemeris over 1900-2099 is
+ *  <=0.30 arcsec (precession-model difference: SE uses Vondrak 2011). */
+export declare const AYANAMSA_J2000: Record<string, number>;
+/** Mean ayanamsa in degrees. Sidereal longitude = (tropical true-equinox
+ *  longitude - nutation in longitude) - ayanamsa: the sidereal zodiac is
+ *  anchored to the mean equinox. */
+export declare function ayanamsa(jde: number, mode: string): number;
+/** Mean lunar apogee (Black Moon Lilith) on the inclined lunar orbit:
+ *  apparent lon (true equinox) and orbital latitude, radians. */
+export declare function meanLilith(data: EngineData, jde: number): [number, number];
+/** Osculating lunar apogee (True Lilith) from the Chebyshev moon. */
+export declare function oscApogeePrecise(data: EngineData, cheb: ChebSeries, jde: number): [number, number, number];
+/** Series fallback outside the Chebyshev range (same finite-difference
+ *  state as the true-node fallback). */
+export declare function oscApogeeSeries(data: EngineData, jde: number): [number, number, number];
+/** Constant-element two-body orbit with the same xyz(jde) interface as
+ *  ChebSeries, so chironApparent takes either. */
+export declare class KeplerOrbit implements XyzSource {
+    private els;
+    private epoch;
+    constructor(els: KeplerElements, epoch: number);
+    xyz(jde: number): [number, number, number];
+}
+export declare const EARTH_RADIUS_AU: number;
+/** Diurnal parallax in ecliptic coordinates (Meeus ch. 11/40).
+ *  lst = local apparent sidereal time (rad). Returns [lon, lat, distAu]. */
+export declare function topocentricEcl(lon: number, lat: number, distAu: number, lst: number, obsLat: number, altM: number, eps: number): [number, number, number];
+/** Meeus ch.37 heliocentric Pluto, ecliptic J2000: [l rad, b rad, r AU]. */
+export declare function plutoHeliocentric(data: EngineData, jde: number): [number, number, number];
 export declare function plutoApparent(data: EngineData, jde: number): [number, number, number];
-export declare function chironApparent(data: EngineData, cheb: ChebSeries, jde: number): [number, number, number];
+export declare function chironApparent(data: EngineData, cheb: XyzSource, jde: number): [number, number, number];

package/dist/src/core.js

@@ -377,30 +377,177 @@ export function trueNodeSeries(data, jde) {
     const node = mod(Math.atan2(hx, -hy), TWO_PI);
     return mod(node + nutation(data, jde)[0], TWO_PI);
 }
-// ---------------------------------------------------------------- pluto
-export function plutoApparent(data, jde) {
-    const helioJ2000 = (tJde) => {
-        const T = (tJde - J2000) / 36525.0;
-        const J = (34.35 + 3034.9057 * T) * DEG;
-        const S = (50.08 + 1222.1138 * T) * DEG;
-        const P = (238.96 + 144.96 * T) * DEG;
-        let l = 0.0;
-        let b = 0.0;
-        let r = 0.0;
-        for (const [i, j, k, lA, lB, bA, bB, rA, rB] of data.pluto) {
-            const a = i * J + j * S + k * P;
-            const sa = Math.sin(a);
-            const ca = Math.cos(a);
-            l += lA * sa + lB * ca;
-            b += bA * sa + bB * ca;
-            r += rA * sa + rB * ca;
-        }
+// ---------------------------------------------------------------- frames+
+/** Ecliptic lon/lat -> right ascension, declination (all radians). */
+export function equatorial(lon, lat, eps) {
+    const ra = mod(Math.atan2(Math.sin(lon) * Math.cos(eps) - Math.tan(lat) * Math.sin(eps), Math.cos(lon)), TWO_PI);
+    const dec = Math.asin(Math.sin(lat) * Math.cos(eps) + Math.cos(lat) * Math.sin(eps) * Math.sin(lon));
+    return [ra, dec];
+}
+/** Mean ayanamsa at J2000.0 (degrees) per mode. Standard epoch anchors
+ *  (matched to Swiss Ephemeris 2.10 to 1e-9 deg); propagation uses IAU 1976
+ *  ecliptic precession. Agreement with Swiss Ephemeris over 1900-2099 is
+ *  <=0.30 arcsec (precession-model difference: SE uses Vondrak 2011). */
+export const AYANAMSA_J2000 = {
+    lahiri: 23.857092325,
+    fagan_bradley: 24.740299966,
+    krishnamurti: 23.760240012,
+    raman: 22.410791012,
+    yukteshwar: 22.478803000,
+};
+/** Mean ayanamsa in degrees. Sidereal longitude = (tropical true-equinox
+ *  longitude - nutation in longitude) - ayanamsa: the sidereal zodiac is
+ *  anchored to the mean equinox. */
+export function ayanamsa(jde, mode) {
+    const a0 = AYANAMSA_J2000[mode];
+    if (a0 === undefined)
+        throw new Error(`unknown ayanamsa ${mode}`);
+    const [lon] = precessEcliptic(a0 * DEG, 0.0, J2000, jde);
+    return lon / DEG;
+}
+/** Mean lunar apogee (Black Moon Lilith) on the inclined lunar orbit:
+ *  apparent lon (true equinox) and orbital latitude, radians. */
+export function meanLilith(data, jde) {
+    const T = (jde - J2000) / 36525.0;
+    const [Lp, , , Mp] = moonFundamental(T);
+    const apog = Lp - Mp + Math.PI; // mean perigee + 180
+    const om = (125.0445479 - 1934.1362891 * T + 0.0020754 * T * T
+        + T ** 3 / 467441 - T ** 4 / 60616000) * DEG;
+    const inc = 5.145396374 * DEG;
+    const u = apog - om;
+    const lat = Math.asin(Math.sin(inc) * Math.sin(u));
+    let lon = om + Math.atan2(Math.cos(inc) * Math.sin(u), Math.cos(u));
+    lon = mod(lon + nutation(data, jde)[0], TWO_PI);
+    return [lon, lat];
+}
+const GM_EARTH_MOON = 403503.2356 * 86400.0 ** 2; // km^3/day^2
+/** Osculating apogee point from a geocentric lunar state vector (km,
+ *  km/day): apparent ecliptic lon/lat of date (rad) + distance (km).
+ *  Hypersensitive to the lunar theory: the eccentricity vector amplifies
+ *  position/velocity differences ~1/e (~18x). Swiss Ephemeris in Moshier
+ *  mode differs from our DE423 fit by up to ~3 arcmin here; published
+ *  'True Lilith' values disagree across software at that scale. */
+function oscApogeeFromState(data, x, y, z, vx, vy, vz, jde, frameJ2000) {
+    const mu = GM_EARTH_MOON;
+    const r = Math.sqrt(x * x + y * y + z * z);
+    const v2 = vx * vx + vy * vy + vz * vz;
+    const rv = x * vx + y * vy + z * vz;
+    const ex = (v2 * x - rv * vx) / mu - x / r;
+    const ey = (v2 * y - rv * vy) / mu - y / r;
+    const ez = (v2 * z - rv * vz) / mu - z / r;
+    const e = Math.sqrt(ex * ex + ey * ey + ez * ez);
+    const a = 1.0 / (2.0 / r - v2 / mu);
+    const s = (a * (1 + e)) / e;
+    let px = -ex * s;
+    let py = -ey * s;
+    let pz = -ez * s;
+    if (frameJ2000)
+        [px, py, pz] = eclJ2000ToEclDate([px, py, pz], jde);
+    const lon = mod(Math.atan2(py, px) + nutation(data, jde)[0], TWO_PI);
+    const lat = Math.atan2(pz, Math.hypot(px, py));
+    return [lon, lat, Math.sqrt(px * px + py * py + pz * pz)];
+}
+/** Osculating lunar apogee (True Lilith) from the Chebyshev moon. */
+export function oscApogeePrecise(data, cheb, jde) {
+    const [[x, y, z], [vx, vy, vz]] = cheb.xyzVel(jde);
+    return oscApogeeFromState(data, x, y, z, vx, vy, vz, jde, true);
+}
+/** Series fallback outside the Chebyshev range (same finite-difference
+ *  state as the true-node fallback). */
+export function oscApogeeSeries(data, jde) {
+    const h = 0.01;
+    const xyz = (t) => {
+        const [lon, lat, dist] = moonGeometric(data, t);
         return [
-            (l + 238.958116 + 144.96 * T) * DEG,
-            (b - 3.908239) * DEG,
-            r + 40.7241346,
+            dist * Math.cos(lat) * Math.cos(lon),
+            dist * Math.cos(lat) * Math.sin(lon),
+            dist * Math.sin(lat),
         ];
     };
+    const [x0, y0, z0] = xyz(jde - h);
+    const [x1, y1, z1] = xyz(jde + h);
+    const [x, y, z] = xyz(jde);
+    return oscApogeeFromState(data, x, y, z, (x1 - x0) / (2 * h), (y1 - y0) / (2 * h), (z1 - z0) / (2 * h), jde, false);
+}
+/** Constant-element two-body orbit with the same xyz(jde) interface as
+ *  ChebSeries, so chironApparent takes either. */
+export class KeplerOrbit {
+    els;
+    epoch;
+    constructor(els, epoch) {
+        this.els = els;
+        this.epoch = epoch;
+    }
+    xyz(jde) {
+        const { a, e, i, node, peri: w, M0, n } = this.els;
+        const M = M0 + n * (jde - this.epoch);
+        let E = M;
+        for (let k = 0; k < 30; k++) {
+            E = E - (E - e * Math.sin(E) - M) / (1 - e * Math.cos(E));
+        }
+        const xv = a * (Math.cos(E) - e);
+        const yv = a * Math.sqrt(1 - e * e) * Math.sin(E);
+        const cw = Math.cos(w);
+        const sw = Math.sin(w);
+        const cn = Math.cos(node);
+        const sn = Math.sin(node);
+        const ci = Math.cos(i);
+        const si = Math.sin(i);
+        const xp = xv * cw - yv * sw;
+        const yp = xv * sw + yv * cw;
+        return [xp * cn - yp * sn * ci, xp * sn + yp * cn * ci, yp * si];
+    }
+}
+export const EARTH_RADIUS_AU = 6378.14 / 149597870.7;
+const EARTH_FLAT = 0.99664719; // 1 - f, IAU 1976 figure
+/** Diurnal parallax in ecliptic coordinates (Meeus ch. 11/40).
+ *  lst = local apparent sidereal time (rad). Returns [lon, lat, distAu]. */
+export function topocentricEcl(lon, lat, distAu, lst, obsLat, altM, eps) {
+    const u = Math.atan(EARTH_FLAT * Math.tan(obsLat));
+    const rs = EARTH_FLAT * Math.sin(u) + (altM / 6378140.0) * Math.sin(obsLat);
+    const rc = Math.cos(u) + (altM / 6378140.0) * Math.cos(obsLat);
+    const ox = EARTH_RADIUS_AU * rc * Math.cos(lst);
+    const oy = EARTH_RADIUS_AU * rc * Math.sin(lst);
+    const oz = EARTH_RADIUS_AU * rs;
+    const [ra, dec] = equatorial(lon, lat, eps);
+    const bx = distAu * Math.cos(dec) * Math.cos(ra);
+    const by = distAu * Math.cos(dec) * Math.sin(ra);
+    const bz = distAu * Math.sin(dec);
+    const tx = bx - ox;
+    const ty = by - oy;
+    const tz = bz - oz;
+    const ra2 = Math.atan2(ty, tx);
+    const dec2 = Math.atan2(tz, Math.hypot(tx, ty));
+    const lon2 = mod(Math.atan2(Math.sin(ra2) * Math.cos(eps) + Math.tan(dec2) * Math.sin(eps), Math.cos(ra2)), TWO_PI);
+    const lat2 = Math.asin(Math.sin(dec2) * Math.cos(eps) - Math.cos(dec2) * Math.sin(eps) * Math.sin(ra2));
+    return [lon2, lat2, Math.sqrt(tx * tx + ty * ty + tz * tz)];
+}
+// ---------------------------------------------------------------- pluto
+/** Meeus ch.37 heliocentric Pluto, ecliptic J2000: [l rad, b rad, r AU]. */
+export function plutoHeliocentric(data, jde) {
+    const T = (jde - J2000) / 36525.0;
+    const J = (34.35 + 3034.9057 * T) * DEG;
+    const S = (50.08 + 1222.1138 * T) * DEG;
+    const P = (238.96 + 144.96 * T) * DEG;
+    let l = 0.0;
+    let b = 0.0;
+    let r = 0.0;
+    for (const [i, j, k, lA, lB, bA, bB, rA, rB] of data.pluto) {
+        const a = i * J + j * S + k * P;
+        const sa = Math.sin(a);
+        const ca = Math.cos(a);
+        l += lA * sa + lB * ca;
+        b += bA * sa + bB * ca;
+        r += rA * sa + rB * ca;
+    }
+    return [
+        (l + 238.958116 + 144.96 * T) * DEG,
+        (b - 3.908239) * DEG,
+        r + 40.7241346,
+    ];
+}
+export function plutoApparent(data, jde) {
+    const helioJ2000 = (tJde) => plutoHeliocentric(data, tJde);
     const [L0d, B0d, R0d] = vsopHeliocentric(data.vsop.earth, jde);
     const [Lj, Bj] = precessEcliptic(L0d, B0d, jde, J2000);
     const ex = R0d * Math.cos(Bj) * Math.cos(Lj);

package/dist/src/events.d.ts

@@ -0,0 +1,22 @@
+import { Engine, BodyId, Zodiac } from "./chart.js";
+export type RiseKind = "rise" | "set" | "mtransit" | "itransit";
+export interface RiseSetOptions {
+    altM?: number;
+    pressure?: number;
+    tempC?: number;
+    searchDays?: number;
+}
+/** Next rise/set/meridian transit (UT JD) after jdStart, or null when the
+ *  event does not occur in the window (polar day/night). */
+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. */
+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"]>;