@openwaters/almanac 0.3.0 → 0.4.0

package/README.md

@@ -1,9 +1,6 @@
 # Almanac
 
-Offline sun & moon engine for the Salish Sea and everywhere else — positions,
-rise/set/twilight, moon phase, lunar eclipses (solar planned), and where any fixed
-star stands from a catalog position, computed from pure geometry with zero network
-and zero runtime data files.
+Offline sky engine for the Salish Sea and everywhere else: Sun and Moon positions, rise, set, twilight, Moon phase, lunar eclipses, solar eclipses for an observer, and fixed-star altitude and azimuth from catalog positions, computed from pure geometry with zero network and zero runtime data files.
 
 Twin implementations, one behavior:
 
@@ -12,22 +9,22 @@ Twin implementations, one behavior:
 - `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.
+Supported interval: 1950-01-01T00:00Z ≤ t < 2101-01-01T00:00Z; results outside it raise a typed error. All instants are UT1-accurate, while unknown future DUT1 is outside the civil-UTC accuracy promise. See the [public contract](docs/CONTRACT.md#time-and-supported-interval) for the time model.
 
-- 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.
+- Contract: [`docs/CONTRACT.md`](docs/CONTRACT.md), including coordinates, public behavior, accuracy, and fixture evidence.
+- Scope: [`docs/ROADMAP.md`](docs/ROADMAP.md), including supported behavior and deliberate boundaries.
+- Development and releases: [`CONTRIBUTING.md`](CONTRIBUTING.md), including pinned tools and required checks.
+- Landing page: [openwaters.io/sky](https://openwaters.io/sky), with 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**
+Almanac includes a shared performance harness for both ports: **22 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.
+moon phases, next/previous/range lunar and solar eclipse searches, including empty
+windows, and solar obscuration over a 228-hour track.
 
 The v0.2.1 optimizations reuse Moon and shadow geometry, flatten scratch arrays,
 and refine altitude crossings with fewer position evaluations. In the
@@ -43,20 +40,18 @@ median query time fell relative to the v0.2.0 astronomy code:
 | 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.
+TypeScript was measured on Ubuntu; Swift used release builds on macOS. 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+):
+Reproduce the comparison locally from the repository root with mise 2026.9.1 or newer after installing the configured Node and Swift versions in `mise.toml`:
 
 ```bash
-npm ci --prefix typescript
-node benchmarks/run.mjs --base v0.2.0
+mise install
+mise exec -- npm ci --prefix typescript
+mise exec -- node benchmarks/run.mjs --base v0.2.0 --skip '^solar/'
 ```
 
+The `--skip` pattern leaves out the solar eclipse workloads, which need a base of 0.4.0 or later.
+
 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
@@ -74,7 +69,7 @@ npm install @openwaters/almanac
 ```
 
 ```ts
-import { nextLunarEclipse, lunarEclipseVisibility, sunEvents, starAltAz } from '@openwaters/almanac';
+import { nextLunarEclipse, lunarEclipseVisibility, nextSolarEclipse, solarObscuration, sunEvents, starAltAz } from '@openwaters/almanac';
 
 const observer = { latitudeDeg: 48.5, longitudeDeg: -123.0 };
 
@@ -82,6 +77,10 @@ const eclipse = nextLunarEclipse(new Date());
 const visibility = lunarEclipseVisibility(eclipse, observer);
 console.log(eclipse.kind, eclipse.peak, visibility.visibleAtPeak);
 
+const solar = nextSolarEclipse(new Date(), observer);
+console.log(solar.kind, solar.peak, solar.obscuration, solar.sunAltDeg.peak);
+console.log(solarObscuration(solar.peak, observer));   // fraction of the Sun's disc covered, 0 to 1
+
 const today = new Date();
 const tomorrow = new Date(today.getTime() + 24 * 60 * 60 * 1000);
 for (const { kind, time } of sunEvents(today, tomorrow, observer)) {
@@ -95,7 +94,7 @@ const { azDeg, altDeg } = starAltAz(88.792939, 7.407064, today, observer);
 ### Swift
 
 ```swift
-.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.3.0")
+.package(url: "https://github.com/openwatersio/almanac.git", exact: "0.4.0")
 ```
 
 ```swift
@@ -108,6 +107,10 @@ let eclipse = try nextLunarEclipse(after: Date())
 let visibility = try lunarEclipseVisibility(eclipse, observer: observer)
 print(eclipse.kind, eclipse.peak, visibility.visibleAtPeak)
 
