caelus 0.2.1 → 0.4.0

package/dist/src/events.js

@@ -0,0 +1,156 @@
+/**
+ * astroengine events -- rise/set/meridian transits, zodiac crossings,
+ * lunar phases, stations.
+ *
+ * Rise/set condition (matches Swiss Ephemeris defaults, calibrated against
+ * swe_rise_trans at standard pressure/temperature): the topocentric true
+ * altitude of the disc center equals -(R0 + topocentric semidiameter),
+ * with R0 = 34.076 arcmin scaled by (pressure/1010)(283/(273+temp)). All
+ * searches are bracketed sign changes refined by bisection; speeds come
+ * from the same apparent-position pipeline as the chart API, so retrograde
+ * loops and multiple crossings are found, not assumed away.
+ */
+import { DEG, mod, jdTT, equatorial, trueObliquity, topocentricEcl, } from "./core.js";
+import { gast } from "./houses.js";
+import { DIAMETER_KM } from "./pheno.js";
+const TWO_PI = 2 * Math.PI;
+const KM_PER_AU = 149597870.7;
+const R0_ARCMIN = 34.076; // horizon refraction at 1010 hPa / 10 C (vs SE)
+function topoAltHa(engine, body, jdUt, latDeg, lonDeg, altM) {
+    const jde = jdTT(jdUt);
+    let [lon, lat, dist] = engine.ecliptic(body, jde);
+    const eps = trueObliquity(engine.data, jde);
+    const lst = mod(gast(engine.data, jdUt) + lonDeg * DEG, TWO_PI);
+    if (dist !== null) {
+        [lon, lat, dist] = topocentricEcl(lon, lat, dist, lst, latDeg * DEG, altM, eps);
+    }
+    const [ra, dec] = equatorial(lon, lat, eps);
+    const ha = mod(lst - ra + Math.PI, TWO_PI) - Math.PI;
+    const phi = latDeg * DEG;
+    const alt = Math.asin(Math.sin(phi) * Math.sin(dec) + Math.cos(phi) * Math.cos(dec) * Math.cos(ha));
+    return [alt, ha, dist];
+}
+function bisect(f, a, b, iters = 45) {
+    let fa = f(a);
+    for (let i = 0; i < iters; i++) {
+        const m = (a + b) / 2;
+        if (fa * f(m) <= 0) {
+            b = m;
+        }
+        else {
+            a = m;
+            fa = f(a);
+        }
+    }
+    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). */
+export function riseSet(engine, body, jdStart, latDeg, lonDeg, kind = "rise", opts = {}) {
+    const altM = opts.altM ?? 0.0;
+    const pressure = opts.pressure ?? 1013.25;
+    const tempC = opts.tempC ?? 15.0;
+    const searchDays = opts.searchDays ?? 2.0;
+    const scale = (pressure / 1010.0) * (283.0 / (273.0 + tempC));
+    if (kind === "mtransit" || kind === "itransit") {
+        const target = kind === "mtransit" ? 0.0 : Math.PI;
+        const g = (t) => {
+            const [, ha] = topoAltHa(engine, body, t, latDeg, lonDeg, altM);
+            return mod(ha - target + Math.PI, TWO_PI) - Math.PI;
+        };
+        const step = 1.0 / 48;
+        let prev = g(jdStart);
+        for (let t = jdStart + step; t <= jdStart + searchDays; t += step) {
+            const cur = g(t);
+            if (prev * cur < 0 && Math.abs(cur - prev) < Math.PI) {
+                return bisect(g, t - step, t);
+            }
+            prev = cur;
+        }
+        return null;
+    }
+    const f = (t) => {
+        const [alt, , dist] = topoAltHa(engine, body, t, latDeg, lonDeg, altM);
+        let sd = 0.0;
+        const diam = DIAMETER_KM[body];
+        if (diam !== undefined && dist !== null) {
+            sd = Math.asin(diam / (2 * dist * KM_PER_AU));
+        }
+        const h0 = -((R0_ARCMIN / 60.0) * scale * DEG + sd);
+        return alt - h0;
+    };
+    const step = 1.0 / 48; // 30 min: well under the fastest crossing scale
+    let prev = f(jdStart);
+    for (let t = jdStart + step; t <= jdStart + searchDays; t += step) {
+        const cur = f(t);
+        if ((kind === "rise" && prev < 0 && cur >= 0)
+            || (kind === "set" && prev > 0 && cur <= 0)) {
+            return bisect(f, t - step, t);
+        }
+        prev = cur;
+    }
+    return 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 function crossings(engine, body, targetLon, jdStart, jdEnd, zodiac = "tropical", maxHits = 60) {
+    const f = (t) => mod(engine.longitude(body, t, { zodiac }) - targetLon + 180, 360) - 180;
+    const fast = body === "moon" || body === "mean_node"
+        || body === "true_node" || body === "mean_lilith" || body === "true_lilith";
+    const step = fast ? 0.25 : 1.0;
+    const out = [];
+    let prev = f(jdStart);
+    for (let t = jdStart + step; t <= jdEnd && out.length < maxHits; t += step) {
+        const cur = f(t);
+        if (prev * cur < 0 && Math.abs(cur - prev) < 180) {
+            out.push(bisect(f, t - step, t));
+        }
+        prev = cur;
+    }
+    return out;
+}
+/** New/first-quarter/full/last-quarter times in [jdStart, jdEnd], sorted. */
+export function lunarPhases(engine, jdStart, jdEnd, maxHits = 60) {
+    const elong = (t) => mod(engine.longitude("moon", t) - engine.longitude("sun", t), 360);
+    const names = [
+        [0, "new"], [90, "first_quarter"], [180, "full"], [270, "last_quarter"],
+    ];
+    const out = [];
+    const step = 0.25;
+    for (const [angle, name] of names) {
+        const f = (t) => mod(elong(t) - angle + 180, 360) - 180;
+        let prev = f(jdStart);
+        for (let t = jdStart + step; t <= jdEnd && out.length < maxHits; t += step) {
+            const cur = f(t);
+            if (prev * cur < 0 && Math.abs(cur - prev) < 180) {
+                out.push([bisect(f, t - step, t), name]);
+            }
+            prev = cur;
+        }
+    }
+    out.sort((a, b) => a[0] - b[0]);
+    return out;
+}
+/** 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 function stations(engine, body, jdStart, jdEnd, maxHits = 30) {
+    const h = 0.25;
+    const speed = (t) => {
+        const l0 = engine.longitude(body, t - h);
+        const l1 = engine.longitude(body, t + h);
+        return (mod(l1 - l0 + 540, 360) - 180) / (2 * h);
+    };
+    const step = 2.0;
+    const out = [];
+    let prev = speed(jdStart);
+    for (let t = jdStart + step; t <= jdEnd && out.length < maxHits; t += step) {
+        const cur = speed(t);
+        if (prev * cur < 0) {
+            out.push([bisect(speed, t - step, t), prev > 0 ? "retrograde" : "direct"]);
+        }
+        prev = cur;
+    }
+    return out;
+}

package/dist/src/houses.d.ts

@@ -4,11 +4,42 @@ import { EngineData } from "./core.js";
 export declare function gmst(jdUt: number): number;
 /** Greenwich apparent sidereal time. */
 export declare function gast(data: EngineData, jdUt: number): number;
+/** Ecliptic longitude where the house circle with pole `pole` crosses the
+ *  ecliptic; `ra` measured like ARMC. The Ascendant is houseCusp(armc+90,
+ *  phi); the MC is houseCusp(armc, 0). */
+export declare function houseCusp(ra: number, pole: number, eps: number): number;
 /** Ascendant, MC, ARMC, obliquity. East longitude positive. */
 export declare function angles(data: EngineData, jdUt: number, latDeg: number, lonDeg: number): [number, number, number, number];
+/** Vertex (western crossing of prime vertical and ecliptic) and east
+ *  point (equatorial ascendant). Radians in, radians out. */
+export declare function vertexEastPoint(armc: number, phi: number, eps: number): [number, number];
 export declare function housesWholeSign(asc: number): number[];
 export declare function housesEqual(asc: number): number[];
 export declare function housesPorphyry(asc: number, mc: number): number[];
+/** Koch (birthplace): cusps are ascendants at ARMC +/- k/3 of the MC
+ *  degree's diurnal semi-arc. Throws where the MC degree is circumpolar
+ *  (|phi| >= 90 - eps, matching Swiss Ephemeris). */
+export declare function housesKoch(armc: number, phi: number, eps: number): number[];
+/** Regiomontanus: equal divisions of the celestial equator; cusp poles
+ *  tan P = tan(phi) sin(H). */
+export declare function housesRegiomontanus(armc: number, phi: number, eps: number): number[];
+/** Campanus: equal divisions of the prime vertical. House circles run
+ *  through the horizon's north/south points; cusps are their ecliptic
+ *  crossings, assigned in zodiacal order MC->ASC->IC. */
+export declare function housesCampanus(armc: number, phi: number, eps: number): number[];
+/** Alcabitius: trisect the Ascendant degree's semi-arcs in right ascension;
+ *  project cusps along meridians. */
+export declare function housesAlcabitius(armc: number, phi: number, eps: number): number[];
+/** Morinus: equal RA divisions projected onto the ecliptic by great circles
+ *  through the ecliptic poles. Latitude-independent. */
+export declare function housesMorinus(armc: number, _phi: number, eps: number): number[];
+/** Meridian (axial rotation): equal RA divisions projected along hour
+ *  circles. Latitude-independent. */
+export declare function housesMeridian(armc: number, _phi: number, eps: number): number[];
+/** Polich-Page ('topocentric'): cusp poles tan P = (k/3) tan(phi). */
+export declare function housesPolichPage(armc: number, phi: number, eps: number): 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

package/dist/src/houses.js

@@ -15,16 +15,49 @@ export function gast(data, jdUt) {
     const eps = trueObliquity(data, jde);
     return mod(gmst(jdUt) + dpsi * Math.cos(eps), TWO_PI);
 }
+/** Ecliptic longitude where the house circle with pole `pole` crosses the
+ *  ecliptic; `ra` measured like ARMC. The Ascendant is houseCusp(armc+90,
+ *  phi); the MC is houseCusp(armc, 0). */
+export function houseCusp(ra, pole, eps) {
+    return mod(Math.atan2(Math.sin(ra), Math.cos(ra) * Math.cos(eps) - Math.sin(eps) * Math.tan(pole)), TWO_PI);
+}
+function mcOf(armc, eps) {
+    return mod(Math.atan2(Math.sin(armc), Math.cos(armc) * Math.cos(eps)), TWO_PI);
+}
+/** Ascendant with the polar-latitude convention: the ASC always lies in
+ *  the half-circle (MC, MC+180). Above ~66 deg the raw horizon intersection
+ *  can be the setting one; Swiss Ephemeris applies the same correction. */
+function ascOf(armc, phi, eps) {
+    let asc = houseCusp(armc + Math.PI / 2, phi, eps);
+    if (mod(asc - mcOf(armc, eps), TWO_PI) >= Math.PI) {
+        asc = mod(asc + Math.PI, TWO_PI);
+    }
+    return asc;
+}
 /** Ascendant, MC, ARMC, obliquity. East longitude positive. */
 export function angles(data, jdUt, latDeg, lonDeg) {
     const jde = jdTT(jdUt);
     const eps = trueObliquity(data, jde);
     const armc = mod(gast(data, jdUt) + lonDeg * DEG, TWO_PI);
     const phi = latDeg * DEG;
-    const mc = mod(Math.atan2(Math.sin(armc), Math.cos(armc) * Math.cos(eps)), TWO_PI);
-    const asc = mod(Math.atan2(Math.cos(armc), -(Math.sin(armc) * Math.cos(eps) + Math.tan(phi) * Math.sin(eps))), TWO_PI);
+    const mc = mcOf(armc, eps);
+    const asc = ascOf(armc, phi, eps);
     return [asc, mc, armc, eps];
 }
+/** Vertex (western crossing of prime vertical and ecliptic) and east
+ *  point (equatorial ascendant). Radians in, radians out. */
+export function vertexEastPoint(armc, phi, eps) {
+    const colat = phi >= 0 ? Math.PI / 2 - phi : -Math.PI / 2 - phi;
+    let vtx = houseCusp(armc + (3 * Math.PI) / 2, colat, eps);
+    // pick the western intersection: equatorial direction . east-point < 0
+    const dx = Math.cos(vtx);
+    const dy = Math.sin(vtx) * Math.cos(eps);
+    if (dx * -Math.sin(armc) + dy * Math.cos(armc) > 0) {
+        vtx = mod(vtx + Math.PI, TWO_PI);
+    }
+    const east = houseCusp(armc + Math.PI / 2, 0.0, eps);
+    return [vtx, east];
+}
 export function housesWholeSign(asc) {
     const first = Math.floor(asc / (30 * DEG)) * 30 * DEG;
     return Array.from({ length: 12 }, (_, i) => mod(first + i * 30 * DEG, TWO_PI));
@@ -53,6 +86,176 @@ export function housesPorphyry(asc, mc) {
     cusps[8] = mod(cusps[2] + Math.PI, TWO_PI);
     return cusps;
 }
+function signed(x) {
+    return mod(x + Math.PI, TWO_PI) - Math.PI;
+}
+function fillOpposites(out) {
+    for (const k of [3, 4, 5])
+        out[k] = mod(out[k + 6] + Math.PI, TWO_PI);
+    for (const k of [6, 7, 8])
+        out[k] = mod(out[k - 6] + Math.PI, TWO_PI);
+    return out;
+}
+/** Cusps 1 and 10. With flipMc (Regiomontanus, Campanus, Polich-Page), the
+ *  MC moves to the IC when the polar ASC correction fires, keeping the cusps
+ *  in zodiacal order; Swiss Ephemeris does the same. Alcabitius and Koch
+ *  keep the astronomical MC. */
+function quadrantFrame(armc, phi, eps, flipMc) {
+    const out = new Array(12).fill(0);
+    let mc = mcOf(armc, eps);
+    let asc = houseCusp(armc + Math.PI / 2, phi, eps);
+    if (mod(asc - mc, TWO_PI) >= Math.PI) {
+        asc = mod(asc + Math.PI, TWO_PI);
+        if (flipMc)
+            mc = mod(mc + Math.PI, TWO_PI);
+    }
+    out[0] = asc;
+    out[9] = mc;
+    return out;
+}
+/** Every quadrant-system house circle passes through the horizon's
+ *  north/south points, so its two ecliptic crossings sit east and west of
+ *  the meridian. Cusps 11, 12, 2, 3 are the eastern ones. */
+function eastOfMeridian(lon, armc, eps) {
+    const ra = Math.atan2(Math.sin(lon) * Math.cos(eps), Math.cos(lon));
+    if (Math.sin(armc - ra) > 0)
+        return mod(lon + Math.PI, TWO_PI);
+    return lon;
+}
+/** Force a cusp candidate onto the short arc from lo spanning the signed
+ *  angle d (negative when the polar ASC correction reverses the zodiacal
+ *  direction of the house sequence). */
+function normArc(lon, lo, d) {
+    const off = signed(lon - lo);
+    const inside = d >= 0 ? off >= 0 && off <= d : off >= d && off <= 0;
+    return inside ? lon : mod(lon + Math.PI, TWO_PI);
+}
+/** Koch (birthplace): cusps are ascendants at ARMC +/- k/3 of the MC
+ *  degree's diurnal semi-arc. Throws where the MC degree is circumpolar
+ *  (|phi| >= 90 - eps, matching Swiss Ephemeris). */
+export function housesKoch(armc, phi, eps) {
+    if (Math.abs(phi) >= Math.PI / 2 - eps) {
+        throw new RangeError("koch undefined at polar latitudes");
+    }
+    const out = quadrantFrame(armc, phi, eps, false);
+    const decMc = Math.asin(Math.sin(eps) * Math.sin(out[9]));
+    const x = Math.tan(phi) * Math.tan(decMc);
+    if (Math.abs(x) > 1) {
+        throw new RangeError("koch undefined: MC degree circumpolar");
+    }
+    const sa = Math.PI / 2 + Math.asin(x); // diurnal semi-arc of the MC degree
+    out[10] = ascOf(armc - (2 * sa) / 3, phi, eps);
+    out[11] = ascOf(armc - sa / 3, phi, eps);
+    out[1] = ascOf(armc + sa / 3, phi, eps);
+    out[2] = ascOf(armc + (2 * sa) / 3, phi, eps);
+    return fillOpposites(out);
+}
+/** Regiomontanus: equal divisions of the celestial equator; cusp poles
+ *  tan P = tan(phi) sin(H). */
+export function housesRegiomontanus(armc, phi, eps) {
+    const out = quadrantFrame(armc, phi, eps, true);
+    for (const [k, h] of [[10, 30], [11, 60], [1, 120], [2, 150]]) {
+        const pole = Math.atan(Math.tan(phi) * Math.sin(h * DEG));
+        out[k] = eastOfMeridian(houseCusp(armc + h * DEG, pole, eps), armc, eps);
+    }
+    return fillOpposites(out);
+}
+/** Campanus: equal divisions of the prime vertical. House circles run
+ *  through the horizon's north/south points; cusps are their ecliptic
+ *  crossings, assigned in zodiacal order MC->ASC->IC. */
+export function housesCampanus(armc, phi, eps) {
+    const out = quadrantFrame(armc, phi, eps, true);
+    const n = [
+        -Math.sin(phi) * Math.cos(armc), -Math.sin(phi) * Math.sin(armc), Math.cos(phi),
+    ];
+    const zen = [
+        Math.cos(phi) * Math.cos(armc), Math.cos(phi) * Math.sin(armc), Math.sin(phi),
+    ];
+    const east = [-Math.sin(armc), Math.cos(armc), 0.0];
+    const pole = [0.0, -Math.sin(eps), Math.cos(eps)];
+    const cusp = (theta) => {
+        const t = theta * DEG;
+        const v = [
+            east[0] * Math.cos(t) + zen[0] * Math.sin(t),
+            east[1] * Math.cos(t) + zen[1] * Math.sin(t),
+            east[2] * Math.cos(t) + zen[2] * Math.sin(t),
+        ];
+        const m = [
+            n[1] * v[2] - n[2] * v[1], n[2] * v[0] - n[0] * v[2], n[0] * v[1] - n[1] * v[0],
+        ];
+        const d = [
+            m[1] * pole[2] - m[2] * pole[1],
+            m[2] * pole[0] - m[0] * pole[2],
+            m[0] * pole[1] - m[1] * pole[0],
+        ];
+        return mod(Math.atan2(d[1] * Math.cos(eps) + d[2] * Math.sin(eps), d[0]), TWO_PI);
+    };
+    for (const [k, theta] of [[10, 30], [11, 60], [1, 120], [2, 150]]) {
+        out[k] = cusp(theta);
+    }
+    const mc = out[9];
+    const asc = out[0];
+    const dUp = signed(asc - mc);
+    const dDn = signed(mod(mc + Math.PI, TWO_PI) - asc);
+    for (const k of [10, 11])
+        out[k] = normArc(out[k], mc, dUp);
+    for (const k of [1, 2])
+        out[k] = normArc(out[k], asc, dDn);
+    // within each quadrant the two cusps must be in house order (away from
+    // MC, away from ASC)
+    if (Math.abs(signed(out[10] - mc)) > Math.abs(signed(out[11] - mc))) {
+        [out[10], out[11]] = [out[11], out[10]];
+    }
+    if (Math.abs(signed(out[1] - asc)) > Math.abs(signed(out[2] - asc))) {
+        [out[1], out[2]] = [out[2], out[1]];
+    }
+    return fillOpposites(out);
+}
+/** Alcabitius: trisect the Ascendant degree's semi-arcs in right ascension;
+ *  project cusps along meridians. */
+export function housesAlcabitius(armc, phi, eps) {
+    const out = quadrantFrame(armc, phi, eps, false);
+    const dec = Math.asin(Math.sin(eps) * Math.sin(out[0]));
+    const x = Math.max(-1.0, Math.min(1.0, Math.tan(phi) * Math.tan(dec)));
+    const ad = Math.asin(x);
+    const sda = Math.PI / 2 + ad; // diurnal semi-arc of the ASC degree
+    const sna = Math.PI / 2 - ad;
+    const ras = [
+        [10, armc + sda / 3], [11, armc + (2 * sda) / 3],
+        [1, armc + Math.PI - (2 * sna) / 3], [2, armc + Math.PI - sna / 3],
+    ];
+    for (const [k, ra] of ras) {
+        out[k] = mod(Math.atan2(Math.sin(ra), Math.cos(ra) * Math.cos(eps)), TWO_PI);
+    }
+    return fillOpposites(out);
+}
+/** Morinus: equal RA divisions projected onto the ecliptic by great circles
+ *  through the ecliptic poles. Latitude-independent. */
+export function housesMorinus(armc, _phi, eps) {
+    return Array.from({ length: 12 }, (_, i) => mod(Math.atan2(Math.sin(armc + (i + 3) * 30 * DEG) * Math.cos(eps), Math.cos(armc + (i + 3) * 30 * DEG)), TWO_PI));
+}
+/** Meridian (axial rotation): equal RA divisions projected along hour
+ *  circles. Latitude-independent. */
+export function housesMeridian(armc, _phi, eps) {
+    return Array.from({ length: 12 }, (_, i) => mod(Math.atan2(Math.sin(armc + (i + 3) * 30 * DEG), Math.cos(armc + (i + 3) * 30 * DEG) * Math.cos(eps)), TWO_PI));
+}
+/** Polich-Page ('topocentric'): cusp poles tan P = (k/3) tan(phi). */
+export function housesPolichPage(armc, phi, eps) {
+    const out = quadrantFrame(armc, phi, eps, true);
+    const spec = [
+        [10, 30, 1], [11, 60, 2], [1, 120, 2], [2, 150, 1],
+    ];
+    for (const [k, h, w] of spec) {
+        const pole = Math.atan((Math.tan(phi) * w) / 3.0);
+        out[k] = eastOfMeridian(houseCusp(armc + h * DEG, pole, eps), armc, eps);
+    }
+    return fillOpposites(out);
+}
+/** Vehlow: equal houses with the ASC at the middle of house 1. */
+export function housesVehlow(armc, phi, eps) {
+    const asc = ascOf(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

package/dist/src/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./core.js";
 export * from "./houses.js";
 export * from "./chart.js";
+export * from "./pheno.js";
+export * from "./events.js";

package/dist/src/index.js

@@ -1,3 +1,5 @@
 export * from "./core.js";
 export * from "./houses.js";
 export * from "./chart.js";
+export * from "./pheno.js";
+export * from "./events.js";

package/dist/src/node-loader.js

@@ -7,8 +7,18 @@ const PLANETS = ["mercury", "venus", "earth", "mars", "jupiter", "saturn",
 export function loadNodeData(dir, level = "embedded", moonTier = "full") {
     const j = (name) => JSON.parse(readFileSync(join(dir, name), "utf8"));
     const vsop = {};
-    for (const p of PLANETS)
-        vsop[p] = j(`vsop87d_${p}.${level}.json`);
+    // The npm package ships the embedded and micro VSOP tiers; full/high live
+    // in the repo. Fall back per planet so "full" against the published
+    // tarball loads instead of throwing ENOENT.
+    for (const p of PLANETS) {
+        const tiers = level === "embedded" || level === "micro" ? [level] : [level, "embedded"];
+        const found = tiers.find((t) => existsSync(join(dir, `vsop87d_${p}.${t}.json`)));
+        if (!found) {
+            throw new Error(`no VSOP87D data for ${p} in ${dir} (tried ${tiers.join(", ")}); `
+                + "the full/high tiers live in the caelus repo, not the npm package");
+        }
+        vsop[p] = j(`vsop87d_${p}.${found}.json`);
+    }
     const data = {
         vsop,
         nutation: j("nutation_iau1980.json"),
@@ -18,6 +28,15 @@ export function loadNodeData(dir, level = "embedded", moonTier = "full") {
     const chironPath = join(dir, "chiron_cheb.json");
     if (existsSync(chironPath))
         data.chiron = j("chiron_cheb.json");
+    if (existsSync(join(dir, "uranian_kepler.json"))) {
+        data.keplerPack = j("uranian_kepler.json");
+    }
+    // asteroid packs (Horizons fits): loaded when present, ~380 KB total
+    for (const b of ["ceres", "pallas", "juno", "vesta", "pholus"]) {
+        if (existsSync(join(dir, `${b}_cheb.json`))) {
+            (data.chebPacks ??= {})[b] = j(`${b}_cheb.json`);
+        }
+    }
     if (moonTier !== "none") {
         // The npm package ships only the embedded tier (1920-2080); the full
         // tier (1850-2150, 3.1 MB, same precision) lives in the repo. Fall back

package/dist/src/pheno.d.ts

@@ -0,0 +1,35 @@
+/**
+ * astroengine pheno -- phase, elongation, apparent diameter, magnitude,
+ * equation of time, horizontal coordinates, refraction.
+ *
+ * Magnitude models: Mallama & Hilton 2018 for Mercury-Saturn (Saturn with
+ * the ring term), constant-plus-distance for Sun and Pluto, the Mallama
+ * secular ramp for Neptune, Allen's phase law for the Moon (valid to phase
+ * angle ~140 deg; the Moon is invisible near conjunction anyway).
+ * Validated against swe_pheno (Swiss Ephemeris 2.10, Moshier mode).
+ */
+import { EngineData } from "./core.js";
+import { Engine, BodyId } from "./chart.js";
+/** Equatorial diameters, km (IAU values, as used by Swiss Ephemeris). */
+export declare const DIAMETER_KM: Record<string, number>;
+export interface Pheno {
+    phaseAngle: number;
+    phase: number;
+    elongation: number;
+    diameter: number;
+    magnitude: number;
+}
+/** Phase angle (deg), illuminated fraction, elongation (deg), apparent
+ *  diameter (deg), apparent magnitude. */
+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;
+/** Apparent ecliptic position -> azimuth (deg, from true north, east-
+ *  positive) and true altitude (deg). No refraction. */
+export declare function azAlt(data: EngineData, lonDeg: number, latDeg: number, jdUt: number, obsLat: number, obsLonEast: number): [number, number];
+/** Saemundsson refraction, degrees. Returns the input unchanged when even
+ *  the refracted altitude stays below the horizon (matches Swiss
+ *  Ephemeris). */
+export declare function refractTrueToApparent(altDeg: number, pressure?: number, tempC?: number): number;
+/** Bennett refraction, degrees. */
+export declare function refractApparentToTrue(altDeg: number, pressure?: number, tempC?: number): number;

package/dist/src/pheno.js

@@ -0,0 +1,152 @@
+/**
+ * astroengine pheno -- phase, elongation, apparent diameter, magnitude,
+ * equation of time, horizontal coordinates, refraction.
+ *
+ * Magnitude models: Mallama & Hilton 2018 for Mercury-Saturn (Saturn with
+ * the ring term), constant-plus-distance for Sun and Pluto, the Mallama
+ * secular ramp for Neptune, Allen's phase law for the Moon (valid to phase
+ * angle ~140 deg; the Moon is invisible near conjunction anyway).
+ * Validated against swe_pheno (Swiss Ephemeris 2.10, Moshier mode).
+ */
+import { DEG, J2000, mod, jdTT, trueObliquity, equatorial, sunApparent, } from "./core.js";
+import { gast } from "./houses.js";
+const TWO_PI = 2 * Math.PI;
+const KM_PER_AU = 149597870.7;
+/** Equatorial diameters, km (IAU values, as used by Swiss Ephemeris). */
+export const DIAMETER_KM = {
+    sun: 1392000.0, moon: 3475.0, mercury: 4878.8, venus: 12103.6,
+    mars: 6779.0, jupiter: 139822.0, saturn: 116464.0,
+    uranus: 50724.0, neptune: 49244.0, pluto: 2376.6,
+};
+function magnitude(body, a, r, dlt, jde, lonDeg, latDeg) {
+    const x = 5 * Math.log10(r * dlt);
+    switch (body) {
+        case "sun":
+            return -26.86 + 5 * Math.log10(dlt);
+        case "moon":
+            // Allen phase law; constant solved against swe_pheno (a < 130).
+            return 0.233431 + x + 0.026 * Math.abs(a) + 4e-9 * a ** 4;
+        case "mercury":
+            return x - 0.613 + 6.328e-2 * a - 1.6336e-3 * a ** 2 + 3.3644e-5 * a ** 3
+                - 3.4265e-7 * a ** 4 + 1.6893e-9 * a ** 5 - 3.0334e-12 * a ** 6;
+        case "venus":
+            if (a <= 163.7) {
+                return x - 4.384 - 1.044e-3 * a + 3.687e-4 * a ** 2
+                    - 2.814e-6 * a ** 3 + 8.938e-9 * a ** 4;
+            }
+            return x + 236.05828 - 2.81914 * a + 8.39034e-3 * a ** 2;
+        case "mars":
+            return x - 1.601 + 2.267e-2 * a - 1.302e-4 * a ** 2;
+        case "jupiter":
+            return x - 9.395 - 3.7e-4 * a + 6.16e-4 * a ** 2;
+        case "saturn": {
+            // ring inclination (Meeus ch. 45)
+            const T = (jde - J2000) / 36525.0;
+            const i = (28.075216 - 0.012998 * T + 0.000004 * T * T) * DEG;
+            const om = (169.50847 + 1.394681 * T + 0.000412 * T * T) * DEG;
+            const lam = lonDeg * DEG;
+            const bet = latDeg * DEG;
+            const sinB = Math.sin(i) * Math.cos(bet) * Math.sin(lam - om)
+                - Math.cos(i) * Math.sin(bet);
+            const b = Math.abs(Math.asin(Math.max(-1.0, Math.min(1.0, sinB))));
+            return x - 8.914 - 1.825 * Math.sin(b) + 0.026 * a
+                - 0.378 * Math.sin(b) * Math.exp(-2.25 * a);
+        }
+        case "uranus":
+            // constant absorbs Mallama's sub-solar-latitude term
+            return x - 7.16 + 6.587e-3 * a + 1.045e-4 * a ** 2;
+        case "neptune": {
+            const y = 2000.0 + (jde - J2000) / 365.25;
+            const base = y < 1980.0 ? -6.89
+                : y < 2000.0 ? -6.89 - (0.11 * (y - 1980.0)) / 20.0
+                    : -7.0;
+            return x + base + 7.944e-3 * a + 9.617e-5 * a ** 2;
+        }
+        default: // pluto
+            return x - 1.01;
+    }
+}
+/** Phase angle (deg), illuminated fraction, elongation (deg), apparent
+ *  diameter (deg), apparent magnitude. */
+export function pheno(engine, body, jdUt) {
+    if (DIAMETER_KM[body] === undefined) {
+        throw new Error(`pheno not available for '${body}'`);
+    }
+    const jde = jdTT(jdUt);
+    const p = engine.position(body, jdUt);
+    const s = body === "sun" ? p : engine.position("sun", jdUt);
+    const dlt = p.dist;
+    const a1 = p.lon * DEG;
+    const d1 = p.lat * DEG;
+    const a2 = s.lon * DEG;
+    const d2 = s.lat * DEG;
+    const elong = Math.acos(Math.max(-1.0, Math.min(1.0, Math.sin(d1) * Math.sin(d2) + Math.cos(d1) * Math.cos(d2) * Math.cos(a1 - a2))));
+    let phaseAngle;
+    let r;
+    if (body === "sun") {
+        phaseAngle = 0.0;
+        r = dlt;
+    }
+    else if (body === "moon") {
+        r = s.dist; // sun-earth distance stands in for sun-moon
+        const R = s.dist;
+        phaseAngle = Math.atan2(R * Math.sin(elong), dlt - R * Math.cos(elong));
+    }
+    else {
+        r = engine.heliocentric(body, jdUt).dist;
+        const cosi = (r * r + dlt * dlt - s.dist ** 2) / (2 * r * dlt);
+        phaseAngle = Math.acos(Math.max(-1.0, Math.min(1.0, cosi)));
+    }
+    const aDeg = phaseAngle / DEG;
+    const diam = (2 * Math.asin(DIAMETER_KM[body] / (2 * dlt * KM_PER_AU))) / DEG;
+    return {
+        phaseAngle: aDeg,
+        phase: (1 + Math.cos(phaseAngle)) / 2,
+        elongation: elong / DEG,
+        diameter: diam,
+        magnitude: magnitude(body, aDeg, r, dlt, jde, p.lon, p.lat),
+    };
+}
+/** Apparent minus mean solar time, minutes (Meeus ch. 28). */
+export function equationOfTime(engine, jdUt) {
+    const jde = jdTT(jdUt);
+    const t = (jde - J2000) / 365250.0;
+    const l0 = mod(280.4664567 + 360007.6982779 * t + 0.03032028 * t * t
+        + t ** 3 / 49931 - t ** 4 / 15300 - t ** 5 / 2000000, 360);
+    const [lon, lat] = sunApparent(engine.data, jde);
+    const [ra] = equatorial(lon, lat, trueObliquity(engine.data, jde));
+    const e = mod(l0 - 0.0057183 - ra / DEG + 180, 360) - 180;
+    return e * 4.0; // degrees -> minutes
+}
+/** Apparent ecliptic position -> azimuth (deg, from true north, east-
+ *  positive) and true altitude (deg). No refraction. */
+export function azAlt(data, lonDeg, latDeg, jdUt, obsLat, obsLonEast) {
+    const jde = jdTT(jdUt);
+    const eps = trueObliquity(data, jde);
+    const [ra, dec] = equatorial(lonDeg * DEG, latDeg * DEG, eps);
+    const lst = mod(gast(data, jdUt) + obsLonEast * DEG, TWO_PI);
+    const ha = lst - ra;
+    const phi = obsLat * DEG;
+    const alt = Math.asin(Math.sin(phi) * Math.sin(dec) + Math.cos(phi) * Math.cos(dec) * Math.cos(ha));
+    const azS = Math.atan2(Math.sin(ha), Math.cos(ha) * Math.sin(phi) - Math.tan(dec) * Math.cos(phi));
+    return [mod(azS / DEG + 180.0, 360.0), alt / DEG];
+}
+/** Saemundsson refraction, degrees. Returns the input unchanged when even
+ *  the refracted altitude stays below the horizon (matches Swiss
+ *  Ephemeris). */
+export function refractTrueToApparent(altDeg, pressure = 1013.25, tempC = 15.0) {
+    if (altDeg < -2.0)
+        return altDeg;
+    let r = 1.02 / Math.tan((altDeg + 10.3 / (altDeg + 5.11)) * DEG);
+    r *= (pressure / 1010.0) * (283.0 / (273.0 + tempC));
+    const out = altDeg + r / 60.0;
+    return out < 0.0 ? altDeg : out;
+}
+/** Bennett refraction, degrees. */
+export function refractApparentToTrue(altDeg, pressure = 1013.25, tempC = 15.0) {
+    if (altDeg < -2.0)
+        return altDeg;
+    let r = 1.0 / Math.tan((altDeg + 7.31 / (altDeg + 4.4)) * DEG);
+    r *= (pressure / 1010.0) * (283.0 / (273.0 + tempC));
+    return altDeg - r / 60.0;
+}

package/package.json

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