caelus 0.17.0 → 0.19.0

package/dist/src/counterfactual.d.ts

@@ -0,0 +1,82 @@
+/**
+ * astroengine counterfactual -- a real chart, perturbed, and what changed.
+ *
+ * The `counterfactual` realm: take a resolved chart and ask "what if". Shift the
+ * instant ("born an hour later") or the place -- a real ephemeris recompute --
+ * or splice a body to a new longitude ("Mars in the next sign") -- a geometry
+ * what-if that keeps everything else and recomputes the aspects it touches.
+ * {@link chartDiff} reports the difference so the change is legible, not buried
+ * in two full charts.
+ */
+import { Engine, Chart, ChartOptions, Aspect } from "./chart.js";
+import { AnchorRegistry } from "./provenance.js";
+import { AnchoredChart, RealizedChart } from "./anchored.js";
+/** A perturbation of a resolved chart. */
+export interface CounterfactualEdit {
+    /** Shift the resolved instant by a duration (e.g. `"1h"`, `"-30m"`, `"P1D"`). */
+    shiftTime?: string;
+    /** Recompute at a different place. */
+    place?: {
+        lat: number;
+        lonEast: number;
+        altM?: number;
+    };
+    /** Move bodies to given ecliptic longitudes (degrees), keeping everything else
+     *  -- a geometry what-if. The moved body's house and the touched aspects are
+     *  recomputed; the angles and other bodies are untouched. */
+    setLongitudes?: Record<string, number>;
+}
+/** A body whose sign or house changed between two charts. */
+export interface BodyChange {
+    body: string;
+    /** Signed degrees the body moved (`b` minus `a`). */
+    dLon: number;
+    signFrom: string;
+    signTo: string;
+    houseFrom: number;
+    houseTo: number;
+}
+/** An angle whose sign changed. */
+export interface AngleChange {
+    angle: string;
+    from: string;
+    to: string;
+}
+/** What differs between two charts. */
+export interface ChartDiff {
+    /** Bodies whose sign or house changed. */
+    bodies: BodyChange[];
+    /** Aspects present in the variant but not the original. */
+    aspectsGained: Aspect[];
+    /** Aspects present in the original but not the variant. */
+    aspectsLost: Aspect[];
+    /** Angles whose sign changed. */
+    angles: AngleChange[];
+}
+/** Diff two charts: body sign/house shifts, aspects gained/lost, angle sign
+ *  changes. Bodies and angles that did not change sign/house are omitted. */
+export declare function chartDiff(a: Chart, b: Chart): ChartDiff;
+/** A counterfactual: a base chart and a perturbed variant, with the diff. */
+export interface Counterfactual {
+    edit: CounterfactualEdit;
+    /** The realized base (its `chart` is the original). */
+    original: RealizedChart;
+    /** The perturbed chart, or null when the base had no chart to perturb. */
+    variant: Chart | null;
+    diff: ChartDiff | null;
+    note: string;
+}
+/**
+ * Realize an {@link AnchoredChart}, then apply a {@link CounterfactualEdit} and
+ * diff the result -- "a real event, perturbed." A time/place edit recomputes the
+ * ephemeris; a `setLongitudes` edit splices the geometry.
+ *
+ * @param engine The engine.
+ * @param base The base chart to perturb (realized via {@link realize}).
+ * @param edit The perturbation.
+ * @param registry Anchor lookups for the base.
+ * @param opts Chart options (house system, zodiac).
+ * @returns A {@link Counterfactual}; `variant`/`diff` are null when the base
+ *   produced no chart (e.g. a constraints-only form).
+ */
+export declare function counterfactual(engine: Engine, base: AnchoredChart, edit: CounterfactualEdit, registry?: AnchorRegistry, opts?: ChartOptions): Counterfactual;

package/dist/src/counterfactual.js

