@openwaters/almanac 0.0.0-bootstrap

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open Waters
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,32 @@
+Almanac contains algorithms translated from Astronomy Engine
+(https://github.com/cosinekitty/astronomy), copyright (c) 2019+ Don Cross,
+released under the MIT License.
+
+Astronomy Engine's lunar theory derives from "Astronomy on the Personal
+Computer" by Oliver Montenbruck and Thomas Pfleger; its solar theory from
+the VSOP87 model by Bretagnon and Francou.
+
+Translation is pinned to Astronomy Engine commit
+865d3da7d8112bbc7911238052c6af4aaf877181. The complete upstream license:
+
+    MIT License
+
+    Copyright (c) 2019-2025 Don Cross <cosinekitty@gmail.com>
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# Almanac
+
+Offline sun & moon engine for the Salish Sea and everywhere else — positions,
+rise/set/twilight, moon phase, and lunar eclipses (solar planned), computed from pure
+geometry with zero network and zero runtime data files.
+
+Twin implementations, one behavior:
+
+- `swift/` — SwiftPM package `Almanac`
+- `typescript/` — npm `@openwaters/almanac`
+- `fixtures/` — the shared test corpus (JPL Horizons, USNO, Espenak) both suites
+  must pass; the contract that keeps the ports identical
+
+Supported interval: 1950-01-01T00:00Z ≤ t < 2101-01-01T00:00Z; results outside it
+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)
+
+Algorithms translated from [Astronomy Engine](https://github.com/cosinekitty/astronomy)
+(MIT, Don Cross) — see [NOTICE](NOTICE). MIT licensed.
+
+## Usage
+
+### TypeScript
+
+```bash
+npm install @openwaters/almanac
+```
+
+```ts
+import { nextLunarEclipse, lunarEclipseVisibility, sunEvents } from '@openwaters/almanac';
+
+const observer = { latitudeDeg: 48.5, longitudeDeg: -123.0 };
+
+const eclipse = nextLunarEclipse(new Date());
+const visibility = lunarEclipseVisibility(eclipse, observer);
+console.log(eclipse.kind, eclipse.peak, visibility.visibleAtPeak);
+
+const today = new Date();
+const tomorrow = new Date(today.getTime() + 24 * 60 * 60 * 1000);
+for (const { kind, time } of sunEvents(today, tomorrow, observer)) {
+  console.log(kind, time.toISOString());
+}
+```
+
+### Swift
+
+```swift
+.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.1.0")
+```
+
+```swift
+import Almanac
+import Foundation
+
+let observer = try Observer(latitudeDeg: 48.5, longitudeDeg: -123.0)
+
+let eclipse = try nextLunarEclipse(after: Date())
+let visibility = try lunarEclipseVisibility(eclipse, observer: observer)
+print(eclipse.kind, eclipse.peak, visibility.visibleAtPeak)
+
+let today = Date()
+let tomorrow = today.addingTimeInterval(24 * 60 * 60)
+for event in try sunEvents(from: today, to: tomorrow, observer: observer) {
+  print(event.kind, event.time)
+}
+```
+
+### Performance
+
+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.

package/dist/eclipse.d.ts

@@ -0,0 +1,66 @@
+import { Observer } from './types.js';
+/** A lunar eclipse: peak circumstances plus the contact instants around them. */
+export interface LunarEclipse {
+    /** `total` if the Moon is fully inside the umbra, `partial` if it touches
+     *  the umbra at all, otherwise `penumbral`. */
+    kind: 'penumbral' | 'partial' | 'total';
+    /** Greatest eclipse — when the Moon's centre passes closest to the shadow axis. */
+    peak: Date;
+    /** Fraction of the Moon's diameter inside the umbra at peak; negative when the umbra is missed entirely. */
+    magUmbral: number;
+    /** Fraction of the Moon's diameter inside the penumbra at peak. */
+    magPenumbral: number;
+    /** First penumbral contact. */
+    p1: Date;
+    /** First umbral contact — `null` for a penumbral eclipse. */
+    u1: Date | null;
+    /** Start of totality — `null` unless the eclipse is total. */
+    u2: Date | null;
+    /** End of totality — `null` unless the eclipse is total. */
+    u3: Date | null;
+    /** Last umbral contact — `null` for a penumbral eclipse. */
+    u4: Date | null;
+    /** Last penumbral contact. */
+    p4: Date;
+}
+/** Which of an eclipse's contacts happen with the Moon above the observer's horizon. */
+export interface LunarEclipseVisibility {
+    /** True when the Moon's centre is geometrically above the horizon at peak. */
+    visibleAtPeak: boolean;
+    /** Unrefracted topocentric altitude of the Moon's centre at peak, degrees. */
+    moonGeometricAltAtPeakDeg: number;
+    /** Per-contact horizon test; `null` exactly where the eclipse has no such contact. */
+    contactsVisible: {
+        p1: boolean;
+        u1: boolean | null;
+        u2: boolean | null;
+        u3: boolean | null;
+        u4: boolean | null;
+        p4: boolean;
+    };
+}
+/**
+ * The first lunar eclipse whose peak falls strictly after `after`.
+ *
+ * Every full moon within the next two years is tested: the Moon's ecliptic
+ * latitude prunes the ones no shadow can reach, and the rest get a peak-shadow
+ * search. Magnitudes are the fraction of the Moon's diameter inside each
+ * shadow at peak, so `magUmbral` goes negative when the umbra is missed and
+ * above 1 for a total eclipse.
+ *
+ * @throws {AlmanacOutOfRangeError} if `after` is outside the supported
+ *      interval, or if the next eclipse falls at or past the end of it.
+ */
+export declare function nextLunarEclipse(after: 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
+ * eclipse looks the same from everywhere it is visible at all, so there is
+ * nothing else to compute.
+ *
+ * `contactsVisible` is `null` exactly where `eclipse` has no such contact, so
+ * its shape mirrors the eclipse's.
+ *
+ * @throws {RangeError} if `eclipse` is structurally invalid or `observer` is out of range.
+ */
+export declare function lunarEclipseVisibility(eclipse: LunarEclipse, observer: Observer): LunarEclipseVisibility;

package/dist/eclipse.js

@@ -0,0 +1,295 @@
+// L3 lunar eclipses: the Earth's shadow cone against the Moon at every full
+// moon — peak time, contact times, magnitudes, and whether an observer can see
+// any of it.
+//
+// Translated from the cosinekitty/astronomy upstream, pinned sha
+// 865d3da7d8112bbc7911238052c6af4aaf877181, source/js/astronomy.ts:
+//   CalcShadow (~8458), EarthShadow (~8470), ShadowDistanceSlope (~8535),
+//   PeakEarthShadow (~8553), ShadowSemiDurationMinutes (~8603),
+//   MoonEclipticLatitudeDegrees (~8616) and SearchLunarEclipse (~8710).
+// Constants and operation order are preserved so the Swift port can be a
+// line-for-line translation.
+//
+// Two deliberate departures from upstream, both spec-driven:
+//   - the full-moon probe is this package's `searchMoonPhase`, whose longitudes
+//     are apparent rather than upstream's geometric (see events.ts). It only
+//     seeds a ±0.03 d peak search, so the ~40 s difference cannot change a
+//     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 { dateFromUt, ttDaysFromUt, utDays } from './time.js';
+import { KM_PER_AU, RAD2DEG } from './nutation.js';
+import { calcMoon, moonGeoVectorEqj } from './moon.js';
+import { sunGeoVectorEqj } from './sun.js';
+import { topoAltAzUnrefracted } from './transforms.js';
+import { MOON_MEAN_RADIUS_KM, SUN_RADIUS_KM, search, searchMoonPhase } from './events.js';
+/** UPSTREAM: `EARTH_MEAN_RADIUS_KM` + `EARTH_ATMOSPHERE_KM`, astronomy.ts 142-144.
+ *  The 88 km of atmosphere is what makes the umbra match observed eclipse
+ *  magnitudes; it is not the geometric Earth radius. */
+const EARTH_ECLIPSE_RADIUS_KM = 6371.0 + 88.0;
+/** UPSTREAM: `PruneLatitude`, inside `SearchLunarEclipse` — full-Moon ecliptic
+ *  latitude above which no eclipse is possible. */
+const PRUNE_LATITUDE_DEG = 1.8;
+/** Spec: the search gives up after two years. The catalog's longest gap between
+ *  consecutive lunar eclipses over 1950-2100 is under a year. */
+const SCAN_LIMIT_DAYS = 730;
+/** Upstream's `PeakEarthShadow` window, in days, either side of the full moon. */
+const PEAK_WINDOW_DAYS = 0.03;
+/** Upstream's outermost `ShadowSemiDurationMinutes` window, in minutes. */
+const PENUMBRAL_WINDOW_MINUTES = 200.0;
+const MINUTES_PER_DAY = 24.0 * 60.0;
+/** Root-finder tolerance for every shadow search, seconds — upstream's `Search` default. */
+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.
+ *
+ * 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.
+ */
+const SAME_ECLIPSE_MS = 100;
+/** UPSTREAM: `CalcShadow`, astronomy.ts ~8458. */
+function calcShadow(bodyRadiusKm, ut, target, dir) {
+    const u = (dir.x * target.x + dir.y * target.y + dir.z * target.z) / (dir.x * dir.x + dir.y * dir.y + dir.z * dir.z);
+    const dx = (u * dir.x) - target.x;
+    const dy = (u * dir.y) - target.y;
+    const dz = (u * dir.z) - target.z;
+    const r = KM_PER_AU * Math.hypot(dx, dy, dz);
+    const k = +SUN_RADIUS_KM - (1.0 + u) * (SUN_RADIUS_KM - bodyRadiusKm);
+    const p = -SUN_RADIUS_KM + (1.0 + u) * (SUN_RADIUS_KM + bodyRadiusKm);
+    return { ut, u, r, k, p };
+}
+/**
+ * UPSTREAM: `EarthShadow`, astronomy.ts ~8470 — the Earth's shadow cone
+ * evaluated where the Moon is. `e = -s` is the path of sunlight through the
+ * centre of the Earth; both vectors are EQJ, and `CalcShadow` only ever takes
+ * dot products and a norm of them, so the frame cancels.
+ */
+function earthShadow(ut) {
+    const tt = ttDaysFromUt(ut);
+    // Light-travel and aberration corrected vector from the Earth to the Sun.
+    const s = sunGeoVectorEqj(tt);
+    const e = { x: -s.x, y: -s.y, z: -s.z };
+    // Geocentric moon.
+    const m = moonGeoVectorEqj(tt);
+    return calcShadow(EARTH_ECLIPSE_RADIUS_KM, ut, m, e);
+}
+/** UPSTREAM: `ShadowDistanceSlope`, astronomy.ts ~8535, bound to `EarthShadow`. */
+function earthShadowSlope(ut) {
+    const dt = 1.0 / 86400.0;
+    return (earthShadow(ut + dt).r - earthShadow(ut - dt).r) / dt;
+}
+/**
+ * UPSTREAM: `PeakEarthShadow`, astronomy.ts ~8553 — greatest eclipse is where
+ * the Moon-to-axis distance stops shrinking, i.e. the ascending zero of its
+ * 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');
+    if (ut === null)
+        throw new Error('almanac internal: failed to find peak Earth shadow time');
+    return earthShadow(ut);
+}
+/**
+ * UPSTREAM: `ShadowSemiDurationMinutes`, astronomy.ts ~8603 — searches
+ * backwards and forwards from the peak for the crossings of `radiusLimitKm`,
+ * 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) {
+    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)');
+    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
+}
+/** UPSTREAM: `MoonEclipticLatitudeDegrees`, astronomy.ts ~8616. */
+function moonEclipticLatitudeDeg(ut) {
+    return RAD2DEG * calcMoon(ttDaysFromUt(ut)).geoEclipLat;
+}
+/**
+ * The first lunar eclipse whose peak falls strictly after `after`.
+ *
+ * Every full moon within the next two years is tested: the Moon's ecliptic
+ * latitude prunes the ones no shadow can reach, and the rest get a peak-shadow
+ * search. Magnitudes are the fraction of the Moon's diameter inside each
+ * shadow at peak, so `magUmbral` goes negative when the umbra is missed and
+ * above 1 for a total eclipse.
+ *
+ * @throws {AlmanacOutOfRangeError} if `after` is outside the supported
+ *      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);
+        if (fullmoon === null)
+            throw new Error('almanac internal: cannot find full moon');
+        // UPSTREAM `SearchLunarEclipse`: step past this full moon before the
+        // next probe, so the same one cannot be found twice.
+        fmUt = fullmoon + 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.
+        if (Math.abs(moonEclipticLatitudeDeg(fullmoon)) >= PRUNE_LATITUDE_DEG)
+            continue;
+        // Search near the full moon for the time when the center of the Moon
+        // is closest to the line passing through the centers of the Sun and Earth.
+        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)
+            continue;
+        if (peak.getTime() >= SUPPORTED_MAX)
+            throw new AlmanacOutOfRangeError();
+        return buildEclipse(shadow, peak);
+    }
+    // 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()}`);
+}
+/** UPSTREAM: the classification and semi-duration block of `SearchLunarEclipse`, astronomy.ts ~8730-8755. */
+function buildEclipse(shadow, peak) {
+    // This is at least a penumbral eclipse.
+    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);
+    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);
+        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);
+        }
+    }
+    // Fraction of the Moon's diameter immersed in each shadow. Shadow radii,
+    // axis distance and the Moon's radius all live in the same plane at the
+    // Moon's distance, so the angles at that distance are these lengths over a
+    // common divisor — it cancels, and the ratio is exact in km.
+    const s = MOON_MEAN_RADIUS_KM;
+    const magPenumbral = (shadow.p + s - shadow.r) / (2 * s);
+    const magUmbral = (shadow.k + s - shadow.r) / (2 * s);
+    const at = (offsetMinutes) => dateFromUt(shadow.ut + offsetMinutes / MINUTES_PER_DAY);
+    const umbral = kind !== 'penumbral';
+    const total = kind === 'total';
+    return {
+        kind,
+        peak,
+        magUmbral,
+        magPenumbral,
+        p1: at(-sdPenum),
+        u1: umbral ? at(-sdPartial) : null,
+        u2: total ? at(-sdTotal) : null,
+        u3: total ? at(+sdTotal) : null,
+        u4: umbral ? at(+sdPartial) : null,
+        p4: at(+sdPenum)
+    };
+}
+/**
+ * Trust boundary: `lunarEclipseVisibility` takes a plain object, which callers
+ * can hand-build or round-trip through JSON. A contact out of order or missing
+ * for its kind would otherwise produce a silently wrong visibility answer, so
+ * the shape is checked before any of it is used.
+ */
+function assertLunarEclipse(e) {
+    if (e === null || typeof e !== 'object')
+        throw new RangeError('eclipse must be an object');
+    if (e.kind !== 'penumbral' && e.kind !== 'partial' && e.kind !== 'total')
+        throw new RangeError(`unknown lunar eclipse kind: ${String(e.kind)}`);
+    const umbral = e.kind !== 'penumbral';
+    const total = e.kind === 'total';
+    const expected = { u1: umbral, u2: total, u3: total, u4: umbral };
+    for (const key of ['u1', 'u2', 'u3', 'u4']) {
+        const present = e[key] !== null && e[key] !== undefined;
+        if (present !== expected[key])
+            throw new RangeError(`${e.kind} lunar eclipse must ${expected[key] ? '' : 'not '}have ${key}`);
+    }
+    // Strictly ascending, skipping the absent ones. Strict is safe: the closest
+    // two contacts of any eclipse over 1950-2100 are five minutes apart. The
+    // third element marks the contacts every eclipse has, whatever its kind —
+    // absent, they would otherwise slip through as `null` past a `boolean` type.
+    const ordered = [
+        ['p1', e.p1, true], ['u1', e.u1, false], ['u2', e.u2, false], ['peak', e.peak, true],
+        ['u3', e.u3, false], ['u4', e.u4, false], ['p4', e.p4, true]
+    ];
+    let prevName = '';
+    let prevMs = -Infinity;
+    for (const [name, d, required] of ordered) {
+        if (d == null) {
+            if (required)
+                throw new RangeError(`lunar eclipse ${name} is required`);
+            continue;
+        }
+        const ms = d instanceof Date ? d.getTime() : NaN;
+        if (!Number.isFinite(ms))
+            throw new RangeError(`lunar eclipse ${name} is not a valid Date`);
+        if (ms <= prevMs)
+            throw new RangeError(`lunar eclipse contacts out of order: ${prevName} not before ${name}`);
+        prevName = name;
+        prevMs = ms;
+    }
+}
+/**
+ * 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
+ * eclipse looks the same from everywhere it is visible at all, so there is
+ * nothing else to compute.
+ *
+ * `contactsVisible` is `null` exactly where `eclipse` has no such contact, so
+ * its shape mirrors the eclipse's.
+ *
+ * @throws {RangeError} if `eclipse` is structurally invalid or `observer` is out of range.
+ */
+export function lunarEclipseVisibility(eclipse, observer) {
+    assertLunarEclipse(eclipse);
+    assertObserver(observer);
+    const altAt = (d) => {
+        const ut = utDays(d);
+        return topoAltAzUnrefracted(moonGeoVectorEqj(ttDaysFromUt(ut)), ut, observer).altDeg;
+    };
+    // `== null` deliberately: the validator counts `undefined` as absent too,
+    // so the reader must, or an `undefined` contact would reach `utDays` raw.
+    const up = (d) => (d == null ? null : altAt(d) > 0);
+    const peakAltDeg = altAt(eclipse.peak);
+    return {
+        visibleAtPeak: peakAltDeg > 0,
+        moonGeometricAltAtPeakDeg: peakAltDeg,
+        contactsVisible: {
+            p1: up(eclipse.p1),
+            u1: up(eclipse.u1),
+            u2: up(eclipse.u2),
+            u3: up(eclipse.u3),
+            u4: up(eclipse.u4),
+            p4: up(eclipse.p4)
+        }
+    };
+}