+let solar = try nextSolarEclipse(after: Date(), observer: observer)
+print(solar.kind, solar.peak, solar.obscuration, solar.sunAltDeg.peak)
+print(try solarObscuration(at: solar.peak, observer: observer))   // fraction of the Sun's disc covered, 0 to 1
+
 let today = Date()
 let tomorrow = today.addingTimeInterval(24 * 60 * 60)
 for event in try sunEvents(from: today, to: tomorrow, observer: observer) {
@@ -136,3 +139,5 @@ let eclipses = try lunarEclipses(from: today, to: tomorrow)
 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.
+
+Solar eclipses are searched for an observer, because their contacts only exist for a place: `nextSolarEclipse(after, observer)`, `previousSolarEclipse(before, observer)`, and `solarEclipses(startUtc, endUtc, observer)`. An eclipse whose Sun is below the horizon at C1, the peak, and C4 is not returned.

package/dist/eclipse.d.ts

@@ -1,4 +1,5 @@
 import { Observer } from './types.js';
+import { Vec3 } from './nutation.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
@@ -39,6 +40,57 @@ export interface LunarEclipseVisibility {
         p4: boolean;
     };
 }
+/** UPSTREAM: `PruneLatitude`, inside `SearchLunarEclipse` — full- or new-Moon
+ *  ecliptic latitude above which no eclipse is possible.
+ *  INTERNAL: shared with solar.ts. */
+export declare const PRUNE_LATITUDE_DEG = 1.8;
+/** Root-finder tolerance for every shadow search, seconds — upstream's `Search` default.
+ *  INTERNAL: shared with solar.ts. */
+export declare const SHADOW_TOL_SECONDS = 1;
+/** UPSTREAM: `Search`'s default `iter_limit`.
+ *  INTERNAL: shared with solar.ts. */
+export declare const SHADOW_ITER_CAP = 20;
+/**
+ * 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.
+ *
+ * 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.
+ * INTERNAL: shared with solar.ts.
+ */
+export declare const SAME_ECLIPSE_MS = 100;
+/**
+ * UPSTREAM: `ShadowInfo` (astronomy.ts ~8445). `target` and `dir` are the
+ * inputs `CalcShadow` measured from: the lunar case passes the geocentric
+ * Moon against the Sun-to-Earth line, the solar case (solar.ts) the
+ * lunacentric observer against the heliocentric Moon, and the obscuration
+ * path reads them back. Upstream's `time` is an `AstroTime`; here the instant
+ * travels as days since J2000 UT, as everywhere in L3.
+ * INTERNAL: exported for `solar.ts`, not part of the public API.
+ */
+export interface ShadowInfo {
+    /** Days since J2000 (UT). */
+    ut: number;
+    /** Shadow-axis parameter: distance to the shadow plane over the casting body's distance. */
+    u: number;
+    /** Distance from `target` to the shadow axis, km. */
+    r: number;
+    /** Umbra radius at the shadow plane, km. */
+    k: number;
+    /** Penumbra radius at the shadow plane, km. */
+    p: number;
+    /** The point measured from, AU. */
+    target: Vec3;
+    /** The shadow axis, AU. */
+    dir: Vec3;
+}
+/** UPSTREAM: `CalcShadow`, astronomy.ts ~8458. INTERNAL, shared with solar.ts. */
+export declare function calcShadow(bodyRadiusKm: number, ut: number, target: Vec3, dir: Vec3): ShadowInfo;
+/** UPSTREAM: `MoonEclipticLatitudeDegrees`, astronomy.ts ~8616.
+ *  INTERNAL: shared with solar.ts. */
+export declare function moonEclipticLatitudeDeg(ut: number): number;
 /**
  * The first lunar eclipse whose peak falls strictly after `after`.
  *

package/dist/eclipse.js

@@ -28,9 +28,10 @@ import { MOON_MEAN_RADIUS_KM, SUN_RADIUS_KM, search, searchMoonPhase } from './e
  *  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;
+/** UPSTREAM: `PruneLatitude`, inside `SearchLunarEclipse` — full- or new-Moon
+ *  ecliptic latitude above which no eclipse is possible.
+ *  INTERNAL: shared with solar.ts. */
+export 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;
@@ -39,10 +40,12 @@ 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;
+/** Root-finder tolerance for every shadow search, seconds — upstream's `Search` default.
+ *  INTERNAL: shared with solar.ts. */
+export const SHADOW_TOL_SECONDS = 1;
+/** UPSTREAM: `Search`'s default `iter_limit`.
+ *  INTERNAL: shared with solar.ts. */
+export const SHADOW_ITER_CAP = 20;
 /**
  * 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
@@ -51,10 +54,11 @@ const SHADOW_ITER_CAP = 20;
  * 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.
+ * INTERNAL: shared with solar.ts.
  */
