caelus 0.2.0 → 0.3.0

package/README.md

@@ -9,8 +9,8 @@ ephemeris files. 1:1 port of the Python reference, checked by golden fixtures.
    every planet ≤ 1″ (Sun–Saturn), Moon ≤ 2.5″, Chiron ≤ 1″, nodes ≤ 1″
    (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: **1,438 checks,
-   0 failures, worst deviation 0.82 nano-arcseconds.** The two implementations
+2. TypeScript port verified against Python golden fixtures: **3,087 checks,
+   0 failures, worst deviation 1.64 nano-arcseconds.** The two implementations
    are numerically identical.
 
 Regenerate fixtures any time from the Python side; any future TS change must
@@ -34,9 +34,13 @@ Moon to ~10″ via the analytic series. The 729 KB tier (1920–2080 JPL-fit Moo
 
 ## Usage
 
+```bash
+npm install caelus
+```
+
 ```ts
 import { Engine, fmtLon } from "caelus";
-import { loadNodeData } from "caelus"; // Node only
+import { loadNodeData } from "caelus/node"; // Node only
 
 // Node: filesystem loader
 const engine = new Engine(loadNodeData("./data", "embedded", "full"));
@@ -82,3 +86,10 @@ test/golden.test.ts  conformance suite vs Python fixtures
   sums in reverse); keep orders identical to the Python reference.
 - All data is injected via `EngineData` — the core has zero I/O, zero deps,
   and runs identically in browser, edge runtime, or Node.
+
+## The caelus packages
+
+- 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

package/accuracy.json

@@ -18,7 +18,14 @@
     { "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": "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°" }
   ],
   "summary": [
     { "label": "Sun–Saturn", "bound": "≤ 1″" },
@@ -27,6 +34,10 @@
     { "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": "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″)" }
+  ],
+  "v03_harness": "python/validate_swiss.py regenerates every figure above the line against pyswisseph 2.10 (Moshier mode)"
 }

package/dist/src/chart.d.ts

@@ -1,17 +1,45 @@
 /** astroengine chart -- public API: natal charts, aspects, retrogrades. */
-import { EngineData } from "./core.js";
+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"];
+/** 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[];
 export declare const ASPECTS: Record<string, number>;
 export declare const DEFAULT_ORBS: Record<string, number>;
-export type HouseSystem = "placidus" | "porphyry" | "equal" | "whole_sign";
+export type HouseSystem = "placidus" | "porphyry" | "equal" | "whole_sign" | "koch" | "regiomontanus" | "campanus" | "alcabitius" | "morinus" | "meridian" | "polich_page" | "vehlow";
+export type Ayanamsa = keyof typeof AYANAMSA_J2000 & string;
+export type Zodiac = "tropical" | `sidereal:${string}`;
+export interface Observer {
+    lat: number;
+    lonEast: number;
+    altM?: number;
+}
+export interface CalcOptions {
+    zodiac?: Zodiac;
+    topocentric?: boolean;
+    observer?: Observer;
+}
+export interface ChartOptions extends CalcOptions {
+    houseSystem?: HouseSystem;
+    bodies?: BodyId[];
+    orbs?: Record<string, number>;
+}
 export interface Position {
     lon: number;
     speed: number;
     retrograde: boolean;
     sign: string;
     signDeg: number;
+    /** Ecliptic latitude, deg (0 for nodes). */
+    lat: number;
+    /** Geocentric distance in AU (Moon included); null for nodes and Lilith. */
+    dist: number | null;
+    /** Equatorial coordinates, true equinox of date, deg. */
+    ra: number;
+    dec: number;
 }
 export interface Aspect {
     a: string;
@@ -21,30 +49,46 @@ export interface Aspect {
 }
 export interface Chart {
     jdUt: number;
-    /** House system actually used. May differ from the request: Placidus is
-     *  undefined above the polar circles and falls back to whole_sign. */
+    zodiac: Zodiac;
+    /** House system actually used. May differ from the request: Placidus and
+     *  Koch are undefined above the polar circles and fall back to whole_sign. */
     houseSystem: HouseSystem;
     houseSystemRequested: HouseSystem;
     bodies: Record<string, Position>;
     angles: {
         asc: number;
         mc: number;
+        vertex: number;
+        eastPoint: number;
     };
     cusps: number[];
     aspects: Aspect[];
 }
 export declare class Engine {
-    private data;
+    readonly data: EngineData;
     private moonCheb;
     private chironCheb;
     constructor(data: EngineData);
     private moonInRange;
-    /** Apparent geocentric ecliptic longitude (deg), true equinox of date. */
-    longitude(body: Body, jdUt: number): number;
-    /** Longitude (deg) + speed (deg/day) + retrograde flag. */
-    position(body: Body, jdUt: number): Position;
-    /** Full natal chart. Time is UT. East longitude positive. */
-    chart(y: number, mo: number, d: number, h: number, mi: number, s: number, lat: number, lonEast: number, houseSystem?: HouseSystem): Chart;
+    /** 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;
+    private lonOnly;
+    /** Apparent geocentric ecliptic longitude (deg). Tropical: true equinox
+     *  of date. Sidereal: mean equinox minus ayanamsa. */
+    longitude(body: BodyId, jdUt: number, opts?: CalcOptions): number;
+    /** Geometric heliocentric ecliptic of date (deg, deg, AU). */
+    heliocentric(body: BodyId, jdUt: number): {
+        lon: number;
+        lat: number;
+        dist: number;
+    };
+    /** Full position: lon/speed/retrograde/sign + lat, dist (AU), ra, dec. */
+    position(body: BodyId, jdUt: number, opts?: CalcOptions): Position;
+    /** 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: number, mo: number, d: number, h: number, mi: number, s: number, lat: number, lonEast: number, opts?: HouseSystem | ChartOptions): Chart;
 }
 export declare function findAspects(bodies: Record<string, Position>, orbs?: Record<string, number>): Aspect[];
 export declare function fmtLon(deg: number): string;

package/dist/src/chart.js

@@ -1,10 +1,15 @@
 /** 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, 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"];
+/** Points: excluded from aspect search by default. */
+const NOT_ASPECTABLE = new Set(["mean_node", "true_node", "mean_lilith"]);
 export const SIGNS = [
     "Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra",
     "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces",
@@ -15,6 +20,20 @@ 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;
@@ -28,93 +47,225 @@ export class Engine {
         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);
+    }
+    /** Apparent geocentric [lon rad, lat rad, dist AU | null]. */
+    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];
         }
-        else if (body === "pluto") {
-            [lon] = plutoApparent(this.data, jde);
+        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];
+        }
+        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);
-        }
-        else if (body === "mean_node") {
-            lon = meanNode(this.data, 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 === "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 +285,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

@@ -68,5 +68,25 @@ 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];
+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];

package/dist/src/core.js

@@ -377,30 +377,99 @@ export function trueNodeSeries(data, jde) {
     const node = mod(Math.atan2(hx, -hy), TWO_PI);
     return mod(node + nutation(data, jde)[0], TWO_PI);
 }
+// ---------------------------------------------------------------- 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];
+}
+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) => {
-        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;
-        }
-        return [
-            (l + 238.958116 + 144.96 * T) * DEG,
-            (b - 3.908239) * DEG,
-            r + 40.7241346,
-        ];
-    };
+    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/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,4 @@
 export * from "./core.js";
 export * from "./houses.js";
 export * from "./chart.js";
+export * from "./pheno.js";

package/dist/src/index.js

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

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.0",
+  "version": "0.3.0",
   "description": "Astrological ephemeris engine. MIT, no AGPL, no ephemeris files. Checked against Swiss Ephemeris.",
   "type": "module",
   "main": "dist/src/index.js",