package/dist/events.d.ts

@@ -0,0 +1,81 @@
+import { Observer } from './types.js';
+/** A Sun event: a horizon or twilight crossing, or upper transit. */
+export type SunEventKind = 'rise' | 'set' | 'civilDawn' | 'civilDusk' | 'nauticalDawn' | 'nauticalDusk' | 'astroDawn' | 'astroDusk' | 'transit';
+export interface SunEvent {
+    time: Date;
+    kind: SunEventKind;
+}
+/** A Moon event: the upper limb crossing the horizon. */
+export type MoonEventKind = 'rise' | 'set';
+export interface MoonEvent {
+    time: Date;
+    kind: MoonEventKind;
+}
+/** A quarter lunar phase. */
+export type MoonPhaseName = 'new' | 'firstQuarter' | 'full' | 'lastQuarter';
+export interface MoonPhaseEvent {
+    time: Date;
+    phase: MoonPhaseName;
+}
+/**
+ * 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 declare const MOON_MEAN_RADIUS_KM = 1737.4;
+/** UPSTREAM: `SUN_RADIUS_KM`, astronomy.ts line 134. INTERNAL, see above. */
+export declare const SUN_RADIUS_KM = 695700;
+/**
+ * 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 declare function quantizedUt(ut: number): number;
+/**
+ * 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 declare function sunEvents(startUtc: Date, endUtc: Date, observer: Observer): SunEvent[];
+/**
+ * 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 declare function moonEvents(startUtc: Date, endUtc: Date, observer: Observer): MoonEvent[];
+/**
+ * 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 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
+ * 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 declare function searchMoonPhase(targetLonDeg: number, startUt: number, limitDays: number): number | null;
+/**
+ * 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 declare function searchMoonPhases(startUtc: Date, endUtc: Date): MoonPhaseEvent[];