@openwaters/almanac 0.0.0-bootstrap

package/dist/events.js

@@ -0,0 +1,492 @@
+// L3 event searches: sun rise/set, the three twilights, solar transit,
+// moonrise/moonset, and the four quarter moon phases.
+//
+// Two different algorithms live here, for two different reasons.
+//
+// The altitude searches are NOT translated from upstream. Upstream's
+// `SearchRiseSet` walks a fixed 0.42-day grid guarded by a maximum-slope prune;
+// a grid can straddle both halves of a grazing pair (the polar-onset day where
+// the Sun sets at 08:00 and rises again at 08:16) and report neither. Here each
+// daily cycle's altitude extrema are located numerically and every monotonic
+// segment between consecutive extrema is bisected, so a pair of crossings
+// minutes apart is bracketed by construction rather than by luck of the grid.
+// Hour angle supplies only the initial bracket: HA 0/12h are not the exact
+// extrema, because declination, distance and lunar parallax all drift within a
+// cycle, and toward the poles the daily altitude cycle flattens until the
+// extremum wanders hours away from transit.
+//
+// `searchMoonPhases` IS translated, from the cosinekitty/astronomy upstream at
+// pinned sha 865d3da7d8112bbc7911238052c6af4aaf877181, source/js/astronomy.ts:
+// `SearchMoonPhase` (~5260) and the `Search` (~4634) / `QuadInterp` (~4528)
+// root finder it calls, plus the quarter walk of `SearchMoonQuarter` (~5339)
+// and `NextMoonQuarter` (~5362).
+import { assertObserver, assertSupported, assertSupportedWindowEnd, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
+import { dateFromUt, ttDaysFromUt, utDays } from './time.js';
+import { KM_PER_AU, RAD2DEG } from './nutation.js';
+import { topoAltAzUnrefracted } from './transforms.js';
+import { sunGeoVectorEqj } from './sun.js';
+import { moonGeoVectorEqj } from './moon.js';
+import { moonPhaseDeg } from './illumination.js';
+// ---------------------------------------------------------------- constants
+const CIVIL_ALT_DEG = -6;
+const NAUTICAL_ALT_DEG = -12;
+const ASTRO_ALT_DEG = -18;
+/**
+ * Body radii, for the semidiameter that lowers each rise/set target — and, in
+ * the L3 eclipse layer, for the Earth's shadow cone and the Moon it falls on.
+ * INTERNAL: exported for `eclipse.ts`, not part of the public API.
+ */
+export const MOON_MEAN_RADIUS_KM = 1737.4;
+/** UPSTREAM: `SUN_RADIUS_KM`, astronomy.ts line 134. INTERNAL, see above. */
+export const SUN_RADIUS_KM = 695700;
+const HORIZON_REFRACTION_DEG = 34 / 60;
+/**
+ * The upper-limb rise/set target: unrefracted centre altitude at
+ * −(34′ + the body's true semidiameter at the distance the observer sees).
+ * Spec, Conventions: the same rule for both bodies — a fixed 16′ for the Sun
+ * sits ~10″ off USNO near aphelion and perihelion, which a high-latitude graze
+ * turns into a minute.
+ */
+function upperLimbTargetDeg(radiusKm, distanceAu) {
+    return -HORIZON_REFRACTION_DEG - RAD2DEG * Math.asin(radiusKm / (distanceAu * KM_PER_AU));
+}
+/** Mean hour-angle advance. The Sun's is a mean solar day by definition. */
+const SUN_HA_RATE_DEG_PER_DAY = 360;
+const SUN_CYCLE_DAYS = 1;
+/** Mean lunar day, 24h50m28s. */
+const MOON_CYCLE_DAYS = 1.035050;
+const MOON_HA_RATE_DEG_PER_DAY = 360 / MOON_CYCLE_DAYS;
+const SECOND_DAYS = 1 / 86400;
+/** Bisection and golden-section both stop under a second; events are reported to the ms. */
+const TIME_TOL_DAYS = SECOND_DAYS;
+/** An extremum this close to the target grazes it without crossing: no event. */
+const TANGENT_EPS_DEG = 1e-6;
+/** Initial half-bracket around the hour-angle estimate of an extremum. */
+const EXTREMUM_HALF_WIDTH_DAYS = 2 / 24;
+/**
+ * Where the daily cycle flattens the extremum drifts hours off transit — the
+ * offset scales as 1/cos φ — so there the bracket is the whole half-cycle
+ * instead. The threshold is 85°, not the 89° where the drift becomes dramatic:
+ * the Moon's fast declination rate already puts the extremum 2.28 h off transit
+ * at 88°N and 5.75 h at 88.9°N, past the ±2 h bracket, and golden section then
+ * converges to a bracket edge and the monotonic-segment invariant breaks. The
+ * cost of the wider threshold is a few extra golden-section steps at latitudes
+ * almost nobody queries.
+ */
+const FLAT_CYCLE_LATITUDE_DEG = 85;
+const GOLDEN_SECTION_CAP = 100;
+const BISECTION_CAP = 60;
+const HOUR_ANGLE_ITER_CAP = 20;
+const MOON_PHASE_ITER_CAP = 50;
+const INV_PHI = 0.6180339887498949;
+const MIN_UT = utDays(new Date(SUPPORTED_MIN));
+const MAX_UT = utDays(new Date(SUPPORTED_MAX));
+/**
+ * Clamps a probe into the supported interval. The altitude-search chain
+ * (searchAltitudeEvents) applies this to every probe it samples, so it never
+ * evaluates the model outside [MIN_UT, MAX_UT]. The phase-search walk
+ * (searchMoonPhases) only clamps its first probe — later quarter-to-quarter
+ * probes can land past MAX_UT and evaluate the model there harmlessly; it is
+ * the half-open window filter on emitted results, not this clamp, that keeps
+ * reported answers inside the interval.
+ */
+function clampUt(ut) {
+    return ut < MIN_UT ? MIN_UT : (ut > MAX_UT ? MAX_UT : ut);
+}
+/**
+ * Truncates a ut-days root to the same integer-ms precision `dateFromUt`
+ * reports it at (TimeClip). A root finder's raw `ut` carries sub-ms
+ * precision; comparing that raw value against a half-open window bound can
+ * pass while the truncated instant it is actually reported as lands exactly
+ * on the excluded end (a pre-1970 negative offset truncates UP, toward the
+ * boundary). The half-open filter must judge the reported instant, not the
+ * root. Exported for its direct micro-test, mirroring the Swift port's
+ * (which relaxes the same function to `internal` for the same reason);
+ * no other module consumes it.
+ */
+export function quantizedUt(ut) {
+    return utDays(dateFromUt(ut));
+}
+/** Hitting an iteration cap is a bug, not a runtime condition — see the spec. */
+function assertReached(condition, what) {
+    if (!condition)
+        throw new Error(`almanac internal: ${what} did not converge`);
+}
+function sunSampler(observer) {
+    return (ut) => {
+        const p = topoAltAzUnrefracted(sunGeoVectorEqj(ttDaysFromUt(ut)), ut, observer);
+        return {
+            ut, altDeg: p.altDeg, hourAngleDeg: p.hourAngleDeg,
+            riseSetAltDeg: upperLimbTargetDeg(SUN_RADIUS_KM, p.distanceAu)
+        };
+    };
+}
+function moonSampler(observer) {
+    return (ut) => {
+        const p = topoAltAzUnrefracted(moonGeoVectorEqj(ttDaysFromUt(ut)), ut, observer);
+        return {
+            ut, altDeg: p.altDeg, hourAngleDeg: p.hourAngleDeg,
+            riseSetAltDeg: upperLimbTargetDeg(MOON_MEAN_RADIUS_KM, p.distanceAu)
+        };
+    };
+}
+function offsetDeg(s, level) {
+    return s.altDeg - (level === null ? s.riseSetAltDeg : level);
+}
+/** −1 below, +1 above, 0 grazing (within {@link TANGENT_EPS_DEG}: touches, never crosses). */
+function crossingSign(s, level) {
+    const f = offsetDeg(s, level);
+    return Math.abs(f) <= TANGENT_EPS_DEG ? 0 : Math.sign(f);
+}
+// ----------------------------------------------------------- root findings
+/** Wrap a hour-angle difference into (−180, 180]. */
+function angleOffset(diff) {
+    let offset = diff % 360;
+    if (offset <= -180)
+        offset += 360;
+    else if (offset > 180)
+        offset -= 360;
+    return offset;
+}
+/**
+ * Time of the next local hour angle `targetHaDeg` strictly after `afterUt`:
+ * one advance at the body's mean rate, then fixed-point refinement at the same
+ * rate. The rate is right to a few percent, so each step cuts the error by ~20×
+ * and the loop settles in three or four iterations. This is both the bracket
+ * centre for an altitude extremum and — for `targetHaDeg = 0` — the transit
+ * event itself.
+ */
+function nextHourAngle(sample, afterUt, targetHaDeg, rateDegPerDay) {
+    let deficit = ((targetHaDeg - sample(afterUt).hourAngleDeg) % 360 + 360) % 360;
+    if (deficit === 0)
+        deficit = 360; // already there: take the next one, not this one
+    let ut = afterUt + deficit / rateDegPerDay;
+    for (let i = 0; i < HOUR_ANGLE_ITER_CAP; i++) {
+        const step = angleOffset(targetHaDeg - sample(ut).hourAngleDeg) / rateDegPerDay;
+        ut += step;
+        if (Math.abs(step) < TIME_TOL_DAYS)
+            return ut;
+    }
+    assertReached(false, 'hour-angle iteration');
+    return ut;
+}
+/**
+ * Golden-section refinement of the altitude extremum bracketed around
+ * `centreUt`. Evaluating the true extremum is what makes a grazing pair
+ * findable: the segment on either side of it is monotonic, so bisection can
+ * only miss a crossing if the extremum itself was never seen.
+ *
+ * `afterUt` is the previous extremum. It matters only under the widened
+ * high-latitude bracket, where the half-cycle window would otherwise reach back
+ * past it — and at the pole, where the daily cycle degenerates into the
+ * declination's slow annual drift, unclamped golden section will happily walk
+ * backwards and break the chain's ordering.
+ */
+function refineExtremum(sample, centreUt, wantMax, halfWidthDays, afterUt) {
+    let a = Math.max(clampUt(centreUt - halfWidthDays), afterUt);
+    let b = clampUt(centreUt + halfWidthDays);
+    let x1 = b - INV_PHI * (b - a);
+    let x2 = a + INV_PHI * (b - a);
+    let s1 = sample(x1);
+    let s2 = sample(x2);
+    const score = (s) => (wantMax ? s.altDeg : -s.altDeg);
+    let converged = false;
+    for (let i = 0; i < GOLDEN_SECTION_CAP; i++) {
+        if (b - a < TIME_TOL_DAYS) {
+            converged = true;
+            break;
+        }
+        if (score(s1) > score(s2)) {
+            b = x2;
+            x2 = x1;
+            s2 = s1;
+            x1 = b - INV_PHI * (b - a);
+            s1 = sample(x1);
+        }
+        else {
+            a = x1;
+            x1 = x2;
+            s1 = s2;
+            x2 = a + INV_PHI * (b - a);
+            s2 = sample(x2);
+        }
+    }
+    assertReached(converged, 'golden-section extremum refinement');
+    return score(s1) > score(s2) ? s1 : s2;
+}
+/**
+ * Bisection for the single crossing of `level` on the monotonic segment
+ * between two consecutive extrema.
+ */
+function bisectCrossing(sample, level, s0, s1) {
+    let a = s0.ut;
+    let b = s1.ut;
+    let belowAtA = offsetDeg(s0, level) < 0;
+    for (let i = 0; i < BISECTION_CAP; i++) {
+        if (b - a < TIME_TOL_DAYS)
+            return (a + b) / 2;
+        const mid = (a + b) / 2;
+        if ((offsetDeg(sample(mid), level) < 0) === belowAtA)
+            a = mid;
+        else
+            b = mid;
+    }
+    assertReached(false, 'crossing bisection');
+    return (a + b) / 2;
+}
+/**
+ * Walk the window one half-cycle at a time, refining each altitude extremum and
+ * solving every monotonic segment between consecutive extrema for every target
+ * level. The chain starts a full cycle before `startUt` so the segment
+ * containing the window's first instant is covered, and runs one extremum past
+ * `endUt` so an event just inside the window's end is too.
+ */
+function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRateDegPerDay, cycleDays, extremumHalfWidthDays) {
+    const found = [];
+    const emit = (ut, kind) => {
+        const q = quantizedUt(ut);
+        if (q >= startUt && q < endUt)
+            found.push({ ut, kind }); // half-open [start, end), judged on the reported instant
+    };
+    // The chain's first point need not be an extremum: between any instant and
+    // the next extremum after it the altitude is already monotonic.
+    let s0 = sample(clampUt(startUt - cycleDays));
+    const firstMax = nextHourAngle(sample, s0.ut, 0, haRateDegPerDay);
+    const firstMin = nextHourAngle(sample, s0.ut, 180, haRateDegPerDay);
+    let nextIsMax = firstMax <= firstMin;
+    let nextEst = nextIsMax ? firstMax : firstMin;
+    const stepCap = Math.ceil(2 * (endUt - s0.ut) / cycleDays) + 8;
+    let steps = 0;
+    while (s0.ut < endUt && s0.ut < MAX_UT) {
+        assertReached(steps++ < stepCap, 'extremum chain');
+        const atRangeEnd = nextEst >= MAX_UT;
+        // At the supported-interval edge the boundary instant stands in for the
+        // extremum we are not allowed to probe past. The segment up to it is
+        // still monotonic, so any crossing inside the window is still found.
+        const s1 = atRangeEnd ? sample(MAX_UT)
+            : refineExtremum(sample, nextEst, nextIsMax, extremumHalfWidthDays, s0.ut);
+        assertReached(s1.ut > s0.ut, 'extremum chain ordering');
+        for (const spec of levels) {
+            const g0 = crossingSign(s0, spec.level);
+            const g1 = crossingSign(s1, spec.level);
+            if (g0 * g1 >= 0)
+                continue; // no crossing, or a graze that only touches
+            emit(bisectCrossing(sample, spec.level, s0, s1), g1 > 0 ? spec.rising : spec.falling);
+        }
+        if (nextIsMax && transitKind !== null && !atRangeEnd)
+            emit(nextEst, transitKind);
+        s0 = s1;
+        if (atRangeEnd)
+            break;
+        nextIsMax = !nextIsMax;
+        nextEst = nextHourAngle(sample, nextEst, nextIsMax ? 0 : 180, haRateDegPerDay);
+    }
+    found.sort((a, b) => a.ut - b.ut);
+    return found.map((e) => ({ time: dateFromUt(e.ut), kind: e.kind }));
+}
+const SUN_LEVELS = [
+    { level: null, rising: 'rise', falling: 'set' },
+    { level: CIVIL_ALT_DEG, rising: 'civilDawn', falling: 'civilDusk' },
+    { level: NAUTICAL_ALT_DEG, rising: 'nauticalDawn', falling: 'nauticalDusk' },
+    { level: ASTRO_ALT_DEG, rising: 'astroDawn', falling: 'astroDusk' },
+];
+const MOON_LEVELS = [
+    { level: null, rising: 'rise', falling: 'set' },
+];
+function extremumHalfWidth(observer, cycleDays) {
+    return Math.abs(observer.latitudeDeg) >= FLAT_CYCLE_LATITUDE_DEG
+        ? cycleDays / 2
+        : EXTREMUM_HALF_WIDTH_DAYS;
+}
+/**
+ * Sun rise, set, the three twilights and upper transit within the half-open
+ * window `[startUtc, endUtc)`, sorted ascending.
+ *
+ * Rise and set are the unrefracted geometric centre altitude at −(34′ + the
+ * Sun's true semidiameter at distance) — the upper-limb convention with the
+ * actual disc, the same rule the Moon gets; the twilights are centre altitude
+ * −6°, −12° and −18° with no refraction term; transit is local hour angle
+ * zero. An empty list is a valid answer — polar day and polar night drop
+ * the crossings — while transit is reported regardless of whether the Sun is
+ * above the horizon when it happens.
+ */
+export function sunEvents(startUtc, endUtc, observer) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    assertObserver(observer);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    return searchAltitudeEvents(sunSampler(observer), SUN_LEVELS, 'transit', utDays(startUtc), utDays(endUtc), SUN_HA_RATE_DEG_PER_DAY, SUN_CYCLE_DAYS, extremumHalfWidth(observer, SUN_CYCLE_DAYS));
+}
+/**
+ * Moonrise and moonset within the half-open window `[startUtc, endUtc)`,
+ * sorted ascending — the apparent topocentric upper limb crossing the horizon,
+ * so refraction (34′), topocentric parallax and the true semidiameter at the
+ * Moon's distance are all included — the same upper-limb rule as the Sun's. An empty list is a valid answer.
+ */
+export function moonEvents(startUtc, endUtc, observer) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    assertObserver(observer);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    return searchAltitudeEvents(moonSampler(observer), MOON_LEVELS, null, utDays(startUtc), utDays(endUtc), MOON_HA_RATE_DEG_PER_DAY, MOON_CYCLE_DAYS, extremumHalfWidth(observer, MOON_CYCLE_DAYS));
+}
+// -------------------------------------------------------------- moon phases
+/**
+ * UPSTREAM: `MEAN_SYNODIC_MONTH`, astronomy.ts line 129. The elongation it
+ * searches is {@link moonPhaseDeg}, apparent on both sides per the spec's
+ * moon-phase definition — upstream's `PairLongitude` uses geometric longitudes,
+ * which sit a flat ~40 s off the USNO catalogue.
+ */
+const MEAN_SYNODIC_MONTH = 29.530588;
+const PHASE_NAMES = ['new', 'firstQuarter', 'full', 'lastQuarter'];
+/** UPSTREAM: `QuadInterp`, astronomy.ts ~4528. */
+function quadInterp(tm, dt, fa, fm, fb) {
+    const Q = (fb + fa) / 2 - fm;
+    const R = (fb - fa) / 2;
+    const S = fm;
+    let x;
+    if (Q === 0) {
+        if (R === 0)
+            return null; // horizontal line: no progress possible
+        x = -S / R;
+        if (x < -1 || x > +1)
+            return null;
+    }
+    else {
+        const u = R * R - 4 * Q * S;
+        if (u <= 0)
+            return null;
+        const ru = Math.sqrt(u);
+        const x1 = (-R + ru) / (2 * Q);
+        const x2 = (-R - ru) / (2 * Q);
+        if (-1 <= x1 && x1 <= +1) {
+            if (-1 <= x2 && x2 <= +1)
+                return null;
+            x = x1;
+        }
+        else if (-1 <= x2 && x2 <= +1) {
+            x = x2;
+        }
+        else {
+            return null;
+        }
+    }
+    return { t: tm + x * dt, dfdt: (2 * Q * x + R) / dt };
+}
+/**
+ * UPSTREAM: `Search`, astronomy.ts ~4634 — bisection with quadratic
+ * acceleration for the ascending zero crossing of `f` in `[t1, t2]`. Times are
+ * days since J2000 UT rather than upstream's `AstroTime`.
+ */
+export function search(f, t1, t2, dtToleranceSeconds, iterLimit = MOON_PHASE_ITER_CAP, what = 'moon-phase search') {
+    const dtDays = Math.abs(dtToleranceSeconds * SECOND_DAYS);
+    let f1 = f(t1);
+    let f2 = f(t2);
+    let fmid = NaN;
+    let calcFmid = true;
+    for (let iter = 0;; iter++) {
+        assertReached(iter < iterLimit, what);
+        const tmid = (t1 + t2) / 2;
+        const dt = tmid - t1;
+        if (Math.abs(dt) < dtDays)
+            return tmid;
+        if (calcFmid)
+            fmid = f(tmid);
+        else
+            calcFmid = true;
+        const q = quadInterp(tmid, t2 - tmid, f1, fmid, f2);
+        if (q && q.dfdt !== 0) {
+            const fq = f(q.t);
+            if (Math.abs(fq / q.dfdt) < dtDays)
+                return q.t;
+            const dtGuess = 1.2 * Math.abs(fq / q.dfdt);
+            if (dtGuess < dt / 10) {
+                const tleft = q.t - dtGuess;
+                const tright = q.t + dtGuess;
+                if ((tleft - t1) * (tleft - t2) < 0 && (tright - t1) * (tright - t2) < 0) {
+                    const fleft = f(tleft);
+                    const fright = f(tright);
+                    if (fleft < 0 && fright >= 0) {
+                        f1 = fleft;
+                        f2 = fright;
+                        t1 = tleft;
+                        t2 = tright;
+                        fmid = fq;
+                        calcFmid = false;
+                        continue;
+                    }
+                }
+            }
+        }
+        if (f1 < 0 && fmid >= 0) {
+            t2 = tmid;
+            f2 = fmid;
+            continue;
+        }
+        if (fmid < 0 && f2 >= 0) {
+            t1 = tmid;
+            f1 = fmid;
+            continue;
+        }
+        return null; // no ascending crossing here, or the window is too wide
+    }
+}
+/**
+ * UPSTREAM: `SearchMoonPhase`, astronomy.ts ~5260 — forward search only, which
+ * is all the quarter walk needs. The phase repeats every synodic month, so the
+ * time of the next occurrence is predicted from the current offset and then
+ * bracketed ±1.5 days: the Moon's eccentricity has been seen to move a quarter
+ * more than 0.9 days off the simple prediction.
+ */
+export function searchMoonPhase(targetLonDeg, startUt, limitDays) {
+    const moonOffset = (ut) => angleOffset(moonPhaseDeg(ttDaysFromUt(ut)) - targetLonDeg);
+    const uncertainty = 1.5;
+    let ya = moonOffset(startUt);
+    if (ya > 0)
+        ya -= 360;
+    const estDt = -(MEAN_SYNODIC_MONTH * ya) / 360;
+    const dt1 = estDt - uncertainty;
+    if (dt1 > limitDays)
+        return null;
+    const dt2 = Math.min(limitDays, estDt + uncertainty);
+    return search(moonOffset, startUt + dt1, startUt + dt2, 0.1);
+}
+/**
+ * The four quarter moon phases within the half-open window
+ * `[startUtc, endUtc)`, sorted ascending.
+ *
+ * A phase is the instant the Moon's geocentric ecliptic longitude leads the
+ * Sun's by 0° (new), 90° (first quarter), 180° (full) or 270° (last quarter).
+ */
+export function searchMoonPhases(startUtc, endUtc) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    if (startUtc.getTime() >= endUtc.getTime())
+        return [];
+    const startUt = utDays(startUtc);
+    const endUt = utDays(endUtc);
+    const events = [];
+    // UPSTREAM `SearchMoonQuarter` finds the first quarter strictly after its
+    // argument, so the walk starts a day early: a phase landing exactly on
+    // startUtc belongs to this half-open window.
+    let probeUt = clampUt(startUt - 1);
+    let quarter = (Math.floor(moonPhaseDeg(ttDaysFromUt(probeUt)) / 90) + 1) % 4;
+    for (;;) {
+        const ut = searchMoonPhase(90 * quarter, probeUt, 10);
+        assertReached(ut !== null, 'moon quarter search');
+        if (ut === null)
+            break;
+        const q = quantizedUt(ut); // judge the half-open bounds on the reported instant, not the raw root
+        if (q >= endUt)
+            break;
+        if (q >= startUt)
+            events.push({ time: dateFromUt(ut), phase: PHASE_NAMES[quarter] });
+        // UPSTREAM `NextMoonQuarter`: skip 6 days, under the smallest observed
+        // quarter-to-quarter interval, so the next search cannot re-find this one.
+        probeUt = ut + 6;
+        quarter = (quarter + 1) % 4;
+    }
+    return events;
+}

