@openwaters/almanac 0.1.0 → 0.2.1

package/README.md

@@ -15,11 +15,55 @@ Supported interval: 1950-01-01T00:00Z ≤ t < 2101-01-01T00:00Z; results outside
 raise a typed error. All instants are UT1-accurate, not civil-UTC-accurate in the far
 future — see the design spec's Conventions section for what that means and why.
 
-Design: [`docs/superpowers/specs/2026-08-28-almanac-v1-design.md`](docs/superpowers/specs/2026-08-28-almanac-v1-design.md)
+- Design: [`docs/superpowers/specs/2026-08-28-almanac-v1-design.md`](docs/superpowers/specs/2026-08-28-almanac-v1-design.md)
+- Roadmap: [`docs/ROADMAP.md`](docs/ROADMAP.md) — what ships next, and what will not.
+- Landing page: [openwaters.io/sky](https://openwaters.io/sky) — the library running live in a browser.
 
 Algorithms translated from [Astronomy Engine](https://github.com/cosinekitty/astronomy)
 (MIT, Don Cross) — see [NOTICE](NOTICE). MIT licensed.
 
+## Performance
+
+Almanac includes a shared performance harness for both ports: **15 workloads**
+cover positions, a 228-hour sky track, short/year/polar event windows, full-range
+moon phases, and next/previous/range eclipse searches, including empty windows.
+
+The v0.2.1 optimizations reuse Moon and shadow geometry, flatten scratch arrays,
+and refine altitude crossings with fewer position evaluations. In the
+[hosted CI comparison](https://github.com/openwatersio/almanac/actions/runs/34119038860),
+median query time fell relative to the v0.2.0 astronomy code:
+
+| Workload | TypeScript: less time | Swift: less time |
+| --- | ---: | ---: |
+| Moon positions / 1,024 hours | 29.8% | 22.1% |
+| Sky track / 228 hours | 40.0% | 42.4% |
+| Sun events / 228 hours | 39.3% | 40.2% |
+| Moon events / 228 hours | 39.1% | 35.1% |
+| Previous lunar eclipse | 26.0% | 36.6% |
+| Lunar eclipses / 1950–2100 | 26.4% | 23.4% |
+
+TypeScript was measured on Ubuntu with Node 22; Swift used release builds on
+macOS 15. Each comparison builds both revisions with the same harness and
+toolchain, then takes seven interleaved process pairs with 300 ms warmup per
+process. Build and startup time are excluded. Timings vary by machine; the shared
+correctness fixtures and parity tolerances remain the accuracy gates.
+
+Reproduce the comparison locally from the repository root (Node 22+ and Swift
+5.9+):
+
+```bash
+npm ci --prefix typescript
+node benchmarks/run.mjs --base v0.2.0
+```
+
+CI runs the harness on code changes and fails on **median regressions over 20%**.
+Results include timing tables, raw samples, checksums, and revision/toolchain
+metadata. See [the harness guide](CONTRIBUTING.md#performance) for choosing a
+baseline, running one port, and inspecting reports.
+
+Event searches scale with window length. Run a full 151-year sweep in a worker or
+background task; use shorter windows for interactive queries.
+
 ## Usage
 
 ### TypeScript
@@ -47,7 +91,7 @@ for (const { kind, time } of sunEvents(today, tomorrow, observer)) {
 ### Swift
 
 ```swift
-.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.1.0")
+.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.2.1")
 ```
 
 ```swift
@@ -67,9 +111,21 @@ for event in try sunEvents(from: today, to: tomorrow, observer: observer) {
 }
 ```
 
-### Performance
+### Eclipse searches
+
+Search for a previous eclipse or all eclipses in a time window:
+
+```ts
+import { previousLunarEclipse, lunarEclipses } from '@openwaters/almanac';
+const last = previousLunarEclipse(new Date());
+const eclipses = lunarEclipses(new Date('2026-08-24T00:00:00Z'), new Date('2026-09-02T12:00:00Z'));
+```
+
+```swift
+let last = try previousLunarEclipse(before: Date())
+let eclipses = try lunarEclipses(from: today, to: tomorrow)
+```
 
-Event searches (`sunEvents`/`moonEvents`) are linear in window length. The full
-151-year supported interval is a measured cost, not a guess: ~68 s in TypeScript,
-~44 s in Swift release builds. Chunk or worker a full-range call rather than
-running it inline.
+Ranges include peaks at the start and exclude peaks at the end. Contacts may
+extend outside the range. Previous/next searches skip peaks within 100 ms of the
+anchor. Search results are global; apply `lunarEclipseVisibility` for an observer.

package/dist/eclipse.d.ts

@@ -52,6 +52,18 @@ export interface LunarEclipseVisibility {
  *      interval, or if the next eclipse falls at or past the end of it.
  */
 export declare function nextLunarEclipse(after: Date): LunarEclipse;
+/**
+ * The last lunar eclipse whose peak falls strictly before `before`, skipping
+ * peaks within 100 ms of it, just as `nextLunarEclipse` does on the other side.
+ *
+ * @throws {AlmanacOutOfRangeError} if `before` is outside the supported
+ *      interval, or if the previous eclipse falls before its beginning.
+ */
+export declare function previousLunarEclipse(before: Date): LunarEclipse;
+/** Lunar eclipses with peaks in `[startUtc, endUtc)`, sorted ascending.
+ *  Contacts may fall outside the window. Visibility is observer-dependent;
+ *  use `lunarEclipseVisibility` on each result to check it. */
+export declare function lunarEclipses(startUtc: Date, endUtc: Date): LunarEclipse[];
 /**
  * Whether an observer can see each phase of a lunar eclipse — purely geometric:
  * the Moon's unrefracted topocentric centre must be above the horizon. A lunar

package/dist/eclipse.js

@@ -17,7 +17,7 @@
 //     result.
 //   - upstream reports semi-durations in minutes; the spec's public shape is
 //     the contact instants themselves, and `obscuration` is not in it.
-import { assertObserver, assertSupported, AlmanacOutOfRangeError, SUPPORTED_MAX } from './types.js';
+import { assertObserver, assertSupported, assertSupportedWindowEnd, AlmanacOutOfRangeError, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
 import { dateFromUt, ttDaysFromUt, utDays } from './time.js';
 import { KM_PER_AU, RAD2DEG } from './nutation.js';
 import { calcMoon, moonGeoVectorEqj } from './moon.js';
@@ -44,25 +44,13 @@ const SHADOW_TOL_SECONDS = 1;
 /** UPSTREAM: `Search`'s default `iter_limit`. */
 const SHADOW_ITER_CAP = 20;
 /**
- * How close a candidate peak may sit to `after` and still be judged the same
- * eclipse, milliseconds.
+ * Peaks within 100 ms of a next/previous search anchor count as the same
+ * eclipse. The fixed full-moon seed below removes within-runtime drift; keep
+ * the band for peaks saved by older versions or computed on another runtime.
  *
- * A peak is only reproducible to about a millisecond: the full-moon seed comes
- * from a root finder with a 0.1 s tolerance, and the ±0.03 d peak-shadow window
- * built around it therefore differs slightly between two calls that reach the
- * same eclipse from different starting times, which moves the interpolated root
- * by an observed ≤1 ms. A caller walking the catalog by feeding each peak back
- * in would otherwise re-find that eclipse whenever the second evaluation landed
- * a millisecond later.
- *
- * The band cuts both ways, and both are bounded:
- *   - it can never swallow a real eclipse — consecutive lunar eclipses are
- *     never less than a month apart, 25 million times this window;
- *   - it *can* skip an eclipse the caller genuinely wanted: `after` set inside
- *     the 100 ms before a peak returns the eclipse after it, not that one.
- *     That is the accepted cost, and 100 ms is its ceiling — against a peak
- *     model that agrees with the Espenak catalog to ~15 s, a caller cannot have
- *     meant a boundary that sharp.
+ * This can skip a wanted peak when the anchor is within 100 ms of it, but
+ * cannot skip a distinct eclipse (the catalog's minimum gap is 29 days).
+ * Range searches use exact half-open bounds without this band.
  */
 const SAME_ECLIPSE_MS = 100;
 /** UPSTREAM: `CalcShadow`, astronomy.ts ~8458. */
@@ -102,7 +90,14 @@ function earthShadowSlope(ut) {
  * time derivative.
  */
 function peakEarthShadow(centerUt) {
-    const ut = search(earthShadowSlope, centerUt - PEAK_WINDOW_DAYS, centerUt + PEAK_WINDOW_DAYS, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'peak earth shadow');
+    // Use the same full-moon seed regardless of search direction or window.
+    // Otherwise a ~1 ms root shift can lose/duplicate a peak when a caller
+    // splits a range at a previously returned peak. Only unpruned moons pay
+    // for this second phase search; its start is a fixed whole UT day.
+    const fullmoon = searchMoonPhase(180, Math.floor(centerUt) - 1, 4);
+    if (fullmoon === null)
+        throw new Error('almanac internal: cannot refine full moon');
+    const ut = search(earthShadowSlope, fullmoon - PEAK_WINDOW_DAYS, fullmoon + PEAK_WINDOW_DAYS, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'peak earth shadow');
     if (ut === null)
         throw new Error('almanac internal: failed to find peak Earth shadow time');
     return earthShadow(ut);
@@ -113,10 +108,13 @@ function peakEarthShadow(centerUt) {
  * then averages the two halves, so the contacts this package reports are
  * symmetric about the peak by construction (as upstream's are).
  */
-function shadowSemiDurationMinutes(centerUt, radiusLimitKm, windowMinutes) {
+function shadowSemiDurationMinutes(shadow, radiusLimitKm, windowMinutes) {
+    const centerUt = shadow.ut;
+    // Both contact searches sample the peak, whose geometry is already known.
+    const distance = (ut) => ut === centerUt ? shadow.r : earthShadow(ut).r;
     const window = windowMinutes / MINUTES_PER_DAY;
-    const t1 = search(ut => -(earthShadow(ut).r - radiusLimitKm), centerUt - window, centerUt, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'shadow semiduration (before)');
-    const t2 = search(ut => +(earthShadow(ut).r - radiusLimitKm), centerUt, centerUt + window, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'shadow semiduration (after)');
+    const t1 = search(ut => -(distance(ut) - radiusLimitKm), centerUt - window, centerUt, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'shadow semiduration (before)');
+    const t2 = search(ut => +(distance(ut) - radiusLimitKm), centerUt, centerUt + window, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'shadow semiduration (after)');
     if (t1 === null || t2 === null)
         throw new Error('almanac internal: failed to find shadow semiduration');
     return (t2 - t1) * (MINUTES_PER_DAY / 2.0); // convert days to minutes and average the semi-durations
@@ -138,17 +136,57 @@ function moonEclipticLatitudeDeg(ut) {
  *      interval, or if the next eclipse falls at or past the end of it.
  */
 export function nextLunarEclipse(after) {
-    assertSupported(after);
-    const startUt = utDays(after);
-    let fmUt = startUt;
-    while (fmUt <= startUt + SCAN_LIMIT_DAYS) {
-        // Search for the next full moon. Any eclipse will be near it.
-        const fullmoon = searchMoonPhase(180, fmUt, 40);
+    return nearestLunarEclipse(after, 1);
+}
+/**
+ * The last lunar eclipse whose peak falls strictly before `before`, skipping
+ * peaks within 100 ms of it, just as `nextLunarEclipse` does on the other side.
+ *
+ * @throws {AlmanacOutOfRangeError} if `before` is outside the supported
+ *      interval, or if the previous eclipse falls before its beginning.
+ */
+export function previousLunarEclipse(before) {
+    return nearestLunarEclipse(before, -1);
+}
+/** Lunar eclipses with peaks in `[startUtc, endUtc)`, sorted ascending.
+ *  Contacts may fall outside the window. Visibility is observer-dependent;
+ *  use `lunarEclipseVisibility` on each result to check it. */
+export function lunarEclipses(startUtc, endUtc) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    return scanLunarEclipses(startUtc.getTime(), endUtc.getTime(), 1, false);
+}
+function nearestLunarEclipse(anchor, direction) {
+    assertSupported(anchor);
+    const ms = anchor.getTime();
+    const startMs = direction > 0 ? ms + SAME_ECLIPSE_MS + 1 : Math.max(SUPPORTED_MIN, ms - SCAN_LIMIT_DAYS * 86400000);
+    const endMs = direction > 0 ? Math.min(SUPPORTED_MAX, ms + SCAN_LIMIT_DAYS * 86400000) : ms - SAME_ECLIPSE_MS;
+    const found = scanLunarEclipses(startMs, endMs, direction, true);
+    if (found.length)
+        return found[0];
+    if (direction > 0 ? endMs === SUPPORTED_MAX : startMs === SUPPORTED_MIN)
+        throw new AlmanacOutOfRangeError();
+    // The longest catalog gap is 178 days: exhausting 730 inside the supported
+    // interval is a broken shadow model, not a normal out-of-range result.
+    throw new Error(`almanac internal: no lunar eclipse within ${SCAN_LIMIT_DAYS} days of ${anchor.toISOString()}`);
+}
+function scanLunarEclipses(startMs, endMs, direction, firstOnly) {
+    const found = [];
+    if (startMs >= endMs)
+        return found;
+    // Peak and full moon differ. Include the entire peak-search margin at
+    // both ends, then apply the caller's bounds to the reported peak below.
+    const startUt = utDays(new Date(startMs)) - PEAK_WINDOW_DAYS;
+    const endUt = utDays(new Date(endMs)) + PEAK_WINDOW_DAYS;
+    let fmUt = direction > 0 ? startUt : endUt;
+    const limitUt = direction > 0 ? endUt : startUt;
+    while (direction * (limitUt - fmUt) > 0) {
+        const fullmoon = searchMoonPhase(180, fmUt, direction * Math.min(40, Math.abs(limitUt - fmUt)));
         if (fullmoon === null)
-            throw new Error('almanac internal: cannot find full moon');
+            break;
         // UPSTREAM `SearchLunarEclipse`: step past this full moon before the
         // next probe, so the same one cannot be found twice.
-        fmUt = fullmoon + 10;
+        fmUt = fullmoon + direction * 10;
         // Pruning: if the full Moon's ecliptic latitude is too large, a lunar
         // eclipse is not possible. Avoid needless work searching for the
         // minimum moon distance.
@@ -159,20 +197,14 @@ export function nextLunarEclipse(after) {
         const shadow = peakEarthShadow(fullmoon);
         if (shadow.r >= shadow.p + MOON_MEAN_RADIUS_KM)
             continue; // not even penumbral
-        // A full moon before `after` can still carry the eclipse the caller
-        // already has; the spec's contract is strictly-later peaks.
         const peak = dateFromUt(shadow.ut);
-        if (peak.getTime() <= after.getTime() + SAME_ECLIPSE_MS)
+        if (peak.getTime() < startMs || peak.getTime() >= endMs)
             continue;
-        if (peak.getTime() >= SUPPORTED_MAX)
-            throw new AlmanacOutOfRangeError();
-        return buildEclipse(shadow, peak);
+        found.push(buildEclipse(shadow, peak));
+        if (firstOnly)
+            break;
     }
-    // Not an AlmanacOutOfRangeError: the interval is fine, the sky is not. The
-    // longest real gap over 1950-2100 is 178 days, so exhausting 730 means the
-    // shadow model is broken — an internal invariant, like every other
-    // `almanac internal:` throw in this package.
-    throw new Error(`almanac internal: no lunar eclipse within ${SCAN_LIMIT_DAYS} days of ${after.toISOString()}`);
+    return found;
 }
 /** UPSTREAM: the classification and semi-duration block of `SearchLunarEclipse`, astronomy.ts ~8730-8755. */
 function buildEclipse(shadow, peak) {
@@ -180,15 +212,15 @@ function buildEclipse(shadow, peak) {
     let kind = 'penumbral';
     let sdTotal = 0.0;
     let sdPartial = 0.0;
-    const sdPenum = shadowSemiDurationMinutes(shadow.ut, shadow.p + MOON_MEAN_RADIUS_KM, PENUMBRAL_WINDOW_MINUTES);
+    const sdPenum = shadowSemiDurationMinutes(shadow, shadow.p + MOON_MEAN_RADIUS_KM, PENUMBRAL_WINDOW_MINUTES);
     if (shadow.r < shadow.k + MOON_MEAN_RADIUS_KM) {
         // This is at least a partial eclipse.
         kind = 'partial';
-        sdPartial = shadowSemiDurationMinutes(shadow.ut, shadow.k + MOON_MEAN_RADIUS_KM, sdPenum);
+        sdPartial = shadowSemiDurationMinutes(shadow, shadow.k + MOON_MEAN_RADIUS_KM, sdPenum);
         if (shadow.r + MOON_MEAN_RADIUS_KM < shadow.k) {
             // This is a total eclipse.
             kind = 'total';
-            sdTotal = shadowSemiDurationMinutes(shadow.ut, shadow.k - MOON_MEAN_RADIUS_KM, sdPartial);
+            sdTotal = shadowSemiDurationMinutes(shadow, shadow.k - MOON_MEAN_RADIUS_KM, sdPartial);
         }
     }
     // Fraction of the Moon's diameter immersed in each shadow. Shadow radii,

package/dist/events.d.ts

@@ -64,8 +64,8 @@ export declare function moonEvents(startUtc: Date, endUtc: Date, observer: Obser
  */
 export declare function search(f: (ut: number) => number, t1: number, t2: number, dtToleranceSeconds: number, iterLimit?: number, what?: string): number | null;
 /**
- * UPSTREAM: `SearchMoonPhase`, astronomy.ts ~5260 — forward search only, which
- * is all the quarter walk needs. The phase repeats every synodic month, so the
+ * UPSTREAM: `SearchMoonPhase`, astronomy.ts ~5260 — a negative limit searches
+ * backward. 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.

package/dist/events.js

@@ -215,13 +215,25 @@ function refineExtremum(sample, centreUt, wantMax, halfWidthDays, afterUt) {
     return score(s1) > score(s2) ? s1 : s2;
 }
 /**
- * Bisection for the single crossing of `level` on the monotonic segment
- * between two consecutive extrema.
+ * Quadratically accelerated search for the single crossing of `level` on a
+ * monotonic segment, with bisection if the estimate cannot be verified.
  */
 function bisectCrossing(sample, level, s0, s1) {
     let a = s0.ut;
     let b = s1.ut;
-    let belowAtA = offsetDeg(s0, level) < 0;
+    const belowAtA = offsetDeg(s0, level) < 0;
+    // Reuse the phase search's quadratic acceleration, normalized to an
+    // ascending crossing. Endpoint geometry has already been evaluated.
+    const f = (ut) => (belowAtA ? 1 : -1) * offsetDeg(ut === s0.ut ? s0 : ut === s1.ut ? s1 : sample(ut), level);
+    const root = search(f, a, b, 0.25, BISECTION_CAP, 'altitude crossing');
+    if (root !== null) {
+        // A derivative-based estimate alone does not establish a time bound.
+        // Accept only a verified half-second bracket, including near grazes.
+        const left = Math.max(a, root - TIME_TOL_DAYS / 4);
+        const right = Math.min(b, root + TIME_TOL_DAYS / 4);
+        if (f(left) < 0 && f(right) >= 0)
+            return (left + right) / 2;
+    }
     for (let i = 0; i < BISECTION_CAP; i++) {
         if (b - a < TIME_TOL_DAYS)
             return (a + b) / 2;
@@ -266,12 +278,28 @@ function searchAltitudeEvents(sample, levels, transitKind, startUt, endUt, haRat
         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);
+        // Earlier extrema still establish the chain, but their crossings cannot be emitted.
+        if (quantizedUt(s1.ut) >= startUt) {
+            let crossingSample = sample;
+            if (levels.length > 1) {
+                // Twilight levels share midpoint probes; retain them only for this segment.
+                const samples = new Map();
+                crossingSample = (ut) => {
+                    const previous = samples.get(ut);
+                    if (previous)
+                        return previous;
+                    const current = sample(ut);
+                    samples.set(ut, current);
+                    return current;
+                };
+            }
+            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(crossingSample, spec.level, s0, s1), g1 > 0 ? spec.rising : spec.falling);
+            }
         }
         if (nextIsMax && transitKind !== null && !atRangeEnd)
             emit(nextEst, transitKind);
@@ -390,8 +418,10 @@ export function search(f, t1, t2, dtToleranceSeconds, iterLimit = MOON_PHASE_ITE
         assertReached(iter < iterLimit, what);
         const tmid = (t1 + t2) / 2;
         const dt = tmid - t1;
+        // A caller may clip the initial bracket to a short range. Small
+        // width alone does not prove that it contains an ascending root.
         if (Math.abs(dt) < dtDays)
-            return tmid;
+            return f1 <= 0 && f2 >= 0 ? tmid : null;
         if (calcFmid)
             fmid = f(tmid);
         else
@@ -434,8 +464,8 @@ export function search(f, t1, t2, dtToleranceSeconds, iterLimit = MOON_PHASE_ITE
     }
 }
 /**
- * UPSTREAM: `SearchMoonPhase`, astronomy.ts ~5260 — forward search only, which
- * is all the quarter walk needs. The phase repeats every synodic month, so the
+ * UPSTREAM: `SearchMoonPhase`, astronomy.ts ~5260 — a negative limit searches
+ * backward. 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.
@@ -444,13 +474,25 @@ 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);
+    let dt1, dt2;
+    if (limitDays < 0) {
+        if (ya < 0)
+            ya += 360;
+        const estDt = -(MEAN_SYNODIC_MONTH * ya) / 360;
+        dt2 = estDt + uncertainty;
+        if (dt2 < limitDays)
+            return null;
+        dt1 = Math.max(limitDays, estDt - uncertainty);
+    }
+    else {
+        if (ya > 0)
+            ya -= 360;
+        const estDt = -(MEAN_SYNODIC_MONTH * ya) / 360;
+        dt1 = estDt - uncertainty;
+        if (dt1 > limitDays)
+            return null;
+        dt2 = Math.min(limitDays, estDt + uncertainty);
+    }
     return search(moonOffset, startUt + dt1, startUt + dt2, 0.1);
 }
 /**

package/dist/illumination.js

@@ -63,7 +63,10 @@ function normalizeLongitude(lon) {
  * that far off the USNO catalogue.
  */
 export function moonPhaseDeg(tt) {
-    return normalizeLongitude(eclipticLonOfDateDeg(moonGeoVectorEqj(tt), tt) - eclipticLonOfDateDeg(sunGeoVectorEqj(tt), tt));
+    return moonPhaseFromVector(tt, moonGeoVectorEqj(tt));
+}
+function moonPhaseFromVector(tt, moon) {
+    return normalizeLongitude(eclipticLonOfDateDeg(moon, tt) - eclipticLonOfDateDeg(sunGeoVectorEqj(tt), tt));
 }
 /** INTERNAL: moon illumination for a TT instant. See {@link moonIllumination}. */
 export function moonIlluminationAtTT(tt) {
@@ -74,7 +77,7 @@ export function moonIlluminationAtTT(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;
+    const phase = moonPhaseFromVector(tt, gc) / 360;
     return { fraction, phaseAngleDeg, phase, waxing: phase < 0.5 };
 }
 /**

package/dist/index.d.ts

@@ -9,4 +9,4 @@ 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';
+export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';

package/dist/index.js

@@ -3,4 +3,4 @@ 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';
+export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';

package/dist/moon.js

@@ -14,43 +14,21 @@ import { ARC, EARTH_EQUATORIAL_RADIUS_AU, PI2, PrecessDirection, eclipticToEquat
  */
 export function calcMoon(tt) {
     const T = tt / 36525;
-    function DeclareArray1(xmin, xmax) {
-        const array = [];
-        let i;
-        for (i = 0; i <= xmax - xmin; ++i) {
-            array.push(0);
-        }
-        return { min: xmin, array: array };
-    }
-    function DeclareArray2(xmin, xmax, ymin, ymax) {
-        const array = [];
-        for (let i = 0; i <= xmax - xmin; ++i) {
-            array.push(DeclareArray1(ymin, ymax));
-        }
-        return { min: xmin, array: array };
-    }
-    function ArrayGet2(a, x, y) {
-        const m = a.array[x - a.min];
-        return m.array[y - m.min];
-    }
-    function ArraySet2(a, x, y, v) {
-        const m = a.array[x - a.min];
-        m.array[y - m.min] = v;
-    }
     let S, MAX, ARG, FAC, I, J, T2, DGAM, DLAM, N, GAM1C, SINPI, L0, L, LS, F, D, DL0, DL, DLS, DF, DD, DS;
-    let coArray = DeclareArray2(-6, 6, 1, 4);
-    let siArray = DeclareArray2(-6, 6, 1, 4);
+    // CO/SI tables: x in -6...6, y in 1...4, stored in flat 13x4 arrays.
+    const coArray = new Array(52).fill(0);
+    const siArray = new Array(52).fill(0);
     function CO(x, y) {
-        return ArrayGet2(coArray, x, y);
+        return coArray[(x + 6) * 4 + y - 1];
     }
     function SI(x, y) {
-        return ArrayGet2(siArray, x, y);
+        return siArray[(x + 6) * 4 + y - 1];
     }
     function SetCO(x, y, v) {
-        return ArraySet2(coArray, x, y, v);
+        coArray[(x + 6) * 4 + y - 1] = v;
     }
     function SetSI(x, y, v) {
-        return ArraySet2(siArray, x, y, v);
+        siArray[(x + 6) * 4 + y - 1] = v;
     }
     function AddThe(c1, s1, c2, s2, func) {
         func(c1 * c2 - s1 * s2, s1 * c2 + c1 * s2);

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Offline sun & moon engine: positions, rise/set, moon phase, lunar eclipses.",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/openwatersio/almanac.git", "directory": "typescript" },
+  "homepage": "https://openwaters.io/sky",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",