-const SAME_ECLIPSE_MS = 100;
-/** UPSTREAM: `CalcShadow`, astronomy.ts ~8458. */
-function calcShadow(bodyRadiusKm, ut, target, dir) {
+export const SAME_ECLIPSE_MS = 100;
+/** UPSTREAM: `CalcShadow`, astronomy.ts ~8458. INTERNAL, shared with solar.ts. */
+export 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;
@@ -62,7 +66,7 @@ function calcShadow(bodyRadiusKm, ut, target, dir) {
     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 };
+    return { ut, u, r, k, p, target, dir };
 }
 /**
  * UPSTREAM: `EarthShadow`, astronomy.ts ~8470 — the Earth's shadow cone
@@ -119,8 +123,9 @@ function shadowSemiDurationMinutes(shadow, radiusLimitKm, windowMinutes) {
         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) {
+/** UPSTREAM: `MoonEclipticLatitudeDegrees`, astronomy.ts ~8616.
+ *  INTERNAL: shared with solar.ts. */
+export function moonEclipticLatitudeDeg(ut) {
     return RAD2DEG * calcMoon(ttDaysFromUt(ut)).geoEclipLat;
 }
 /**

package/dist/index.d.ts

@@ -10,3 +10,5 @@ export type { SunEvent, SunEventKind, MoonEvent, MoonEventKind, MoonPhaseEvent,
 export { sunEvents, moonEvents, searchMoonPhases } from './events.js';
 export type { LunarEclipse, LunarEclipseVisibility } from './eclipse.js';
 export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';
+export type { SolarEclipse, SolarEclipseKind, SolarEclipseSunAltitudes } from './solar.js';
+export { nextSolarEclipse, previousSolarEclipse, solarEclipses, solarObscuration } from './solar.js';

package/dist/index.js

@@ -4,3 +4,4 @@ export { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
 export { moonIllumination } from './illumination.js';
 export { sunEvents, moonEvents, searchMoonPhases } from './events.js';
 export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';
+export { nextSolarEclipse, previousSolarEclipse, solarEclipses, solarObscuration } from './solar.js';

package/dist/solar.d.ts

@@ -0,0 +1,66 @@
+import { Observer } from './types.js';
+/** How much of the Sun an observer sees covered: `partial` when the Moon never covers it, `annular` when the Moon sits inside the Sun's disc, `total` when it covers it. */
+export type SolarEclipseKind = 'partial' | 'annular' | 'total';
+/** The Sun's refracted topocentric altitude at each contact, degrees; `null` exactly where the eclipse has no such contact. */
+export interface SolarEclipseSunAltitudes {
+    c1: number;
+    c2: number | null;
+    peak: number;
+    c3: number | null;
+    c4: number;
+}
+/** A solar eclipse as one observer sees it: peak circumstances plus the contact instants around them. */
+export interface SolarEclipse {
+    kind: SolarEclipseKind;
+    /** Fraction of the Sun's disc area covered at peak; exactly 1 for a total eclipse. */
+    obscuration: number;
+    /** First contact: the partial phase begins. */
+    c1: Date;
+    /** Second contact: the total or annular phase begins — `null` for a partial eclipse. */
+    c2: Date | null;
+    /** Closest approach of the Moon's shadow axis to the observer. */
+    peak: Date;
+    /** Third contact: the total or annular phase ends — `null` for a partial eclipse. */
+    c3: Date | null;
+    /** Fourth contact: the partial phase ends. */
+    c4: Date;
+    /** The number `sunAltAz` reports at each contact instant, so "above the horizon" agrees with the Sun a consumer draws. */
+    sunAltDeg: SolarEclipseSunAltitudes;
+}
+/**
+ * The fraction of the Sun's disc area the Moon covers for `observer` at
+ * `time`: 0 when the discs are apart, 1 in totality, the ratio of the disc
+ * areas in annularity, and the lens overlap between. Purely geometric — it
+ * does not test the horizon; a consumer that draws the Sun already knows
+ * whether it is up.
+ *
+ * @throws {AlmanacOutOfRangeError} if `time` is outside the supported interval.
+ * @throws {RangeError} if `time` is invalid or `observer` is out of range.
+ */
+export declare function solarObscuration(time: Date, observer: Observer): number;
+/**
+ * The first solar eclipse `observer` can see whose peak falls strictly after
+ * `after`.
+ *
+ * Every new moon up to the end of the supported interval is tested: the
+ * Moon's ecliptic latitude prunes the ones no shadow can reach, and the rest
+ * get a peak-shadow search from the observer. An eclipse whose Sun is below
+ * the horizon at C1, the peak, and C4 is skipped.
+ *
+ * @throws {AlmanacOutOfRangeError} if `after` is outside the supported
+ *      interval, or if no visible eclipse remains before the end of it.
+ * @throws {RangeError} if `after` is invalid or `observer` is out of range.
+ */
+export declare function nextSolarEclipse(after: Date, observer: Observer): SolarEclipse;
+/**
+ * The last solar eclipse `observer` can see whose peak falls strictly before
+ * `before`, skipping peaks within 100 ms of it, just as `nextSolarEclipse`
+ * does on the other side.
+ *
+ * @throws {AlmanacOutOfRangeError} if `before` is outside the supported
+ *      interval, or if no visible eclipse remains after the start of it.
+ * @throws {RangeError} if `before` is invalid or `observer` is out of range.
+ */
+export declare function previousSolarEclipse(before: Date, observer: Observer): SolarEclipse;
+/** Solar eclipses `observer` can see with peaks in `[startUtc, endUtc)`, sorted ascending. Contacts may fall outside the window. */
+export declare function solarEclipses(startUtc: Date, endUtc: Date, observer: Observer): SolarEclipse[];