package/dist/illumination.d.ts

@@ -0,0 +1,32 @@
+/** Moon illumination at an instant. `phase` is 0 at new moon, 0.5 at full. */
+export interface MoonIllumination {
+    fraction: number;
+    phaseAngleDeg: number;
+    phase: number;
+    waxing: boolean;
+}
+/**
+ * INTERNAL: the Moon's apparent ecliptic longitude ahead of the Sun's, [0, 360)
+ * — 0 at new moon, 180 at full. The single definition of lunar phase in this
+ * package: `moonIllumination.phase` is this over 360, and `searchMoonPhases`
+ * roots this against 0/90/180/270.
+ *
+ * UPSTREAM: `MoonPhase` = `PairLongitude(Moon, Sun)` (astronomy.ts ~5221,
+ * ~4831) takes both longitudes from `GeoVector(body, t, aberration=false)`,
+ * i.e. geometric directions. The spec's moon-phase definition is **apparent**
+ * on both sides, matching the USNO/almanac definition of syzygy, so the Sun
+ * here is the aberrated vector `sunPosition` returns. The Moon needs no such
+ * change: aberration follows the observer's velocity *relative to the body* —
+ * 30 km/s for the Sun (20.5″) against 1 km/s for the Moon (0.7″). That 20.5″ is
+ * 40 s of elongation rate, and upstream's geometric convention sits exactly
+ * that far off the USNO catalogue.
+ */
+export declare function moonPhaseDeg(tt: number): number;
+/** INTERNAL: moon illumination for a TT instant. See {@link moonIllumination}. */
+export declare function moonIlluminationAtTT(tt: number): MoonIllumination;
+/**
+ * Moon illumination at a given instant: the fraction of the visible disc lit
+ * by the Sun, the phase angle it derives from (0 = full, 180 = new), and the
+ * phase (0 = new, 0.5 = full, `waxing` = phase < 0.5).
+ */
+export declare function moonIllumination(time: Date): MoonIllumination;