@@ -0,0 +1,105 @@
+/**
+ * astroengine counterfactual -- a real chart, perturbed, and what changed.
+ *
+ * The `counterfactual` realm: take a resolved chart and ask "what if". Shift the
+ * instant ("born an hour later") or the place -- a real ephemeris recompute --
+ * or splice a body to a new longitude ("Mars in the next sign") -- a geometry
+ * what-if that keeps everything else and recomputes the aspects it touches.
+ * {@link chartDiff} reports the difference so the change is legible, not buried
+ * in two full charts.
+ */
+import { SIGNS, findAspects, DEFAULT_ORBS, } from "./chart.js";
+import { houseOf } from "./electional.js";
+import { mod } from "./core.js";
+import { parseOffset } from "./provenance.js";
+import { realize } from "./anchored.js";
+const signOf = (lon) => SIGNS[Math.floor(mod(lon, 360) / 30)];
+const aspectKey = (x) => `${[x.a, x.b].sort().join("~")}:${x.aspect}`;
+/** Diff two charts: body sign/house shifts, aspects gained/lost, angle sign
+ *  changes. Bodies and angles that did not change sign/house are omitted. */
+export function chartDiff(a, b) {
+    const bodies = [];
+    for (const [name, pa] of Object.entries(a.bodies)) {
+        const pb = b.bodies[name];
+        if (!pa || !pb || (pa.sign === pb.sign && pa.house === pb.house))
+            continue;
+        bodies.push({
+            body: name, dLon: mod(pb.lon - pa.lon + 180, 360) - 180,
+            signFrom: pa.sign, signTo: pb.sign, houseFrom: pa.house, houseTo: pb.house,
+        });
+    }
+    const aset = new Set(a.aspects.map(aspectKey));
+    const bset = new Set(b.aspects.map(aspectKey));
+    const angles = [];
+    for (const ang of ["asc", "mc", "vertex", "eastPoint"]) {
+        const from = signOf(a.angles[ang]);
+        const to = signOf(b.angles[ang]);
+        if (from !== to)
+            angles.push({ angle: ang, from, to });
+    }
+    return {
+        bodies,
+        aspectsGained: b.aspects.filter((x) => !aset.has(aspectKey(x))),
+        aspectsLost: a.aspects.filter((x) => !bset.has(aspectKey(x))),
+        angles,
+    };
+}
+/** Splice bodies to new longitudes, recomputing their sign/house and the
+ *  aspects (the angles and untouched bodies stay as they were). */
+function spliceLongitudes(chart, overrides) {
+    const bodies = { ...chart.bodies };
+    for (const [name, lon] of Object.entries(overrides)) {
+        const cur = bodies[name];
+        if (!cur)
+            continue;
+        const L = mod(lon, 360);
+        bodies[name] = {
+            ...cur, lon: L, sign: SIGNS[Math.floor(L / 30)], signDeg: L % 30,
+            house: houseOf(L, chart.cusps),
+        };
+    }
+    return {
+        ...chart, bodies: bodies,
+        aspects: findAspects(bodies, DEFAULT_ORBS),
+    };
+}
+/**
+ * Realize an {@link AnchoredChart}, then apply a {@link CounterfactualEdit} and
+ * diff the result -- "a real event, perturbed." A time/place edit recomputes the
+ * ephemeris; a `setLongitudes` edit splices the geometry.
+ *
+ * @param engine The engine.
+ * @param base The base chart to perturb (realized via {@link realize}).
+ * @param edit The perturbation.
+ * @param registry Anchor lookups for the base.
+ * @param opts Chart options (house system, zodiac).
+ * @returns A {@link Counterfactual}; `variant`/`diff` are null when the base
+ *   produced no chart (e.g. a constraints-only form).
+ */
+export function counterfactual(engine, base, edit, registry = {}, opts = {}) {
+    const original = realize(engine, base, registry, opts);
+    if (!original.chart) {
+        return { edit, original, variant: null, diff: null, note: `nothing to perturb (${original.note})` };
+    }
+    const shiftsTimeOrPlace = edit.shiftTime !== undefined || edit.place !== undefined;
+    let variant = original.chart;
+    if (shiftsTimeOrPlace) {
+        const off = edit.shiftTime !== undefined ? parseOffset(edit.shiftTime) : 0;
+        if (Number.isNaN(off))
+            throw new Error(`unparseable shiftTime ${edit.shiftTime}`);
+        const lat = edit.place?.lat ?? original.place.place?.lat ?? 0;
+        const lon = edit.place?.lonEast ?? original.place.place?.lonEast ?? 0;
+        variant = engine.chartAt(original.time.jd + off, lat, lon, opts);
+    }
+    if (edit.setLongitudes)
+        variant = spliceLongitudes(variant, edit.setLongitudes);
+    const bits = [
+        edit.shiftTime !== undefined ? `time ${edit.shiftTime}` : null,
+        edit.place ? "place" : null,
+        edit.setLongitudes ? `moved ${Object.keys(edit.setLongitudes).join(", ")}` : null,
+    ].filter(Boolean);
+    return {
+        edit, original, variant, diff: chartDiff(original.chart, variant),
+        note: bits.length ? `perturbed: ${bits.join("; ")}` : "no edit applied",
+    };
+}

