caelus 0.3.0 → 0.5.0

package/README.md

@@ -6,10 +6,11 @@ ephemeris files. 1:1 port of the Python reference, checked by golden fixtures.
 ## Verification chain
 
 1. Python engine checked against Swiss Ephemeris 2.10 across 1900–2099:
-   every planet ≤ 1″ (Sun–Saturn), Moon ≤ 2.5″, Chiron ≤ 1″, nodes ≤ 1″
+   every planet ≤ 1″ (Sun–Saturn), Moon ≤ 2.5″, Chiron ≤ 1″, mean node ≤ 1″,
+   true node ≤ 1′ vs SE's built-in ephemeris (≤ 1″ vs JPL DE431)
    (vs full DE431 files, 1850–2149), angles and Placidus cusps ≤ 3.2″ — all
    invisible at the arcminute display precision chart software uses.
-2. TypeScript port verified against Python golden fixtures: **3,087 checks,
+2. TypeScript port verified against Python golden fixtures: **3,218 checks,
    0 failures, worst deviation 1.64 nano-arcseconds.** The two implementations
    are numerically identical.
 
@@ -62,8 +63,15 @@ engine.longitude("chiron", 2451545.0);
 engine.position("mars", 2451545.0); // { lon, speed, retrograde, sign, signDeg }
 ```
 
-Bodies: sun, moon, mercury…pluto, chiron, mean_node, true_node.
-House systems: placidus, porphyry, equal, whole_sign.
+Bodies: sun, moon, mercury…pluto, chiron, mean_node, true_node; on request:
+mean_lilith, true_lilith, ceres, pallas, juno, vesta, pholus, and the eight
+Hamburg-school Uranian bodies (cupido…poseidon) when their data packs are
+loaded.
+House systems: placidus, porphyry, equal, whole_sign, koch, regiomontanus,
+campanus, alcabitius, morinus, meridian, polich_page, vehlow (Placidus and
+Koch fall back to whole_sign above the polar circles).
+Event search: rise/set/meridian transits, zodiac crossings, lunar phases,
+stations (`events.ts`).
 Performance: ~2.4 ms per full chart (13 bodies × 3 evaluations + houses +
 aspects) single-threaded in Node 22 — ~420 charts/sec, faster in hot loops.
 
@@ -92,4 +100,4 @@ test/golden.test.ts  conformance suite vs Python fixtures
 - caelus — this package
 - [caelus-birth](https://www.npmjs.com/package/caelus-birth) — local birth time + place → UT (charts take UT; use this)
 - [caelus-wheel](https://www.npmjs.com/package/caelus-wheel) — React SVG chart wheel
-- [caelus-mcp](https://www.npmjs.com/package/caelus-mcp) — MCP server, six chart tools over stdio
+- [caelus-mcp](https://www.npmjs.com/package/caelus-mcp) — MCP server, seven chart tools over stdio

package/accuracy.json

@@ -3,41 +3,271 @@
   "range": "1900-2099",
   "unit": "arcsec",
   "bodies": [
-    { "name": "Sun", "max": "0.4", "rms": "0.2", "note": "" },
-    { "name": "Moon (precise tier)", "max": "2.5", "rms": "0.9", "note": "JPL DE423 fit (2010); DE423 vs DE440 is <0.1″ over this span" },
-    { "name": "Moon (embedded series)", "max": "9.6", "rms": "2.8", "note": "60-term ELP abridged" },
-    { "name": "Mercury", "max": "0.5", "rms": "0.2", "note": "" },
-    { "name": "Venus", "max": "0.8", "rms": "0.2", "note": "" },
-    { "name": "Mars", "max": "0.7", "rms": "0.2", "note": "" },
-    { "name": "Jupiter", "max": "0.9", "rms": "0.3", "note": "" },
-    { "name": "Saturn", "max": "0.8", "rms": "0.4", "note": "" },
-    { "name": "Uranus", "max": "1.9", "rms": "0.7", "note": "series truncation; complete VSOP87 holds ≤1″" },
-    { "name": "Neptune", "max": "4.6", "rms": "2.2", "note": "series truncation; complete VSOP87 holds ≤1″" },
-    { "name": "Pluto", "max": "2.5", "rms": "1.0", "note": "series valid 1885-2099" },
-    { "name": "Chiron", "max": "1.0", "rms": "0.3", "note": "JPL Horizons fit, 1850-2150" },
-    { "name": "Mean node", "max": "0.1", "rms": "0.1", "note": "" },
-    { "name": "True node", "max": "0.8", "rms": "0.4", "note": "vs full DE431 files; Swiss’s built-in Moshier mode itself differs from DE431 by up to ~15″ here" },
-    { "name": "Ascendant / MC", "max": "3.2", "rms": "—", "note": "" },
-    { "name": "Placidus cusps (all 12)", "max": "3.2", "rms": "—", "note": "" },
-    { "name": "Mean Lilith", "max": "1.3", "rms": "0.5", "note": "mean lunar apogee on the inclined orbit; latitude ≤0.1″" },
-    { "name": "Sidereal longitudes", "max": "0.1", "rms": "—", "note": "ayanamsa model vs SE ≤0.30″ at the 1900/2099 edges (IAU 1976 vs Vondrák precession); Sun worst-case 0.08″ at 120 sampled epochs" },
-    { "name": "RA / Dec", "max": "2.1", "rms": "—", "note": "rotation is exact; bound tracks each body's ecliptic accuracy (Moon worst)" },
-    { "name": "Topocentric Moon", "max": "2.7", "rms": "—", "note": "parallax model adds ≤0.1″ over the geocentric bound" },
-    { "name": "House cusps, 8 new systems", "max": "0.0", "rms": "0.0", "note": "Koch, Regiomontanus, Campanus, Alcabitius, Morinus, Meridian, Polich-Page, Vehlow: exact vs swe_houses_armc (200 polar-inclusive cases each)" },
-    { "name": "Vertex / east point", "max": "0.0", "rms": "0.0", "note": "exact vs swe_houses_armc" },
-    { "name": "Magnitudes", "max": "0.045 mag", "rms": "—", "note": "Mallama 2018; Moon (Allen law) valid to phase angle 140°" }
+    {
+      "name": "Sun",
+      "max": "0.4",
+      "rms": "0.2",
+      "note": ""
+    },
+    {
+      "name": "Moon (precise tier)",
+      "max": "2.5",
+      "rms": "0.9",
+      "note": "JPL DE423 fit (2010); DE423 vs DE440 is <0.1″ over this span"
+    },
+    {
+      "name": "Moon (embedded series)",
+      "max": "9.6",
+      "rms": "2.8",
+      "note": "60-term ELP abridged"
+    },
+    {
+      "name": "Mercury",
+      "max": "0.5",
+      "rms": "0.2",
+      "note": ""
+    },
+    {
+      "name": "Venus",
+      "max": "0.8",
+      "rms": "0.2",
+      "note": ""
+    },
+    {
+      "name": "Mars",
+      "max": "0.7",
+      "rms": "0.2",
+      "note": ""
+    },
+    {
+      "name": "Jupiter",
+      "max": "0.9",
+      "rms": "0.3",
+      "note": ""
+    },
+    {
+      "name": "Saturn",
+      "max": "0.8",
+      "rms": "0.4",
+      "note": ""
+    },
+    {
+      "name": "Uranus",
+      "max": "1.9",
+      "rms": "0.7",
+      "note": "series truncation; complete VSOP87 holds ≤1″"
+    },
+    {
+      "name": "Neptune",
+      "max": "4.6",
+      "rms": "2.2",
+      "note": "series truncation; complete VSOP87 holds ≤1″"
+    },
+    {
+      "name": "Pluto",
+      "max": "2.5",
+      "rms": "1.0",
+      "note": "series valid 1885-2099"
+    },
+    {
+      "name": "Chiron",
+      "max": "1.0",
+      "rms": "0.3",
+      "note": "JPL Horizons fit, 1850-2150"
+    },
+    {
+      "name": "Mean node",
+      "max": "0.1",
+      "rms": "0.1",
+      "note": ""
+    },
+    {
+      "name": "True node",
+      "max": "0.8",
+      "rms": "0.4",
+      "note": "vs full JPL DE431 files; vs Swiss Ephemeris's BUILT-IN (Moshier) ephemeris expect up to ~1′ (measured: 50″ max, 8″ median, 300 epochs) — that is the built-in lunar theory's own node error, not ours"
+    },
+    {
+      "name": "Ascendant / MC",
+      "max": "3.2",
+      "rms": "—",
+      "note": ""
+    },
+    {
+      "name": "Placidus cusps (all 12)",
+      "max": "3.2",
+      "rms": "—",
+      "note": ""
+    },
+    {
+      "name": "Mean Lilith",
+      "max": "1.3",
+      "rms": "0.5",
+      "note": "mean lunar apogee on the inclined orbit; latitude ≤0.1″"
+    },
+    {
+      "name": "Sidereal longitudes",
+      "max": "0.1",
+      "rms": "—",
+      "note": "ayanamsa model vs SE ≤0.30″ at the 1900/2099 edges (IAU 1976 vs Vondrák precession); Sun worst-case 0.08″ at 120 sampled epochs"
+    },
+    {
+      "name": "RA / Dec",
+      "max": "2.1",
+      "rms": "—",
+      "note": "rotation is exact; bound tracks each body's ecliptic accuracy (Moon worst)"
+    },
+    {
+      "name": "Topocentric Moon",
+      "max": "2.7",
+      "rms": "—",
+      "note": "parallax model adds ≤0.1″ over the geocentric bound"
+    },
+    {
+      "name": "House cusps, 8 new systems",
+      "max": "0.0",
+      "rms": "0.0",
+      "note": "Koch, Regiomontanus, Campanus, Alcabitius, Morinus, Meridian, Polich-Page, Vehlow: exact vs swe_houses_armc (200 polar-inclusive cases each)"
+    },
+    {
+      "name": "Vertex / east point",
+      "max": "0.0",
+      "rms": "0.0",
+      "note": "exact vs swe_houses_armc"
+    },
+    {
+      "name": "Magnitudes",
+      "max": "0.045 mag",
+      "rms": "—",
+      "note": "Mallama 2018; Moon (Allen law) valid to phase angle 140°"
+    },
+    {
+      "name": "Rise/set/meridian transit",
+      "max": "0.5 s",
+      "rms": "—",
+      "note": "vs swe_rise_trans, 48 polar-inclusive cases per body; Moon bound tracks its position accuracy"
+    },
+    {
+      "name": "Crossings / lunar phases",
+      "max": "4 s",
+      "rms": "—",
+      "note": "vs swe_solcross/swe_mooncross and elongation root-finds"
+    },
+    {
+      "name": "Stations",
+      "max": "55 s",
+      "rms": "—",
+      "note": "ill-conditioned by nature: speed-zero slope ~0.01°/day² turns sub-arcsecond model differences into minutes"
+    },
+    {
+      "name": "True Lilith (osc. apogee)",
+      "max": "187",
+      "rms": "—",
+      "note": "hypersensitive to the lunar theory (~1/e amplification); SE's own Moshier-vs-DE difference dominates. 'True Lilith' values disagree across software at this scale"
+    },
+    {
+      "name": "Ceres, Pallas, Juno, Vesta, Pholus",
+      "max": "1.0",
+      "rms": "0.3",
+      "note": "JPL Horizons fits 1850-2150 (residual <5e-6 AU); same geocentric pipeline as Chiron. No independent SE oracle here: SE's asteroid files are unavailable in Moshier mode"
+    },
+    {
+      "name": "Uranian bodies (Cupido…Poseidon)",
+      "max": "2.3",
+      "rms": "—",
+      "note": "Hamburg-school constant-element Kepler orbits, elements fitted to SE 2.10's built-in definitions (fit_uranian.py prints per-body figures; Zeus is fit-noise-limited at ~3″ heliocentric). Uranian practice works in arcminutes"
+    },
+    {
+      "name": "Fixed stars (318-star catalog)",
+      "max": "0.6",
+      "rms": "—",
+      "note": "HYG-derived catalog (ICRS J2000 + proper motions, full 3D space motion); vs swe_fixstar fed the same rows. Floor is the IAU 1976 vs Vondrák precession difference"
+    },
+    {
+      "name": "Star-anchored ayanamsas",
+      "max": "0.2",
+      "rms": "—",
+      "note": "galcent_0sag and true_citra computed from the apparent star (Galactic Center / Spica); sidereal Sun vs SE ≤0.19″"
+    },
+    {
+      "name": "Gauquelin sectors",
+      "max": "0.0001 sectors",
+      "rms": "—",
+      "note": "rise/set of disc center with refraction (SE method 3): exact to the rise/set bound"
+    },
+    {
+      "name": "Eclipses (solar + lunar)",
+      "max": "9 s",
+      "rms": "—",
+      "note": "times of maximum vs swe; types exact over 1990-2030 (92 lunar + 89 solar, zero mismatches); lunar magnitudes ≤0.0013 (Danjon parallax enlargement, recovered empirically). Contact times typically ≤15 s, minutes for grazing geometries. Global circumstances only — no ground paths"
+    }
   ],
   "summary": [
-    { "label": "Sun–Saturn", "bound": "≤ 1″" },
-    { "label": "Uranus / Neptune", "bound": "≤ 1.9″ / ≤ 4.6″" },
-    { "label": "Moon (1920–2080 tier)", "bound": "≤ 2.5″" },
-    { "label": "Moon (series, embedded)", "bound": "≤ 10″" },
-    { "label": "Pluto / Chiron", "bound": "≤ 2.5″ / ≤ 1″" },
-    { "label": "Angles & Placidus cusps", "bound": "≤ 3.2″" },
-    { "label": "True node", "bound": "≤ 1″" },
-    { "label": "Mean Lilith", "bound": "≤ 1.3″" },
-    { "label": "Sidereal (5 ayanamsas)", "bound": "≤ 0.3″ added" },
-    { "label": "8 new house systems", "bound": "exact (0.0″)" }
+    {
+      "label": "Sun–Saturn",
+      "bound": "≤ 1″"
+    },
+    {
+      "label": "Uranus / Neptune",
+      "bound": "≤ 1.9″ / ≤ 4.6″"
+    },
+    {
+      "label": "Moon (1920–2080 tier)",
+      "bound": "≤ 2.5″"
+    },
+    {
+      "label": "Moon (series, embedded)",
+      "bound": "≤ 10″"
+    },
+    {
+      "label": "Pluto / Chiron",
+      "bound": "≤ 2.5″ / ≤ 1″"
+    },
+    {
+      "label": "Angles & Placidus cusps",
+      "bound": "≤ 3.2″"
+    },
+    {
+      "label": "True node",
+      "bound": "≤ 1′ vs SE built-in (≤ 1″ vs JPL DE431)"
+    },
+    {
+      "label": "Mean Lilith",
+      "bound": "≤ 1.3″"
+    },
+    {
+      "label": "8 new house systems",
+      "bound": "exact (0.0″)"
+    },
+    {
+      "label": "Rise/set/transit",
+      "bound": "≤ 0.5 s"
+    },
+    {
+      "label": "Crossings & phases",
+      "bound": "≤ 4 s"
+    },
+    {
+      "label": "Asteroids (big 4 + Pholus)",
+      "bound": "≤ 1″"
+    },
+    {
+      "label": "Uranian bodies",
+      "bound": "≤ 2.3″"
+    },
+    {
+      "label": "Fixed stars",
+      "bound": "≤ 0.6″"
+    },
+    {
+      "label": "Sidereal (7 ayanamsas)",
+      "bound": "≤ 0.3″ added"
+    },
+    {
+      "label": "Eclipses",
+      "bound": "types exact; max ≤ 9 s"
+    }
   ],
-  "v03_harness": "python/validate_swiss.py regenerates every figure above the line against pyswisseph 2.10 (Moshier mode)"
-}
+  "v03_harness": "python/validate_swiss.py regenerates every figure above the line against pyswisseph 2.10 (Moshier mode)",
+  "true_node_vs_builtin": "1′"
+}

package/dist/src/chart.d.ts

@@ -3,7 +3,7 @@ import { EngineData, AYANAMSA_J2000 } from "./core.js";
 export declare const BODIES: readonly ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn", "uranus", "neptune", "pluto", "chiron", "mean_node", "true_node"];
 export type Body = (typeof BODIES)[number];
 /** Computable on request (not in the default chart set). */
-export declare const EXTRA_BODIES: readonly ["mean_lilith"];
+export declare const EXTRA_BODIES: readonly ["mean_lilith", "true_lilith"];
 /** Core names keep autocomplete; any string id is accepted (data packs). */
 export type BodyId = Body | (typeof EXTRA_BODIES)[number] | (string & {});
 export declare const SIGNS: string[];
@@ -68,12 +68,30 @@ export declare class Engine {
     readonly data: EngineData;
     private moonCheb;
     private chironCheb;
+    private packs;
     constructor(data: EngineData);
+    private pack;
     private moonInRange;
     /** Body ids this engine can compute, given the data it was handed. */
     bodies(): BodyId[];
-    /** Apparent geocentric [lon rad, lat rad, dist AU | null]. */
-    private ecliptic;
+    /** 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: BodyId, jde: number): [number, number, number | null];
+    /** Degrees to subtract from a true-equinox tropical longitude. */
+    private ayanShift;
+    /** Apparent place of a catalog star: lon/lat/ra/dec (deg), sign, mag. */
+    fixedStar(name: string, jdUt: number, opts?: CalcOptions): {
+        lon: number;
+        lat: number;
+        ra: number;
+        dec: number;
+        mag: number;
+        sign: string;
+        signDeg: number;
+    };
+    /** Names in the loaded fixed-star catalog (sorted). */
+    starNames(): string[];
     private lonOnly;
     /** Apparent geocentric ecliptic longitude (deg). Tropical: true equinox
      *  of date. Sidereal: mean equinox minus ayanamsa. */

package/dist/src/chart.js

@@ -1,5 +1,6 @@
 /** astroengine chart -- public API: natal charts, aspects, retrogrades. */
-import { DEG, mod, jdTT, julianDay, ChebSeries, planetApparent, sunApparent, moonApparentSeries, moonApparentPrecise, plutoApparent, chironApparent, meanNode, trueNodeSeries, trueNodePrecise, equatorial, ayanamsa, AYANAMSA_J2000, meanLilith, topocentricEcl, trueObliquity, nutation, plutoHeliocentric, vsopHeliocentric, precessEcliptic, J2000, } 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 { starApparent } from "./stars.js";
 import * as H from "./houses.js";
 const TWO_PI = 2 * Math.PI;
 export const BODIES = [
@@ -7,9 +8,11 @@ export const BODIES = [
     "uranus", "neptune", "pluto", "chiron", "mean_node", "true_node",
 ];
 /** Computable on request (not in the default chart set). */
-export const EXTRA_BODIES = ["mean_lilith"];
+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"]);
+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",
@@ -26,11 +29,18 @@ function parseZodiac(zodiac) {
         return null;
     if (zodiac.startsWith("sidereal:")) {
         const mode = zodiac.slice("sidereal:".length);
-        if (AYANAMSA_J2000[mode] !== undefined)
+        if (AYANAMSA_J2000[mode] !== undefined || STAR_AYANAMSAS[mode])
             return mode;
     }
     throw new Error(`unknown zodiac ${JSON.stringify(zodiac)}`);
 }
+/** Star-anchored ayanamsas: the named star sits at the fixed sidereal
+ *  longitude by definition (Galactic Center at 0 Sagittarius; Spica at
+ *  0 Libra "citra"). Need the fixed-star catalog loaded. */
+const STAR_AYANAMSAS = {
+    galcent_0sag: ["Galactic Center", 240.0],
+    true_citra: ["Spica", 180.0],
+};
 const VSOP_BODIES = new Set([
     "mercury", "venus", "earth", "mars", "jupiter", "saturn", "uranus", "neptune",
 ]);
@@ -38,20 +48,42 @@ 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;
     }
     /** Body ids this engine can compute, given the data it was handed. */
     bodies() {
-        return [...BODIES, ...EXTRA_BODIES].filter((b) => b !== "chiron" || this.chironCheb);
+        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]. */
+    /** 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);
@@ -82,10 +114,53 @@ export class Engine {
             const [lon, lat] = meanLilith(this.data, jde);
             return [lon, lat, null];
         }
+        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}'`);
     }