package/dist/illumination.js

@@ -0,0 +1,88 @@
+// L1 moon illumination: phase angle / illuminated fraction (upstream
+// `Illumination`, Body.Moon branch, astronomy.ts line ~5048) and phase
+// (upstream `MoonPhase` = `PairLongitude(Moon, Sun)` / 360, astronomy.ts line
+// ~5221), plus the Moon–Sun elongation both `phase` and the L3 phase search
+// read — one definition, one implementation.
+//
+// Translated from the cosinekitty/astronomy upstream, pinned sha
+// 865d3da7d8112bbc7911238052c6af4aaf877181, source/js/astronomy.ts.
+//
+// INTERNAL: not part of the curated public API (see index.ts).
+import { assertSupported } from './types.js';
+import { ttDays } from './time.js';
+import { DEG2RAD, PrecessDirection, RAD2DEG, earthTilt, eclipticToEquatorial, gyration } from './nutation.js';
+import { moonGeoVectorEqj } from './moon.js';
+import { earthHelioVector, sunGeoVectorEqj } from './sun.js';
+/** UPSTREAM: `AngleBetween`, astronomy.ts lines 256-273 — angle between two vectors, [0, 180]. */
+function angleBetweenDeg(a, b) {
+    const aa = a.x * a.x + a.y * a.y + a.z * a.z;
+    const bb = b.x * b.x + b.y * b.y + b.z * b.z;
+    const dot = (a.x * b.x + a.y * b.y + a.z * b.z) / Math.sqrt(aa * bb);
+    if (dot <= -1)
+        return 180;
+    if (dot >= 1)
+        return 0;
+    return RAD2DEG * Math.acos(dot);
+}
+/**
+ * UPSTREAM: the `elon` half of `Ecliptic()` (astronomy.ts lines 3013-3030),
+ * applied to a J2000 mean-equator (EQJ) vector: `gyration(..., From2000)`
+ * reproduces `Ecliptic`'s precession+nutation-to-EQD step exactly, and
+ * `eclipticToEquatorial` called with the negated obliquity performs the same
+ * rotation as upstream's `RotateEquatorialToEcliptic` (its inverse).
+ */
+function eclipticLonOfDateDeg(eqj, tt) {
+    const eqd = gyration(eqj, tt, PrecessDirection.From2000);
+    const tobl = earthTilt(tt).tobl;
+    const ecl = eclipticToEquatorial(-tobl, eqd);
+    if (ecl.x === 0 && ecl.y === 0)
+        return 0;
+    let elon = RAD2DEG * Math.atan2(ecl.y, ecl.x);
+    if (elon < 0)
+        elon += 360;
+    return elon;
+}
+/** UPSTREAM: `NormalizeLongitude`, astronomy.ts lines 4735-4739. */
+function normalizeLongitude(lon) {
+    return ((lon % 360) + 360) % 360;
+}
+/**
+ * INTERNAL: the Moon's apparent ecliptic longitude ahead of the Sun's, [0, 360)
+ * — 0 at new moon, 180 at full. The single definition of lunar phase in this
+ * package: `moonIllumination.phase` is this over 360, and `searchMoonPhases`
+ * roots this against 0/90/180/270.
+ *
+ * UPSTREAM: `MoonPhase` = `PairLongitude(Moon, Sun)` (astronomy.ts ~5221,
+ * ~4831) takes both longitudes from `GeoVector(body, t, aberration=false)`,
+ * i.e. geometric directions. The spec's moon-phase definition is **apparent**
+ * on both sides, matching the USNO/almanac definition of syzygy, so the Sun
+ * here is the aberrated vector `sunPosition` returns. The Moon needs no such
+ * change: aberration follows the observer's velocity *relative to the body* —
+ * 30 km/s for the Sun (20.5″) against 1 km/s for the Moon (0.7″). That 20.5″ is
+ * 40 s of elongation rate, and upstream's geometric convention sits exactly
+ * that far off the USNO catalogue.
+ */
+export function moonPhaseDeg(tt) {
+    return normalizeLongitude(eclipticLonOfDateDeg(moonGeoVectorEqj(tt), tt) - eclipticLonOfDateDeg(sunGeoVectorEqj(tt), tt));
+}
+/** INTERNAL: moon illumination for a TT instant. See {@link moonIllumination}. */
+export function moonIlluminationAtTT(tt) {
+    // UPSTREAM `Illumination`, Body.Moon branch: gc = GeoMoon(time) (no
+    // backdating/aberration — see moonGeoVectorEqj); hc = earth + gc.
+    const gc = moonGeoVectorEqj(tt);
+    const earth = earthHelioVector(tt);
+    const hc = { x: earth.x + gc.x, y: earth.y + gc.y, z: earth.z + gc.z };
+    const phaseAngleDeg = angleBetweenDeg(gc, hc);
+    const fraction = (1 + Math.cos(DEG2RAD * phaseAngleDeg)) / 2;
+    const phase = moonPhaseDeg(tt) / 360;
+    return { fraction, phaseAngleDeg, phase, waxing: phase < 0.5 };
+}
+/**
+ * Moon illumination at a given instant: the fraction of the visible disc lit
+ * by the Sun, the phase angle it derives from (0 = full, 180 = new), and the
+ * phase (0 = new, 0.5 = full, `waxing` = phase < 0.5).
+ */
+export function moonIllumination(time) {
+    assertSupported(time);
+    return moonIlluminationAtTT(ttDays(time));
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export type { Observer } from './types.js';
+export { AlmanacOutOfRangeError } from './types.js';
+export type { SunPosition, MoonPosition } from './positions.js';
+export { sunPosition, moonPosition } from './positions.js';
+export type { AltAz } from './transforms.js';
+export { sunAltAz, moonAltAz } from './transforms.js';
+export type { MoonIllumination } from './illumination.js';
+export { moonIllumination } from './illumination.js';
+export type { SunEvent, SunEventKind, MoonEvent, MoonEventKind, MoonPhaseEvent, MoonPhaseName } from './events.js';
+export { sunEvents, moonEvents, searchMoonPhases } from './events.js';
+export type { LunarEclipse, LunarEclipseVisibility } from './eclipse.js';
+export { nextLunarEclipse, lunarEclipseVisibility } from './eclipse.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { AlmanacOutOfRangeError } from './types.js';
+export { sunPosition, moonPosition } from './positions.js';
+export { sunAltAz, moonAltAz } from './transforms.js';
+export { moonIllumination } from './illumination.js';
+export { sunEvents, moonEvents, searchMoonPhases } from './events.js';
+export { nextLunarEclipse, lunarEclipseVisibility } from './eclipse.js';

package/dist/moon.d.ts

@@ -0,0 +1,38 @@
+import { Vec3 } from './nutation.js';
+/** Geocentric ecliptic-of-date position of the Moon; angles in radians. */
+export interface MoonEcliptic {
+    geoEclipLon: number;
+    geoEclipLat: number;
+    distanceAu: number;
+}
+/**
+ * UPSTREAM: `CalcMoon`, astronomy.ts lines 1494-1793 — the full MOON2 series.
+ * Returns ecliptic longitude/latitude of date (radians) and distance (AU).
+ */
+export declare function calcMoon(tt: number): MoonEcliptic;
+/**
+ * UPSTREAM: `GeoMoon`, astronomy.ts lines 3049-3068, followed by the
+ * `gyration(..., From2000)` that `Equator(ofdate=true)` (line 2803) applies.
+ *
+ * `GeoVector(Body.Moon, ...)` returns `GeoMoon` unchanged whatever the
+ * `aberration` flag: the Moon shares the Earth's orbital velocity, so its
+ * geocentric aberration and its 1.3-second light time both fall far below the
+ * precision of this lunar theory.
+ *
+ * The precession round trip (into J2000, then back out inside `gyration`) is
+ * upstream's own composition and is kept so the Swift port can be a
+ * line-for-line translation.
+ *
+ * @returns geocentric position in AU, J2000 mean equator (EQJ) — the `mpos2`
+ * intermediate below, exported for the L2 topocentric path (Task 11), which
+ * needs the body vector in the same EQJ frame as the observer's geocentric
+ * position before subtracting the two.
+ */
+export declare function moonGeoVectorEqj(tt: number): Vec3;
+/**
+ * UPSTREAM: `GeoMoon` (astronomy.ts 3049-3068) followed by the
+ * `gyration(..., From2000)` that `Equator(ofdate=true)` (line 2803) applies.
+ *
+ * @returns geocentric position in AU, true equator & equinox of date.
+ */
+export declare function moonGeoVector(tt: number): Vec3;