package/dist/solar.js

@@ -0,0 +1,344 @@
+// L3 solar eclipses for one observer: the Moon's shadow cone against the
+// observer at every new moon — the local peak, the contacts C1–C4 with the
+// Sun's altitude at each, the covered fraction at peak, and the covered
+// fraction of the Sun's disc at any instant.
+//
+// Translated from the cosinekitty/astronomy upstream, pinned sha
+// 865d3da7d8112bbc7911238052c6af4aaf877181, source/js/astronomy.ts:
+//   AngleBetween (~256), geo_pos (~2236, in transforms.ts),
+//   LocalMoonShadow (~8494), PeakLocalMoonShadow (~8587), Obscuration (~8622),
+//   SolarEclipseObscuration (~8670), EclipseKindFromUmbra (~8834),
+//   local_partial_distance (~9126), local_total_distance (~9130),
+//   LocalEclipse (~9137), LocalEclipseTransition (~9165), SunAltitude (~9181)
+//   and SearchLocalSolarEclipse (~9211).
+// Constants and operation order are preserved so the Swift port can be a
+// line-for-line translation.
+//
+// Four deliberate departures from upstream, all spec-driven:
+//   - the new-moon probe is this package's `searchMoonPhase`, whose longitudes
+//     are apparent rather than upstream's geometric (see events.ts). It only
+//     seeds a ±0.2 d peak search, so the ~40 s difference cannot change a
+//     result.
+//   - previous and range searches, the fixed whole-UT-day new-moon seed and
+//     the 100 ms same-eclipse band come from the lunar port (eclipse.ts);
+//     upstream searches forward only.
+//   - the night filter also accepts the Sun above the horizon at the peak, not
+//     only at C1 or C4, so a short polar day inside the eclipse is kept.
+//   - no two-year scan limit: next/previous walk new moons to the supported
+//     boundary. A place can go years without a visible solar eclipse, and a
+//     pruned new moon costs one Moon evaluation.
+import { assertObserver, assertSupported, assertSupportedWindowEnd, AlmanacOutOfRangeError, SUPPORTED_MIN, SUPPORTED_MAX } from './types.js';
+import { dateFromUt, ttDaysFromUt, utDays } from './time.js';
+import { DEG2RAD, KM_PER_AU, RAD2DEG } from './nutation.js';
+import { moonGeoVectorEqj } from './moon.js';
+import { sunGeoVectorEqj } from './sun.js';
+import { observerGeoVectorEqj, refractionDeg, topoAltAzUnrefracted } from './transforms.js';
+import { MOON_MEAN_RADIUS_KM, SUN_RADIUS_KM, search, searchMoonPhase } from './events.js';
+import { calcShadow, moonEclipticLatitudeDeg, PRUNE_LATITUDE_DEG, SAME_ECLIPSE_MS, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP } from './eclipse.js';
+/** UPSTREAM: `SUN_RADIUS_AU` and `MOON_POLAR_RADIUS_AU`, astronomy.ts 135 and 149-150. */
+const SUN_RADIUS_AU = SUN_RADIUS_KM / KM_PER_AU;
+const MOON_POLAR_RADIUS_KM = 1736.0;
+const MOON_POLAR_RADIUS_AU = MOON_POLAR_RADIUS_KM / KM_PER_AU;
+/** Upstream's `PeakLocalMoonShadow` window, in days, either side of the new moon. */
+const PEAK_WINDOW_DAYS = 0.2;
+/** Upstream's `LocalEclipse` windows, in days, either side of the peak. */
+const PARTIAL_WINDOW_DAYS = 0.2;
+const TOTAL_WINDOW_DAYS = 0.01;
+/**
+ * UPSTREAM: `LocalMoonShadow`, astronomy.ts ~8494 — the Moon's shadow cone
+ * evaluated at the observer: the lunacentric observer measured against the
+ * heliocentric Moon. All three vectors are EQJ, and `calcShadow` only ever
+ * takes dot products and norms of them, so the frame cancels.
+ */
+function localMoonShadow(ut, observer) {
+    const tt = ttDaysFromUt(ut);
+    // Observer's geocentric position.
+    const pos = observerGeoVectorEqj(ut, observer);
+    // Light-travel and aberration corrected Sun.
+    const s = sunGeoVectorEqj(tt);
+    // Geocentric Moon.
+    const m = moonGeoVectorEqj(tt);
+    // Lunacentric location of an observer on the Earth's surface.
+    const o = { x: pos.x - m.x, y: pos.y - m.y, z: pos.z - m.z };
+    // Convert geocentric moon to heliocentric Moon.
+    const hm = { x: m.x - s.x, y: m.y - s.y, z: m.z - s.z };
+    return calcShadow(MOON_MEAN_RADIUS_KM, ut, o, hm);
+}
+/** UPSTREAM: `AngleBetween`, astronomy.ts ~256 — degrees. */
+function angleBetweenDeg(a, b) {
+    const aa = (a.x * a.x + a.y * a.y + a.z * a.z);
+    if (Math.abs(aa) < 1.0e-8)
+        throw new Error('almanac internal: AngleBetween first vector is too short');
+    const bb = (b.x * b.x + b.y * b.y + b.z * b.z);
+    if (Math.abs(bb) < 1.0e-8)
+        throw new Error('almanac internal: AngleBetween second vector is too short');
+    const dot = (a.x * b.x + a.y * b.y + a.z * b.z) / Math.sqrt(aa * bb);
+    if (dot <= -1.0)
+        return 180;
+    if (dot >= +1.0)
+        return 0;
+    return RAD2DEG * Math.acos(dot);
+}
+/**
+ * UPSTREAM: `Obscuration`, astronomy.ts ~8622 — the area of intersection of
+ * two discs of radii `a` and `b` whose centres are `c` apart, divided by the
+ * area of the first disc.
+ */
+function discOverlap(a, b, c) {
+    if (a <= 0.0)
+        throw new Error('almanac internal: radius of first disc must be positive');
+    if (b <= 0.0)
+        throw new Error('almanac internal: radius of second disc must be positive');
+    if (c < 0.0)
+        throw new Error('almanac internal: distance between discs is not allowed to be negative');
+    if (c >= a + b) {
+        // The discs are too far apart to have any overlapping area.
+        return 0.0;
+    }
+    if (c == 0.0) {
+        // The discs have a common center. Therefore, one disc is inside the other.
+        return (a <= b) ? 1.0 : (b * b) / (a * a);
+    }
+    const x = (a * a - b * b + c * c) / (2 * c);
+    const radicand = a * a - x * x;
+    if (radicand <= 0.0) {
+        // The circumferences do not intersect, or are tangent.
+        // We already ruled out the case of non-overlapping discs.
+        // Therefore, one disc is inside the other.
+        return (a <= b) ? 1.0 : (b * b) / (a * a);
+    }
+    // The discs overlap fractionally in a pair of lens-shaped areas.
+    const y = Math.sqrt(radicand);
+    // Return the overlapping fractional area.
+    // There are two lens-shaped areas, one to the left of x, the other to the right of x.
+    // Each part is calculated by subtracting a triangular area from a sector's area.
+    const lens1 = a * a * Math.acos(x / a) - x * y;
+    const lens2 = b * b * Math.acos((c - x) / b) - (c - x) * y;
+    // Find the fractional area with respect to the first disc.
+    return (lens1 + lens2) / (Math.PI * a * a);
+}
+/**
+ * UPSTREAM: the body of `SolarEclipseObscuration`, astronomy.ts ~8670, before
+ * its clamp — the fraction of the Sun's apparent disc the Moon covers for an
+ * observer, from the heliocentric Moon `hm` and the lunacentric observer `lo`.
+ */
+function discObscuration(hm, lo) {
+    // Find heliocentric observer.
+    const ho = { x: hm.x + lo.x, y: hm.y + lo.y, z: hm.z + lo.z };
+    // Calculate the apparent angular radius of the Sun for the observer.
+    const sunRadius = Math.asin(SUN_RADIUS_AU / Math.hypot(ho.x, ho.y, ho.z));
+    // Calculate the apparent angular radius of the Moon for the observer.
+    const moonRadius = Math.asin(MOON_POLAR_RADIUS_AU / Math.hypot(lo.x, lo.y, lo.z));
+    // Calculate the apparent angular separation between the Sun's center and the Moon's center.
+    const sunMoonSeparation = angleBetweenDeg(lo, ho);
+    // Find the fraction of the Sun's apparent disc area that is covered by the Moon.
+    return discOverlap(sunRadius, moonRadius, sunMoonSeparation * DEG2RAD);
+}
+/**
+ * The fraction of the Sun's disc area the Moon covers for `observer` at
+ * `time`: 0 when the discs are apart, 1 in totality, the ratio of the disc
+ * areas in annularity, and the lens overlap between. Purely geometric — it
+ * does not test the horizon; a consumer that draws the Sun already knows
+ * whether it is up.
+ *
+ * @throws {AlmanacOutOfRangeError} if `time` is outside the supported interval.
+ * @throws {RangeError} if `time` is invalid or `observer` is out of range.
+ */
+export function solarObscuration(time, observer) {
+    assertSupported(time);
+    assertObserver(observer);
+    const shadow = localMoonShadow(utDays(time), observer);
+    return discObscuration(shadow.dir, shadow.target);
+}
+/**
+ * UPSTREAM: `SolarEclipseObscuration`, astronomy.ts ~8670, with its clamp:
+ * "in marginal cases, we need to clamp obscuration to less than 1.0. This
+ * function is never called for total eclipses, so it should never return 1.0."
+ */
+function solarEclipseObscuration(hm, lo) {
+    return Math.min(0.9999, discObscuration(hm, lo));
+}
+/** UPSTREAM: `ShadowDistanceSlope`, astronomy.ts ~8535, bound to `localMoonShadow`. */
+function localShadowSlope(ut, observer) {
+    const dt = 1.0 / 86400.0;
+    return (localMoonShadow(ut + dt, observer).r - localMoonShadow(ut - dt, observer).r) / dt;
+}
+/**
+ * UPSTREAM: `PeakLocalMoonShadow`, astronomy.ts ~8587 — the time near the
+ * new moon when the Moon's shadow axis comes closest to the observer, i.e.
+ * the ascending zero of the axis distance's time derivative.
+ */
+function peakLocalMoonShadow(centerUt, observer) {
+    // Use the same new-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 newmoon = searchMoonPhase(0, Math.floor(centerUt) - 1, 4);
+    if (newmoon === null)
+        throw new Error('almanac internal: cannot refine new moon');
+    const ut = search(u => localShadowSlope(u, observer), newmoon - PEAK_WINDOW_DAYS, newmoon + PEAK_WINDOW_DAYS, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'peak local moon shadow');
+    if (ut === null)
+        throw new Error('almanac internal: failed to find peak local Moon shadow time');
+    return localMoonShadow(ut, observer);
+}
+/**
+ * UPSTREAM: `EclipseKindFromUmbra`, astronomy.ts ~8834 — a positive umbra
+ * radius at the observer is a total eclipse, otherwise annular. The 14 m
+ * bias is upstream's, added to match Espenak's classifications.
+ */
+function eclipseKindFromUmbra(k) {
+    return (k > 0.014) ? 'total' : 'annular';
+}
+/** UPSTREAM: `local_partial_distance`, astronomy.ts ~9126. */
+function localPartialDistance(shadow) {
+    return shadow.p - shadow.r;
+}
+/** UPSTREAM: `local_total_distance`, astronomy.ts ~9130 — `|k|`, because the umbra radius is negative for an annular eclipse. */
+function localTotalDistance(shadow) {
+    return Math.abs(shadow.k) - shadow.r;
+}
+/** UPSTREAM: `LocalEclipseTransition`, astronomy.ts ~9165 — the instant `func` crosses zero in `direction` inside `[t1, t2]`. */
+function localEclipseTransition(observer, direction, func, t1, t2) {
+    const ut = search(u => direction * func(localMoonShadow(u, observer)), t1, t2, SHADOW_TOL_SECONDS, SHADOW_ITER_CAP, 'local eclipse transition');
+    if (ut === null)
+        throw new Error('almanac internal: local eclipse transition search failed');
+    return ut;
+}
+/**
+ * UPSTREAM: `SunAltitude`, astronomy.ts ~9181 — the refracted topocentric
+ * altitude `sunAltAz` reports, without its interval assertion: a contact can
+ * fall just outside the supported interval while its peak is inside.
+ */
+function sunAltDegAt(d, observer) {
+    const ut = utDays(d);
+    const alt = topoAltAzUnrefracted(sunGeoVectorEqj(ttDaysFromUt(ut)), ut, observer).altDeg;
+    return alt + refractionDeg(alt);
+}
+/** UPSTREAM: `LocalEclipse`, astronomy.ts ~9137 — contacts and kind around a peak the observer is inside the penumbra for. */
+function buildSolarEclipse(shadow, observer) {
+    const peakUt = shadow.ut;
+    const c1Ut = localEclipseTransition(observer, 1, localPartialDistance, peakUt - PARTIAL_WINDOW_DAYS, peakUt);
+    const c4Ut = localEclipseTransition(observer, -1, localPartialDistance, peakUt, peakUt + PARTIAL_WINDOW_DAYS);
+    let c2Ut = null;
+    let c3Ut = null;
+    let kind;
+    if (shadow.r < Math.abs(shadow.k)) { // take absolute value of 'k' to handle annular eclipses too.
+        c2Ut = localEclipseTransition(observer, 1, localTotalDistance, peakUt - TOTAL_WINDOW_DAYS, peakUt);
+        c3Ut = localEclipseTransition(observer, -1, localTotalDistance, peakUt, peakUt + TOTAL_WINDOW_DAYS);
+        kind = eclipseKindFromUmbra(shadow.k);
+    }
+    else {
+        kind = 'partial';
+    }
+    const obscuration = (kind === 'total') ? 1.0 : solarEclipseObscuration(shadow.dir, shadow.target);
+    // Altitudes come from the reported (TimeClip-truncated) instants, so
+    // `sunAltAz(e.c1, observer).altDeg === e.sunAltDeg.c1` exactly.
+    const c1 = dateFromUt(c1Ut);
+    const c2 = c2Ut === null ? null : dateFromUt(c2Ut);
+    const peak = dateFromUt(peakUt);
+    const c3 = c3Ut === null ? null : dateFromUt(c3Ut);
+    const c4 = dateFromUt(c4Ut);
+    const alt = (d) => (d === null ? null : sunAltDegAt(d, observer));
+    return {
+        kind, obscuration, c1, c2, peak, c3, c4,
+        sunAltDeg: { c1: alt(c1), c2: alt(c2), peak: alt(peak), c3: alt(c3), c4: alt(c4) }
+    };
+}
+/**
+ * The night filter: the Sun's centre must be above the horizon at C1, the
+ * peak, or C4. Upstream tests only C1 and C4; the peak keeps a short polar day
+ * inside the eclipse.
+ * ponytail: three samples, not a sunrise search — a day that starts after C1
+ * and ends before the peak still drops. Upgrade path: sunEvents over [c1, c4].
+ */
+function seesAnyOfIt(e) {
+    return e.sunAltDeg.c1 > 0.0 || e.sunAltDeg.peak > 0.0 || e.sunAltDeg.c4 > 0.0;
+}
+/**
+ * The first solar eclipse `observer` can see whose peak falls strictly after
+ * `after`.
+ *
+ * Every new moon up to the end of the supported interval is tested: the
+ * Moon's ecliptic latitude prunes the ones no shadow can reach, and the rest
+ * get a peak-shadow search from the observer. An eclipse whose Sun is below
+ * the horizon at C1, the peak, and C4 is skipped.
+ *
+ * @throws {AlmanacOutOfRangeError} if `after` is outside the supported
+ *      interval, or if no visible eclipse remains before the end of it.
+ * @throws {RangeError} if `after` is invalid or `observer` is out of range.
+ */
+export function nextSolarEclipse(after, observer) {
+    return nearestSolarEclipse(after, 1, observer);
+}
+/**
+ * The last solar eclipse `observer` can see whose peak falls strictly before
+ * `before`, skipping peaks within 100 ms of it, just as `nextSolarEclipse`
+ * does on the other side.
+ *
+ * @throws {AlmanacOutOfRangeError} if `before` is outside the supported
+ *      interval, or if no visible eclipse remains after the start of it.
+ * @throws {RangeError} if `before` is invalid or `observer` is out of range.
+ */
+export function previousSolarEclipse(before, observer) {
+    return nearestSolarEclipse(before, -1, observer);
+}
+/** Solar eclipses `observer` can see with peaks in `[startUtc, endUtc)`, sorted ascending. Contacts may fall outside the window. */
+export function solarEclipses(startUtc, endUtc, observer) {
+    assertSupported(startUtc);
+    assertSupportedWindowEnd(endUtc);
+    assertObserver(observer);
+    return scanSolarEclipses(startUtc.getTime(), endUtc.getTime(), 1, false, observer);
+}
+function nearestSolarEclipse(anchor, direction, observer) {
+    assertSupported(anchor);
+    assertObserver(observer);
+    const ms = anchor.getTime();
+    // No scan limit: walk to the supported boundary. A place can go years
+    // without a visible solar eclipse, and a pruned new moon is cheap.
+    const startMs = direction > 0 ? ms + SAME_ECLIPSE_MS + 1 : SUPPORTED_MIN;
+    const endMs = direction > 0 ? SUPPORTED_MAX : ms - SAME_ECLIPSE_MS;
+    const found = scanSolarEclipses(startMs, endMs, direction, true, observer);
+    if (found.length)
+        return found[0];
+    throw new AlmanacOutOfRangeError();
+}
+function scanSolarEclipses(startMs, endMs, direction, firstOnly, observer) {
+    const found = [];
+    if (startMs >= endMs)
+        return found;
+    // Peak and new moon differ by up to the peak window. Include the entire
+    // margin at both ends, then apply the caller's bounds to the reported peak.
+    const startUt = utDays(new Date(startMs)) - PEAK_WINDOW_DAYS;
+    const endUt = utDays(new Date(endMs)) + PEAK_WINDOW_DAYS;
+    let nmUt = direction > 0 ? startUt : endUt;
+    const limitUt = direction > 0 ? endUt : startUt;
+    while (direction * (limitUt - nmUt) > 0) {
+        const newmoon = searchMoonPhase(0, nmUt, direction * Math.min(40, Math.abs(limitUt - nmUt)));
+        if (newmoon === null)
+            break;
+        // UPSTREAM `SearchLocalSolarEclipse`: step past this new moon before
+        // the next probe, so the same one cannot be found twice.
+        nmUt = newmoon + direction * 10;
+        // Pruning: if the new moon's ecliptic latitude is too large, a solar
+        // eclipse is not possible.
+        if (Math.abs(moonEclipticLatitudeDeg(newmoon)) >= PRUNE_LATITUDE_DEG)
+            continue;
+        // Search near the new moon for the time when the observer is closest
+        // to the line passing through the centers of the Sun and Moon.
+        const shadow = peakLocalMoonShadow(newmoon, observer);
+        if (shadow.r >= shadow.p)
+            continue; // the observer never enters the penumbra
+        const peak = dateFromUt(shadow.ut);
+        if (peak.getTime() < startMs || peak.getTime() >= endMs)
+            continue;
+        // This is at least a partial solar eclipse for the observer.
+        const eclipse = buildSolarEclipse(shadow, observer);
+        // Ignore any eclipse that happens completely at night.
+        if (!seesAnyOfIt(eclipse))
+            continue;
+        found.push(eclipse);
+        if (firstOnly)
+            break;
+    }
+    return found;
+}