package/dist/src/eclipses.d.ts

@@ -38,3 +38,106 @@ export declare function lunarEclipses(engine: Engine, jdStart: number, jdEnd: nu
  * ```
  */
 export declare function solarEclipses(engine: Engine, jdStart: number, jdEnd: number): SolarEclipse[];
+/** Geographic point on the Earth's surface (geodetic latitude, east longitude). */
+export interface GeoPoint {
+    /** Geodetic latitude in degrees, north positive. */
+    lat: number;
+    /** Longitude in degrees, east positive, in (-180, 180]. */
+    lonEast: number;
+}
+/** Local circumstances of a solar eclipse seen from one place. */
+export interface SolarLocal {
+    /** What the observer sees at maximum: `"none"` when no part of the Sun is
+     *  covered from this place. */
+    type: "total" | "annular" | "partial" | "none";
+    /** Eclipse magnitude: fraction of the Sun's *diameter* covered at maximum
+     *  (can exceed 1 in totality). 0 when `type` is `"none"`. */
+    magnitude: number;
+    /** Obscuration: fraction of the Sun's *area* covered at maximum, in [0, 1]. */
+    obscuration: number;
+    /** Time of maximum eclipse at this place (JD UT), or `null` when unseen. */
+    maxTime: number | null;
+    /** First contact (partial begins), JD UT, or `null` when unseen. */
+    c1: number | null;
+    /** Second contact (totality/annularity begins), JD UT, or `null`. */
+    c2: number | null;
+    /** Third contact (totality/annularity ends), JD UT, or `null`. */
+    c3: number | null;
+    /** Fourth contact (partial ends), JD UT, or `null` when unseen. */
+    c4: number | null;
+}
+/**
+ * Sub-shadow geographic point where the eclipse axis meets the Earth at a
+ * Julian Day (UT): the centre line of totality/annularity at that instant.
+ * Sample it across the eclipse (e.g. between the {@link SolarEclipse} `begin`
+ * and `end`) to draw the ground track.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Instant to evaluate, Julian Day (UT) -- typically a
+ *   {@link SolarEclipse.tMax} for the point of greatest eclipse.
+ * @returns The {@link GeoPoint} on the IAU 1976 ellipsoid, or `null` when the
+ *   axis misses the Earth (only a partial eclipse exists anywhere then).
+ */
+export declare function solarEclipseWhere(engine: Engine, jd: number): GeoPoint | null;
+/**
+ * Local circumstances of a solar eclipse as seen from one place: contact
+ * times, magnitude, and obscuration. Topocentric Sun and Moon disks, so it
+ * accounts for lunar parallax (which is what makes the same eclipse total in
+ * one town and partial in the next).
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd A time near the eclipse, JD (UT) -- typically a
+ *   {@link SolarEclipse.tMax}; the local maximum is found within a few hours.
+ * @param latDeg Observer geodetic latitude in degrees (north positive).
+ * @param lonEastDeg Observer longitude in degrees (east positive).
+ * @param altM Observer height above the ellipsoid in metres (default 0).
+ * @returns {@link SolarLocal}. `type` is `"none"` when the Sun is not eclipsed
+ *   from this place at all; `c2`/`c3` are `null` outside totality/annularity.
+ */
+export declare function solarEclipseLocal(engine: Engine, jd: number, latDeg: number, lonEastDeg: number, altM?: number): SolarLocal;
+/** The umbra/antumbra path of a solar eclipse at one instant. */
+export interface EclipsePath {
+    /** Central line point (greatest coverage) at this instant. */
+    center: GeoPoint;
+    /** Northern edge of totality/annularity, or `null` if it runs off the Earth. */
+    north: GeoPoint | null;
+    /** Southern edge, or `null` if it runs off the Earth. */
+    south: GeoPoint | null;
+    /** Full path width (km) between the limits, or `null` when a limit is missing. */
+    widthKm: number | null;
+}
+/**
+ * Ground path of a solar eclipse at a Julian Day (UT): the central point and
+ * the north/south limits of totality (or annularity), with the path width.
+ * Marches perpendicular to the shadow's ground track out to the umbra edge --
+ * where the Moon just fully covers (or is covered by) the Sun. Sample across
+ * the eclipse to trace the full path of totality.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Instant to evaluate, Julian Day (UT) -- typically a
+ *   {@link SolarEclipse.tMax} for the path at greatest eclipse.
+ * @returns The {@link EclipsePath}, or `null` when no central eclipse exists
+ *   then (only a partial eclipse, or the axis misses the Earth).
+ */
+export declare function solarEclipseLimits(engine: Engine, jd: number): EclipsePath | null;
+/** Whether a lunar eclipse is up at a place, and how high the Moon stands. */
+export interface LunarLocal {
+    /** Moon's true altitude in degrees at the given instant (negative = below
+     *  the horizon). */
+    altitude: number;
+    /** Whether the Moon is above the horizon (the eclipse is visible there). */
+    visible: boolean;
+}
+/**
+ * Local visibility of a lunar eclipse: a lunar eclipse happens at the same
+ * instant for the whole Earth, so "local circumstances" is simply whether the
+ * Moon is up. Pass a contact time (e.g. {@link LunarEclipse.tMax} or a phase
+ * boundary) to learn whether that phase is visible from a place.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Instant to evaluate, Julian Day (UT).
+ * @param latDeg Observer latitude in degrees (north positive).
+ * @param lonEastDeg Observer longitude in degrees (east positive).
+ * @returns {@link LunarLocal} with the Moon's altitude and a visibility flag.
+ */
+export declare function lunarEclipseLocal(engine: Engine, jd: number, latDeg: number, lonEastDeg: number): LunarLocal;

package/dist/src/eclipses.js

@@ -11,9 +11,18 @@
  * 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.
+ *
+ * Solar (where): the same shadow axis intersected with the IAU 1976 Earth
+ * ellipsoid gives the sub-shadow geographic point -- the centre line of
+ * totality/annularity at an instant; sampled across the eclipse it draws the
+ * ground track. Solar (local): topocentric Sun/Moon disks at an observer give
+ * the contact times, magnitude, and obscuration as seen from that point. With
+ * a ~2.5" Moon these land within seconds of time and a few km of track: right
+ * for charts, not for eclipse-chaser path maps.
  */
-import { ARCSEC, jdTT, mod } from "./core.js";
+import { ARCSEC, DEG, jdTT, mod, trueObliquity, equatorial, topocentricEcl } from "./core.js";
+import { gast } from "./houses.js";
+import { azAlt } from "./pheno.js";
 const KM_PER_AU = 149597870.7;
 const R_EARTH = 6378.14;
 const R_SUN = 696000.0;
@@ -177,3 +186,252 @@ export function solarEclipses(engine, jdStart, jdEnd) {
     }
     return out;
 }
+// ---------------------------------------------------------------- where + local
+const EARTH_FLAT = 0.99664719; // 1 - f, IAU 1976 figure (b/a)
+const EARTH_FLAT2 = EARTH_FLAT * EARTH_FLAT; // (b/a)^2 = 1 - e^2
+/** Geocentric *equatorial* Cartesian (km) of the Sun and Moon, plus obliquity. */
+function sunMoonEq(engine, jde) {
+    const eps = trueObliquity(engine.data, jde);
+    const vec = (body) => {
+        const [lon, lat, dist] = engine.ecliptic(body, jde);
+        const [ra, dec] = equatorial(lon, lat, eps);
+        const r = dist * KM_PER_AU;
+        return [
+            r * Math.cos(dec) * Math.cos(ra),
+            r * Math.cos(dec) * Math.sin(ra),
+            r * Math.sin(dec),
+        ];
+    };
+    return { S: vec("sun"), M: vec("moon") };
+}
+/**
+ * Sub-shadow geographic point where the eclipse axis meets the Earth at a
+ * Julian Day (UT): the centre line of totality/annularity at that instant.
+ * Sample it across the eclipse (e.g. between the {@link SolarEclipse} `begin`
+ * and `end`) to draw the ground track.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Instant to evaluate, Julian Day (UT) -- typically a
+ *   {@link SolarEclipse.tMax} for the point of greatest eclipse.
+ * @returns The {@link GeoPoint} on the IAU 1976 ellipsoid, or `null` when the
+ *   axis misses the Earth (only a partial eclipse exists anywhere then).
+ */
+export function solarEclipseWhere(engine, jd) {
+    const jde = jdTT(jd);
+    const { S, M } = sunMoonEq(engine, jde);
+    const SM = [M[0] - S[0], M[1] - S[1], M[2] - S[2]];
+    const smn = Math.hypot(SM[0], SM[1], SM[2]);
+    const d = SM.map((c) => c / smn); // travels Sun -> Moon -> Earth
+    // Intersect the line M + s*d with the ellipsoid by scaling z by 1/flat,
+    // which maps the ellipsoid to a sphere of radius R_EARTH.
+    const Mz = [M[0], M[1], M[2] / EARTH_FLAT];
+    const dz = [d[0], d[1], d[2] / EARTH_FLAT];
+    const a = dz[0] ** 2 + dz[1] ** 2 + dz[2] ** 2;
+    const b = 2 * (Mz[0] * dz[0] + Mz[1] * dz[1] + Mz[2] * dz[2]);
+    const c = Mz[0] ** 2 + Mz[1] ** 2 + Mz[2] ** 2 - R_EARTH ** 2;
+    const disc = b * b - 4 * a * c;
+    if (disc < 0)
+        return null;
+    const s = (-b - Math.sqrt(disc)) / (2 * a); // near side, facing the Moon
+    const P = [M[0] + s * d[0], M[1] + s * d[1], M[2] + s * d[2]];
+    const rho = Math.hypot(P[0], P[1]);
+    const lat = Math.atan2(P[2], EARTH_FLAT2 * rho); // geocentric -> geodetic
+    const ra = Math.atan2(P[1], P[0]);
+    const lonEast = mod(ra - gast(engine.data, jd) + Math.PI, 2 * Math.PI) - Math.PI;
+    return { lat: lat / DEG, lonEast: lonEast / DEG };
+}
+/** Topocentric Sun/Moon angular separation and disk radii (rad) at a place. */
+function topoCircs(engine, jd, latDeg, lonEastDeg, altM) {
+    const jde = jdTT(jd);
+    const eps = trueObliquity(engine.data, jde);
+    const lst = mod(gast(engine.data, jd) + lonEastDeg * DEG, 2 * Math.PI);
+    const topo = (body) => {
+        const [lon, lat, dist] = engine.ecliptic(body, jde);
+        return topocentricEcl(lon, lat, dist, lst, latDeg * DEG, altM, eps);
+    };
+    const [slon, slat, sdist] = topo("sun");
+    const [mlon, mlat, mdist] = topo("moon");
+    const cosSep = Math.sin(slat) * Math.sin(mlat)
+        + Math.cos(slat) * Math.cos(mlat) * Math.cos(slon - mlon);
+    return {
+        sep: Math.acos(Math.max(-1, Math.min(1, cosSep))),
+        sS: Math.asin(R_SUN / (sdist * KM_PER_AU)),
+        sM: Math.asin(R_MOON / (mdist * KM_PER_AU)),
+    };
+}
+/** Area where two disks (radii r1, r2, centre distance d) overlap. */
+function lensArea(d, r1, r2) {
+    if (d >= r1 + r2)
+        return 0;
+    if (d <= Math.abs(r1 - r2))
+        return Math.PI * Math.min(r1, r2) ** 2;
+    const a1 = Math.acos((d * d + r1 * r1 - r2 * r2) / (2 * d * r1));
+    const a2 = Math.acos((d * d + r2 * r2 - r1 * r1) / (2 * d * r2));
+    return r1 * r1 * (a1 - Math.sin(2 * a1) / 2) + r2 * r2 * (a2 - Math.sin(2 * a2) / 2);
+}
+/** Step out from `tMax` (where g < 0) until `g` changes sign, then bisect. */
+function contact(g, tMax, dir) {
+    const step = 0.003; // ~4.3 min
+    let prev = tMax;
+    let fprev = g(tMax);
+    for (let i = 1; i <= 120; i++) { // search up to ~8.6 h either side
+        const t = tMax + dir * i * step;
+        const f = g(t);
+        if (fprev * f <= 0)
+            return bisect(g, Math.min(prev, t), Math.max(prev, t));
+        prev = t;
+        fprev = f;
+    }
+    return null;
+}
+/**
+ * Local circumstances of a solar eclipse as seen from one place: contact
+ * times, magnitude, and obscuration. Topocentric Sun and Moon disks, so it
+ * accounts for lunar parallax (which is what makes the same eclipse total in
+ * one town and partial in the next).
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd A time near the eclipse, JD (UT) -- typically a
+ *   {@link SolarEclipse.tMax}; the local maximum is found within a few hours.
+ * @param latDeg Observer geodetic latitude in degrees (north positive).
+ * @param lonEastDeg Observer longitude in degrees (east positive).
+ * @param altM Observer height above the ellipsoid in metres (default 0).
+ * @returns {@link SolarLocal}. `type` is `"none"` when the Sun is not eclipsed
+ *   from this place at all; `c2`/`c3` are `null` outside totality/annularity.
+ */
+export function solarEclipseLocal(engine, jd, latDeg, lonEastDeg, altM = 0) {
+    const sepAt = (t) => topoCircs(engine, t, latDeg, lonEastDeg, altM).sep;
+    const tMax = minimize(sepAt, jd - 0.2, jd + 0.2);
+    const { sep, sS, sM } = topoCircs(engine, tMax, latDeg, lonEastDeg, altM);
+    const none = {
+        type: "none", magnitude: 0, obscuration: 0,
+        maxTime: null, c1: null, c2: null, c3: null, c4: null,
+    };
+    if (sep >= sS + sM)
+        return none;
+    const type = sep <= sM - sS ? "total" : sep <= sS - sM ? "annular" : "partial";
+    const gOuter = (t) => {
+        const c = topoCircs(engine, t, latDeg, lonEastDeg, altM);
+        return c.sep - (c.sS + c.sM);
+    };
+    let c2 = null;
+    let c3 = null;
+    if (type === "total" || type === "annular") {
+        const gInner = (t) => {
+            const c = topoCircs(engine, t, latDeg, lonEastDeg, altM);
+            return c.sep - Math.abs(c.sM - c.sS);
+        };
+        c2 = contact(gInner, tMax, -1);
+        c3 = contact(gInner, tMax, 1);
+    }
+    // Magnitude = fraction of the Sun's diameter covered. In the partial regime
+    // one Moon edge is inside the Sun's disk; once central (annular or total) it
+    // is the Moon/Sun diameter ratio -- < 1 in annularity, > 1 in totality.
+    return {
+        type,
+        magnitude: sep <= Math.abs(sM - sS) ? sM / sS : (sS + sM - sep) / (2 * sS),
+        obscuration: lensArea(sep, sS, sM) / (Math.PI * sS * sS),
+        maxTime: tMax,
+        c1: contact(gOuter, tMax, -1),
+        c2, c3,
+        c4: contact(gOuter, tMax, 1),
+    };
+}
+const R_MEAN = 6371.0; // mean Earth radius (km) for short surface offsets
+/** Geodetic destination point `distKm` from (lat, lon) along `bearingDeg`. */
+function destPoint(lat, lon, bearingDeg, distKm) {
+    const d = distKm / R_MEAN;
+    const br = bearingDeg * DEG;
+    const p1 = lat * DEG;
+    const l1 = lon * DEG;
+    const p2 = Math.asin(Math.sin(p1) * Math.cos(d) + Math.cos(p1) * Math.sin(d) * Math.cos(br));
+    const l2 = l1 + Math.atan2(Math.sin(br) * Math.sin(d) * Math.cos(p1), Math.cos(d) - Math.sin(p1) * Math.sin(p2));
+    return { lat: p2 / DEG, lonEast: mod(l2 / DEG + 540, 360) - 180 };
+}
+/** Initial great-circle bearing (deg) from `a` to `b`. */
+function bearing(a, b) {
+    const p1 = a.lat * DEG;
+    const p2 = b.lat * DEG;
+    const dl = (b.lonEast - a.lonEast) * DEG;
+    return mod(Math.atan2(Math.sin(dl) * Math.cos(p2), Math.cos(p1) * Math.sin(p2) - Math.sin(p1) * Math.cos(p2) * Math.cos(dl)) / DEG, 360);
+}
+/** Great-circle distance (km) between two geographic points. */
+function greatCircleKm(a, b) {
+    const p1 = a.lat * DEG;
+    const p2 = b.lat * DEG;
+    const dp = (b.lat - a.lat) * DEG;
+    const dl = (b.lonEast - a.lonEast) * DEG;
+    const h = Math.sin(dp / 2) ** 2 + Math.cos(p1) * Math.cos(p2) * Math.sin(dl / 2) ** 2;
+    return R_MEAN * 2 * Math.atan2(Math.sqrt(h), Math.sqrt(1 - h));
+}
+/**
+ * Ground path of a solar eclipse at a Julian Day (UT): the central point and
+ * the north/south limits of totality (or annularity), with the path width.
+ * Marches perpendicular to the shadow's ground track out to the umbra edge --
+ * where the Moon just fully covers (or is covered by) the Sun. Sample across
+ * the eclipse to trace the full path of totality.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Instant to evaluate, Julian Day (UT) -- typically a
+ *   {@link SolarEclipse.tMax} for the path at greatest eclipse.
+ * @returns The {@link EclipsePath}, or `null` when no central eclipse exists
+ *   then (only a partial eclipse, or the axis misses the Earth).
+ */
+export function solarEclipseLimits(engine, jd) {
+    const center = solarEclipseWhere(engine, jd);
+    if (center === null)
+        return null;
+    const ahead = solarEclipseWhere(engine, jd + 1 / 86400);
+    const track = ahead ? bearing(center, ahead) : 0; // ground-track direction
+    // Inside the umbra/antumbra the centres are closer than |radii difference|.
+    const edge = (lat, lon) => {
+        const c = topoCircs(engine, jd, lat, lon, 0);
+        return c.sep - Math.abs(c.sM - c.sS);
+    };
+    const march = (brg) => {
+        let gPrev = edge(center.lat, center.lonEast); // < 0 on the central line
+        for (let s = 4; s <= 400; s += 4) {
+            const q = destPoint(center.lat, center.lonEast, brg, s);
+            if (gPrev * edge(q.lat, q.lonEast) <= 0) {
+                let lo = s - 4;
+                let hi = s; // edge is between lo (inside) and hi (outside)
+                for (let i = 0; i < 40; i++) {
+                    const mid = (lo + hi) / 2;
+                    const qm = destPoint(center.lat, center.lonEast, brg, mid);
+                    if (edge(qm.lat, qm.lonEast) <= 0)
+                        lo = mid;
+                    else
+                        hi = mid;
+                }
+                return destPoint(center.lat, center.lonEast, brg, (lo + hi) / 2);
+            }
+            gPrev = edge(q.lat, q.lonEast);
+        }
+        return null;
+    };
+    const a = march(mod(track - 90, 360));
+    const b = march(mod(track + 90, 360));
+    // Label by latitude so `north` is always the higher-latitude edge.
+    const [north, south] = !a || !b ? [a, b] : a.lat >= b.lat ? [a, b] : [b, a];
+    return {
+        center, north, south,
+        widthKm: north && south ? greatCircleKm(north, south) : null,
+    };
+}
+/**
+ * Local visibility of a lunar eclipse: a lunar eclipse happens at the same
+ * instant for the whole Earth, so "local circumstances" is simply whether the
+ * Moon is up. Pass a contact time (e.g. {@link LunarEclipse.tMax} or a phase
+ * boundary) to learn whether that phase is visible from a place.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jd Instant to evaluate, Julian Day (UT).
+ * @param latDeg Observer latitude in degrees (north positive).
+ * @param lonEastDeg Observer longitude in degrees (east positive).
+ * @returns {@link LunarLocal} with the Moon's altitude and a visibility flag.
+ */
+export function lunarEclipseLocal(engine, jd, latDeg, lonEastDeg) {
+    const [mlon, mlat] = engine.ecliptic("moon", jdTT(jd));
+    const [, altitude] = azAlt(engine.data, mlon / DEG, mlat / DEG, jd, latDeg, lonEastDeg);
+    return { altitude, visible: altitude > 0 };
+}

package/dist/src/index.d.ts

@@ -28,5 +28,11 @@ export * from "./ashtottari.js";
 export * from "./rajayoga.js";
 export * from "./patterns.js";
 export * from "./signature.js";
+export * from "./interpretation.js";
+export * from "./interpret.js";
+export * from "./brief.js";
+export * from "./provenance.js";
+export * from "./anchored.js";
+export * from "./counterfactual.js";
 export * from "./dignity-score.js";
 export * from "./parans.js";

package/dist/src/index.js

@@ -28,5 +28,11 @@ export * from "./ashtottari.js";
 export * from "./rajayoga.js";
 export * from "./patterns.js";
 export * from "./signature.js";
+export * from "./interpretation.js";
+export * from "./interpret.js";
+export * from "./brief.js";
+export * from "./provenance.js";
+export * from "./anchored.js";
+export * from "./counterfactual.js";
 export * from "./dignity-score.js";
 export * from "./parans.js";