+    /** Degrees to subtract from a true-equinox tropical longitude. */
+    ayanShift(jde, mode) {
+        const star = STAR_AYANAMSAS[mode];
+        if (star) {
+            const s = this.data.fixedStars?.stars[star[0]];
+            if (!s)
+                throw new Error(`zodiac 'sidereal:${mode}' needs the fixed-star catalog loaded`);
+            const [lon] = starApparent(this.data, s, jde);
+            return mod(lon / DEG - star[1], 360);
+        }
+        return mod(nutation(this.data, jde)[0] / DEG + ayanamsa(jde, mode), 360);
+    }
+    /** Apparent place of a catalog star: lon/lat/ra/dec (deg), sign, mag. */
+    fixedStar(name, jdUt, opts = {}) {
+        const s = this.data.fixedStars?.stars[name];
+        if (!s)
+            throw new Error(`no fixed-star catalog entry for '${name}'`);
+        const mode = parseZodiac(opts.zodiac ?? "tropical");
+        const jde = jdTT(jdUt);
+        const [lonR, latR] = starApparent(this.data, s, jde);
+        const [ra, dec] = equatorial(lonR, latR, trueObliquity(this.data, jde));
+        let lon = lonR / DEG;
+        if (mode !== null)
+            lon = mod(lon - this.ayanShift(jde, mode), 360);
+        return {
+            lon, lat: latR / DEG, ra: ra / DEG, dec: dec / DEG, mag: s.mag,
+            sign: SIGNS[Math.floor(lon / 30)], signDeg: mod(lon, 30),
+        };
+    }
+    /** Names in the loaded fixed-star catalog (sorted). */
+    starNames() {
+        return Object.keys(this.data.fixedStars?.stars ?? {}).sort();
+    }
     lonOnly(body, jdUt, mode, topo) {
         const jde = jdTT(jdUt);
         let [lon, lat, dist] = this.ecliptic(body, jde);
@@ -94,9 +169,8 @@ export class Engine {
             [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);
-        }
+        if (mode !== null)
+            lonDeg = mod(lonDeg - this.ayanShift(jde, mode), 360);
         return lonDeg;
     }
     /** Apparent geocentric ecliptic longitude (deg). Tropical: true equinox
@@ -125,6 +199,13 @@ export class Engine {
             b = Math.atan2(z, Math.hypot(x, y));
             [l, b] = precessEcliptic(l, b, J2000, 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 (VSOP_BODIES.has(body) && this.data.vsop[body]) {
             [l, b, r] = vsopHeliocentric(this.data.vsop[body], jde);
         }
@@ -145,9 +226,8 @@ export class Engine {
         }
         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);
-        }
+        if (mode !== null)
+            lon = mod(lon - this.ayanShift(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);
@@ -235,9 +315,8 @@ export class Engine {
         }
         const jde = jdTT(jdUt);
         let shift = 0.0;
-        if (mode !== null) {
-            shift = nutation(this.data, jde)[0] / DEG + ayanamsa(jde, mode);
-        }
+        if (mode !== null)
+            shift = this.ayanShift(jde, mode);
         const outDeg = (rad) => mod(rad / DEG - shift, 360);
         let cuspsDeg;
         if (mode !== null && used === "whole_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,13 @@ 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;
+    /** Fixed-star catalog (HYG-derived; ICRS J2000 + proper motions). */
+    fixedStars?: import("./stars.js").StarPack;
 }
 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,