package/dist/transforms.d.ts

@@ -23,6 +23,15 @@ export interface TopoUnrefracted extends AltAz {
  * are folded into one multiply here — same value, one division dropped.
  */
 export declare function siderealDeg(ut: number): number;
+/**
+ * UPSTREAM: `geo_pos`, astronomy.ts ~2236 — the observer's geocentric
+ * position in AU on the J2000 mean equator: `terra`'s of-date vector
+ * gyrated into J2000. The topocentric path below avoids this rotation; the
+ * solar-eclipse layer needs it because it subtracts the observer from a
+ * geocentric Moon that stays in EQJ.
+ * INTERNAL: exported for `solar.ts`, not part of the public API.
+ */
+export declare function observerGeoVectorEqj(ut: number, observer: Observer): Vec3;
 /**
  * UPSTREAM: the topocentric path composed of `Equator(body, date, observer,
  * ofdate=true, aberration=true)` (astronomy.ts ~2803) followed by `Horizon`

package/dist/transforms.js

@@ -81,6 +81,17 @@ function observerGeoVectorOfDate(gastDeg, observer) {
         z: ash * sinphi / KM_PER_AU
     };
 }
+/**
+ * UPSTREAM: `geo_pos`, astronomy.ts ~2236 — the observer's geocentric
+ * position in AU on the J2000 mean equator: `terra`'s of-date vector
+ * gyrated into J2000. The topocentric path below avoids this rotation; the
+ * solar-eclipse layer needs it because it subtracts the observer from a
+ * geocentric Moon that stays in EQJ.
+ * INTERNAL: exported for `solar.ts`, not part of the public API.
+ */
+export function observerGeoVectorEqj(ut, observer) {
+    return gyration(observerGeoVectorOfDate(siderealDeg(ut), observer), ttDaysFromUt(ut), PrecessDirection.Into2000);
+}
 /** UPSTREAM: `spin`, astronomy.ts ~2518 — rotate a horizontal-frame unit vector by sidereal angle. */
 function spin(angleDeg, pos) {
     const angr = angleDeg * DEG2RAD;

package/package.json

@@ -1,16 +1,50 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.3.0",
-  "description": "Offline sun & moon engine: positions, rise/set, moon phase, lunar eclipses.",
+  "version": "0.4.0",
+  "description": "Offline sun & moon engine: positions, rise/set, moon phase, lunar and solar eclipses.",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/openwatersio/almanac.git", "directory": "typescript" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openwatersio/almanac.git",
+    "directory": "typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/openwatersio/almanac/issues"
+  },
+  "keywords": [
+    "astronomy",
+    "sun",
+    "moon",
+    "ephemeris",
+    "lunar-eclipse",
+    "solar-eclipse",
+    "marine"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "homepage": "https://openwaters.io/sky",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
-  "files": ["dist", "NOTICE"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
   "//": "index.ts is a curated allow-list: ONLY the spec's public API table is exported — no guards, no L0/L1 internals",
-  "scripts": { "build": "tsc -p tsconfig.json", "test": "vitest run", "prepack": "npm run build && cp ../NOTICE ../LICENSE ../README.md ." },
-  "devDependencies": { "typescript": "^5.5.0", "vitest": "^2.0.0" }
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepack": "npm run build && cp ../NOTICE ../LICENSE ../README.md ."
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  }
 }