@@ -82,6 +107,19 @@ 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]. */
@@ -89,4 +127,4 @@ export declare function topocentricEcl(lon: number, lat: number, distAu: 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

@@ -420,6 +420,84 @@ export function meanLilith(data, jde) {
     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 [
+            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).

package/dist/src/eclipses.d.ts

@@ -0,0 +1,24 @@
+import { Engine } from "./chart.js";
+export interface LunarEclipse {
+    tMax: number;
+    type: "total" | "partial" | "penumbral";
+    magUmbral: number;
+    magPenumbral: number;
+    penumbralBegin: number | null;
+    penumbralEnd: number | null;
+    partialBegin: number | null;
+    partialEnd: number | null;
+    totalBegin: number | null;
+    totalEnd: number | null;
+}
+export interface SolarEclipse {
+    tMax: number;
+    type: "total" | "annular" | "hybrid" | "partial";
+    gamma: number;
+    begin: number;
+    end: number;
+}
+/** Lunar eclipses in [jdStart, jdEnd] (UT JDs). */
+export declare function lunarEclipses(engine: Engine, jdStart: number, jdEnd: number): LunarEclipse[];
+/** Solar eclipses (global circumstances) in [jdStart, jdEnd] (UT JDs). */
+export declare function solarEclipses(engine: Engine, jdStart: number, jdEnd: number): SolarEclipse[];

package/dist/src/eclipses.js

@@ -0,0 +1,163 @@
+/**
+ * astroengine eclipses -- solar and lunar eclipse search.
+ *
+ * Lunar: direct shadow geometry at the anti-solar point with Danjon's
+ * enlargement (lunar parallax x 86/85 on the flattened Earth) — the rule
+ * Swiss Ephemeris uses, recovered empirically: magnitudes match to 0.001,
+ * types exactly; times of maximum to ~9 s (contact times typically <=15 s,
+ * up to ~2 min for grazing geometries where the crossing flattens).
+ *
+ * Solar (global): shadow-axis geometry. gamma = closest approach of the
+ * Sun-Moon axis to the geocenter in Earth radii; the umbral cone's reach
+ * at the surface separates total from annular, a sign change along the
+ * track marks hybrids. Types match Swiss Ephemeris exactly over decades.
+ * Local circumstances (where/visibility) are not computed here.
+ */
+import { ARCSEC, jdTT, mod } from "./core.js";
+const KM_PER_AU = 149597870.7;
+const R_EARTH = 6378.14;
+const R_SUN = 696000.0;
+const R_MOON = 1737.4;
+const PI_SUN = 8.794 * ARCSEC;
+const DANJON = (1 + 1 / 85.0) * 0.99834;
+function lunarGeom(engine, jd) {
+    const jde = jdTT(jd);
+    const [slon, slat, sdist] = engine.ecliptic("sun", jde);
+    const [mlon, mlat, mdist] = engine.ecliptic("moon", jde);
+    const alon = mod(slon + Math.PI, 2 * Math.PI);
+    const alat = -slat;
+    const cosd = Math.sin(alat) * Math.sin(mlat)
+        + Math.cos(alat) * Math.cos(mlat) * Math.cos(alon - mlon);
+    const theta = Math.acos(Math.max(-1, Math.min(1, cosd)));
+    const mkm = mdist * KM_PER_AU;
+    const piEff = DANJON * Math.asin(R_EARTH / mkm);
+    const sM = Math.asin(R_MOON / mkm);
+    const sS = Math.asin(R_SUN / (sdist * KM_PER_AU));
+    return [theta, piEff - sS + PI_SUN, piEff + sS + PI_SUN, sM];
+}
+function solarGeom(engine, jd) {
+    const jde = jdTT(jd);
+    const [slon, slat, sdist] = engine.ecliptic("sun", jde);
+    const [mlon, mlat, mdist] = engine.ecliptic("moon", jde);
+    const vec = (lon, lat, r) => [
+        r * Math.cos(lat) * Math.cos(lon),
+        r * Math.cos(lat) * Math.sin(lon),
+        r * Math.sin(lat),
+    ];
+    const S = vec(slon, slat, sdist * KM_PER_AU);
+    const M = vec(mlon, mlat, mdist * KM_PER_AU);
+    const SM = [M[0] - S[0], M[1] - S[1], M[2] - S[2]];
+    const smn = Math.sqrt(SM[0] ** 2 + SM[1] ** 2 + SM[2] ** 2);
+    const d = SM.map((c) => c / smn);
+    const t0 = -(M[0] * d[0] + M[1] * d[1] + M[2] * d[2]);
+    const P = [M[0] + t0 * d[0], M[1] + t0 * d[1], M[2] + t0 * d[2]];
+    const dAxis = Math.sqrt(P[0] ** 2 + P[1] ** 2 + P[2] ** 2);
+    const f1 = Math.asin((R_SUN + R_MOON) / smn);
+    const f2 = Math.asin((R_SUN - R_MOON) / smn);
+    const rPen = (R_MOON / Math.tan(f1) + t0) * Math.tan(f1);
+    const rUmb = (R_MOON / Math.tan(f2) - t0) * Math.tan(f2);
+    return [dAxis, rPen, rUmb, t0, f2];
+}
+function minimize(f, lo, hi) {
+    for (let i = 0; i < 60; i++) {
+        const m1 = lo + (hi - lo) / 3;
+        const m2 = hi - (hi - lo) / 3;
+        if (f(m1) < f(m2))
+            hi = m2;
+        else
+            lo = m1;
+    }
+    return (lo + hi) / 2;
+}
+function bisect(f, a, b) {
+    let fa = f(a);
+    for (let i = 0; i < 50; i++) {
+        const m = (a + b) / 2;
+        if (fa * f(m) <= 0) {
+            b = m;
+        }
+        else {
+            a = m;
+            fa = f(a);
+        }
+    }
+    return (a + b) / 2;
+}
+function syzygies(engine, jdStart, jdEnd, angle) {
+    const f = (t) => {
+        const e = mod(engine.longitude("moon", t) - engine.longitude("sun", t), 360);
+        return mod(e - angle + 180, 360) - 180;
+    };
+    const out = [];
+    const step = 5.0;
+    let prev = f(jdStart);
+    for (let t = jdStart + step; t <= jdEnd + step; 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;
+}
+/** Lunar eclipses in [jdStart, jdEnd] (UT JDs). */
+export function lunarEclipses(engine, jdStart, jdEnd) {
+    const out = [];
+    for (const tFull of syzygies(engine, jdStart - 1, jdEnd + 1, 180.0)) {
+        const tMax = minimize((t) => lunarGeom(engine, t)[0], tFull - 0.3, tFull + 0.3);
+        const [theta, u, pen, sM] = lunarGeom(engine, tMax);
+        const magU = (u + sM - theta) / (2 * sM);
+        const magP = (pen + sM - theta) / (2 * sM);
+        if (magP <= 0 || tMax < jdStart || tMax > jdEnd)
+            continue;
+        const kind = magU >= 1 ? "total" : magU > 0 ? "partial" : "penumbral";
+        const cross = (idx, sign) => {
+            const f = (t) => {
+                const g = lunarGeom(engine, t);
+                return g[0] - (g[idx] + sign * g[3]);
+            };
+            return [bisect(f, tMax - 0.35, tMax), bisect(f, tMax, tMax + 0.35)];
+        };
+        const [penB, penE] = cross(2, 1);
+        const [parB, parE] = magU > 0 ? cross(1, 1) : [null, null];
+        const [totB, totE] = magU >= 1 ? cross(1, -1) : [null, null];
+        out.push({
+            tMax, type: kind,
+            magUmbral: Math.max(magU, 0), magPenumbral: magP,
+            penumbralBegin: penB, penumbralEnd: penE,
+            partialBegin: parB, partialEnd: parE,
+            totalBegin: totB, totalEnd: totE,
+        });
+    }
+    return out;
+}
+/** Solar eclipses (global circumstances) in [jdStart, jdEnd] (UT JDs). */
+export function solarEclipses(engine, jdStart, jdEnd) {
+    const out = [];
+    for (const tNew of syzygies(engine, jdStart - 1, jdEnd + 1, 0.0)) {
+        const tMax = minimize((t) => solarGeom(engine, t)[0], tNew - 0.4, tNew + 0.4);
+        const [dAxis, rPen, rUmb, , f2] = solarGeom(engine, tMax);
+        if (dAxis > R_EARTH + rPen || tMax < jdStart || tMax > jdEnd)
+            continue;
+        const gamma = dAxis / R_EARTH;
+        let kind;
+        if (dAxis < R_EARTH) {
+            const depth = Math.sqrt(Math.max(R_EARTH ** 2 - dAxis ** 2, 0));
+            const rUmbSurface = rUmb + depth * Math.tan(f2);
+            kind = rUmb > 0 ? "total" : rUmbSurface > 0 ? "hybrid" : "annular";
+        }
+        else {
+            kind = "partial";
+        }
+        const f = (t) => {
+            const g = solarGeom(engine, t);
+            return g[0] - (R_EARTH + g[1]);
+        };
+        out.push({
+            tMax, type: kind, gamma,
+            begin: bisect(f, tMax - 0.35, tMax),
+            end: bisect(f, tMax, tMax + 0.35),
+        });
+    }
+    return out;
+}

package/dist/src/events.d.ts

@@ -0,0 +1,29 @@
+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;
+    /** Rise/set of the disc center instead of the upper limb. */
+    discCenter?: boolean;
+}
+/** Next rise/set/meridian transit (UT JD) after jdStart, or null when the
+ *  event does not occur in the window (polar day/night). */
+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"]>;
+/** Gauquelin sector (1..36, float) from rise/set times of the disc center
+ *  with refraction (Swiss Ephemeris method 3). Sectors run from rise: 1-18
+ *  above the horizon, 19-36 below. Null in polar no-rise/no-set
+ *  conditions. */
+export declare function gauquelinSector(engine: Engine, body: BodyId, jdUt: number, latDeg: number, lonDeg: number): number | null;

package/dist/src/events.js

@@ -0,0 +1,184 @@
+/**
+ * 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 (!opts.discCenter && 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;
+}
+/** Gauquelin sector (1..36, float) from rise/set times of the disc center
+ *  with refraction (Swiss Ephemeris method 3). Sectors run from rise: 1-18
+ *  above the horizon, 19-36 below. Null in polar no-rise/no-set
+ *  conditions. */
+export function gauquelinSector(engine, body, jdUt, latDeg, lonDeg) {
+    const surrounding = (kind) => {
+        let t = riseSet(engine, body, jdUt - 1.3, latDeg, lonDeg, kind, { discCenter: true });
+        let prev = null;
+        while (t !== null && t <= jdUt) {
+            prev = t;
+            t = riseSet(engine, body, t + 1e-4, latDeg, lonDeg, kind, { discCenter: true });
+        }
+        return [prev, t];
+    };
+    const [prevRise] = surrounding("rise");
+    const [prevSet, nextSetA] = surrounding("set");
+    if (prevRise === null || prevSet === null)
+        return null;
+    if (prevRise > prevSet) {
+        if (nextSetA === null)
+            return null;
+        return 1 + (18 * (jdUt - prevRise)) / (nextSetA - prevRise);
+    }
+    const [, nextRise] = surrounding("rise");
+    if (nextRise === null)
+        return null;
+    return 19 + (18 * (jdUt - prevSet)) / (nextRise - prevSet);
+}

package/dist/src/index.d.ts

@@ -2,3 +2,6 @@ export * from "./core.js";
 export * from "./houses.js";
 export * from "./chart.js";
 export * from "./pheno.js";
+export * from "./events.js";
+export * from "./stars.js";
+export * from "./eclipses.js";

package/dist/src/index.js

@@ -2,3 +2,6 @@ export * from "./core.js";
 export * from "./houses.js";
 export * from "./chart.js";
 export * from "./pheno.js";
+export * from "./events.js";
+export * from "./stars.js";
+export * from "./eclipses.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,18 @@ 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");
+    }
+    if (existsSync(join(dir, "fixed_stars.json"))) {
+        data.fixedStars = j("fixed_stars.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/stars.d.ts

@@ -0,0 +1,29 @@
+/**
+ * astroengine stars -- fixed stars: apparent places from the HYG-derived
+ * catalog (data/fixed_stars.json; ICRS J2000 with proper motions).
+ *
+ * Chain: full 3D space motion (proper motion + radial velocity at the
+ * parallax distance) -> ICRS equatorial -> ecliptic J2000 -> IAU 1976
+ * precession to date -> annual aberration (classic elliptic form, as for
+ * Pluto/Chiron) -> nutation. Validated against swe_fixstar fed the same
+ * catalog rows: <=0.6 arcsec over 1900-2099 (the floor is the IAU 1976 vs
+ * Vondrak precession difference, shared with the rest of the engine).
+ */
+import { EngineData } from "./core.js";
+export interface StarEntry {
+    ra: number;
+    dec: number;
+    pmra: number;
+    pmdec: number;
+    rv: number;
+    plx: number;
+    mag: number;
+    bayer: string;
+}
+export interface StarPack {
+    provenance: string;
+    frame: string;
+    stars: Record<string, StarEntry>;
+}
+/** Apparent ecliptic [lon, lat] of date (rad) for a catalog entry. */
+export declare function starApparent(data: EngineData, s: StarEntry, jde: number): [number, number];

package/dist/src/stars.js

@@ -0,0 +1,53 @@
+/**
+ * astroengine stars -- fixed stars: apparent places from the HYG-derived
+ * catalog (data/fixed_stars.json; ICRS J2000 with proper motions).
+ *
+ * Chain: full 3D space motion (proper motion + radial velocity at the
+ * parallax distance) -> ICRS equatorial -> ecliptic J2000 -> IAU 1976
+ * precession to date -> annual aberration (classic elliptic form, as for
+ * Pluto/Chiron) -> nutation. Validated against swe_fixstar fed the same
+ * catalog rows: <=0.6 arcsec over 1900-2099 (the floor is the IAU 1976 vs
+ * Vondrak precession difference, shared with the rest of the engine).
+ */
+import { DEG, ARCSEC, J2000, mod, nutation, precessEcliptic, vsopHeliocentric, } from "./core.js";
+const TWO_PI = 2 * Math.PI;
+const KM_PER_AU = 149597870.7;
+const AU_PER_PC = 206264.806;
+/** Apparent ecliptic [lon, lat] of date (rad) for a catalog entry. */
+export function starApparent(data, s, jde) {
+    const t = (jde - J2000) / 365.25;
+    const ra = s.ra * DEG;
+    const dec = s.dec * DEG;
+    const rAu = s.plx > 0 ? AU_PER_PC / (s.plx * 1e-3) : 1e9 * AU_PER_PC;
+    const cd = Math.cos(dec);
+    const sd = Math.sin(dec);
+    const cr = Math.cos(ra);
+    const sr = Math.sin(ra);
+    const p = [cd * cr, cd * sr, sd];
+    const east = [-sr, cr, 0.0];
+    const north = [-sd * cr, -sd * sr, cd];
+    const pmra = s.pmra * 1e-3 * ARCSEC;
+    const pmdec = s.pmdec * 1e-3 * ARCSEC;
+    const rv = (s.rv * 86400 * 365.25) / KM_PER_AU;
+    const pos = [0, 1, 2].map((i) => p[i] * rAu + (east[i] * pmra * rAu + north[i] * pmdec * rAu + p[i] * rv) * t);
+    const rn = Math.sqrt(pos[0] ** 2 + pos[1] ** 2 + pos[2] ** 2);
+    const x = pos[0] / rn;
+    const y = pos[1] / rn;
+    const z = pos[2] / rn;
+    const ra2 = Math.atan2(y, x);
+    const dec2 = Math.asin(z);
+    const e0 = 84381.448 * ARCSEC;
+    let lat = Math.asin(Math.sin(dec2) * Math.cos(e0) - Math.cos(dec2) * Math.sin(e0) * Math.sin(ra2));
+    let lon = mod(Math.atan2(Math.sin(ra2) * Math.cos(e0) + Math.tan(dec2) * Math.sin(e0), Math.cos(ra2)), TWO_PI);
+    [lon, lat] = precessEcliptic(lon, lat, J2000, jde);
+    const [L0] = vsopHeliocentric(data.vsop.earth, jde);
+    const sunLon = mod(L0 + Math.PI, TWO_PI);
+    const T = (jde - J2000) / 36525.0;
+    const k = 20.4898 * ARCSEC;
+    const e = 0.016708634 - 0.000042037 * T;
+    const piPer = (102.93735 + 1.71946 * T) * DEG;
+    lon += (-k * Math.cos(sunLon - lon) + e * k * Math.cos(piPer - lon)) / Math.cos(lat);
+    lat += -k * Math.sin(lat) * (Math.sin(sunLon - lon) - e * Math.sin(piPer - lon));
+    lon = mod(lon + nutation(data, jde)[0], TWO_PI);
+    return [lon, lat];
+}

package/package.json

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