panchanga 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hindu Society of North America
+
+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,272 @@
+# panchanga
+
+Drik Panchanga (Smārta, pūrṇimānta) engine for the [HSNA](https://hsna.ca) website.
+
+A dependency-light TypeScript library that computes the Hindu lunisolar calendar —
+the **five aṅgas** (vāra, tithi, nakṣatra, yoga, karaṇa), the lunar month, and
+sidereal / ayanāṁśa values — and resolves **Hindu festival dates**, all from
+astronomical first principles via
+[astronomy-engine](https://github.com/cosinekitty/astronomy). No lookup tables, no
+remote API.
+
+> **Status:** pre-1.0 (`0.1.0`), under active development. The grammar and public API
+> may still change.
+
+## Features
+
+- **The five aṅgas** — vāra (sunrise-to-sunrise weekday), tithi, nakṣatra, yoga, and
+  karaṇa (including Viṣṭi / Bhadra, with its Mukha/Pucchā split and Vāsa), plus the
+  pūrṇimānta / amānta lunar month with adhika (leap) and kṣaya (lost) month detection.
+- **Daily pañcāṅga** — `dailyPanchanga(date, loc)` bundles all five aṅgas (each resolved
+  at sunrise, with its end-time) and the day's sun/moon instants into one record.
+- **Grahaṇa (eclipses)** — solar & lunar eclipse type, contact timings, local visibility,
+  and sūtak windows (9h lunar / 12h solar) for any year and place.
+- **Astronomy primitives** — Lahiri ayanāṁśa (IAU 1976 precession), sidereal longitudes
+  and Sun rāśi, new moons, solar ingress (saṅkrānti).
+- **Time & kāla windows** — timezone/DST-safe sunrise, sunset and moonrise, the muhūrta
+  windows (pūrvāhna, madhyāhna, aparāhna, pradoṣa, niśīta, brahma-muhūrta, …), and the
+  weekday day-part periods **Rāhu Kāla, Yamaganda, Gulika, and Abhijit**.
+- **Festival engine** — a compact rule grammar (`Observance`) and a **pure, testable**
+  pervasion-day selector that resolves ~195 observances to civil dates and **never
+  silently drops**: every miss is explained in `diagnostics`. Selection conventions are
+  first-class — `udaya` vs window-fraction precedence, a `nearest-window` fallback, an
+  `adhika:"prefer-adhika"` leap-month policy, Bhadra exclusion, and nakṣatra- and
+  weekday-anchored festivals (Onam, Varalakṣmī).
+- **Validated at two well-separated longitudes** against Drik Panchang fixtures (2026):
+  **New Delhi** and **Calgary** (the HSNA temple's city). All 24 core festivals and all
+  24 in-year Ekādaśīs match Drik's Calgary calendar exactly, including the −1-day
+  localisation shifts; the handful of remaining differences are convention edges, pinned
+  and documented in the tests.
+
+## Requirements
+
+- **ESM only** (`"type": "module"`) — use `import`, not `require`.
+- **Node.js ≥ 18** to consume (the build targets ES2022). Building/testing from source
+  needs **Node ≥ 22.12** (Vitest 4).
+
+## Install
+
+```sh
+npm install panchanga
+```
+
+## Quick start
+
+### The full pañcāṅga for a day
+
+```ts
+import { dailyPanchanga } from "panchanga";
+import type { GeoLocation } from "panchanga";
+
+const newDelhi: GeoLocation = {
+  latitude: 28.6139,
+  longitude: 77.209,
+  timeZone: "Asia/Kolkata", // IANA tz id
+};
+
+const p = dailyPanchanga(new Date("2026-01-23"), newDelhi);
+
+console.log(p.date, p.vara.name);            // 2026-01-23 Shukravara
+console.log(p.tithi.paksha, p.tithi.name);   // shukla Panchami
+console.log(p.nakshatra.name);               // Purva Bhadrapada
+console.log(p.yoga.name);                    // Parigha
+console.log(p.karana.name);                  // Bava
+console.log(p.month.purnimanta);             // Magha
+console.log(p.muhurta.rahuKala);             // { start: "...Z", end: "...Z" } — Rāhu Kāla
+```
+
+Each running aṅga (tithi, nakṣatra, yoga, karaṇa) is the one **prevailing at sunrise**
+and carries an `endsAt` (ISO-UTC) marking when it gives way to the next; the record also
+includes `sunrise`, `sunset`, `moonrise`, and the day's `muhurta` windows (Rāhu Kāla,
+Yamaganda, Gulika, Abhijit).
+
+### Compute festival dates for a year and location
+
+```ts
+import { computeFestivals, allRules } from "panchanga";
+import type { GeoLocation } from "panchanga";
+
+const newDelhi: GeoLocation = {
+  latitude: 28.6139,
+  longitude: 77.209,
+  timeZone: "Asia/Kolkata", // IANA tz id
+};
+
+const { results, diagnostics } = computeFestivals(2026, newDelhi, {
+  rules: allRules(2026),
+});
+
+for (const f of results) {
+  if (f.date) console.log(f.date, f.id, "—", f.monthLabel.purnimanta);
+}
+// 2026-01-14 makar-sankranti — Magha
+// 2026-03-04 holi            — Chaitra
+// 2026-04-02 hanuman-jayanti — Vaishakha
+// …
+
+// Anything that could not be resolved is explained, never dropped:
+diagnostics.forEach((d) => console.warn(d));
+```
+
+Each [`FestivalResult`](src/types.ts) carries the civil `date` (`YYYY-MM-DD` in `loc`'s
+timezone), a map of key `instants` (tithi start/end, window start/end, …) as ISO-UTC
+strings, both month labels, and per-rule `diagnostics`.
+
+### Read raw calendar elements at an instant
+
+```ts
+import {
+  tithiBoundaries, nakshatraAt, NAKSHATRA_NAMES, karanaAt, lunarMonth,
+} from "panchanga";
+
+const when = new Date("2026-01-23T12:00:00Z");
+
+const tithi = tithiBoundaries(when);          // { number: 1..30, start: Date, end: Date }
+const nak   = NAKSHATRA_NAMES[nakshatraAt(when)];
+const kar   = karanaAt(when);                 // karaṇa name
+const month = lunarMonth(when, { system: "purnimanta" });
+
+console.log(tithi.number, nak, kar, month.purnimantaLabel, month.adhika);
+```
+
+### Sidereal / ayanāṁśa
+
+```ts
+import { ayanamsha, siderealSunRashi } from "panchanga";
+
+const t = new Date("2026-06-24T00:00:00Z");
+ayanamsha(t);        // Lahiri ayanāṁśa in degrees (≈ 24.2° in 2026)
+siderealSunRashi(t); // sidereal rāśi index of the Sun: 0 = Mesha … 11 = Mīna
+```
+
+## API overview
+
+The public surface (see [`src/index.ts`](src/index.ts)) is layered:
+
+**1. Ayanāṁśa & sidereal** — `ayanamsha`, `siderealLongitude`, `siderealSunRashi`,
+`normalize360`, `LAHIRI_ANCHOR_J2000_DEG`.
+
+**2. Time, vāra & kāla windows** — `riseSet`, `moonrise`, `sunset`, `varaAt`,
+`sunriseWindow` / `pratahkala`, `purvahna`, `madhyahna`, `aparahna`, `pradosha`,
+`nishita`, `brahmaMuhurta`, `arunodaya`, `rahuKala`, `yamaganda`, `gulikaKala`,
+`abhijitMuhurta`, `sankrantiPunyaKala`, plus timezone helpers (`localDayString`,
+`startOfLocalDayUTC`, `nextLocalDayStartUTC`) and `VARA_NAMES`. Types: `GeoLocation`,
+`TimeWindow`, `Vara`.
+
+**3. Calendar elements** — `tithiAt`, `tithiBoundaries`, `nakshatraAt`,
+`nakshatraBoundaries`, `yogaAt`, `yogaBoundaries`, `karanaAt`, `karanaIndexAt`,
+`karanaName`, `karanaBoundaries`, `bhadraIntervals`, `bhadraSplit`, `elongation`,
+`newMoons`, `solarIngress`, `lunarMonth`. Name tables: `TITHI_NAMES`, `NAKSHATRA_NAMES`,
+`YOGA_NAMES`, `MOVABLE_KARANAS`, `LUNAR_MONTH_NAMES`.
+
+**4. Daily aggregator** — `dailyPanchanga(date, loc)` → `DailyPanchanga` (the five aṅgas
+at sunrise + sun/moon instants + month label + the day's Rāhu/Yama/Gulika/Abhijit
+muhūrtas).
+
+**4b. Grahaṇa (eclipses)** — `lunarEclipses(year, loc?)`, `solarEclipses(year, loc?)` →
+eclipse type, contact phases (ISO-UTC `IsoWindow`s), local visibility, and sūtak.
+Types: `LunarEclipse`, `SolarEclipse`, `GrahanKind`.
+
+**5. Festival engine** — `computeFestivals`, `computeFestival`, `selectDayByPervasion`
+(the pure selector), and the rule data: `CORE_RULES` plus the generators
+`ekadashiRules`, `sankashtiRules`, `pradoshRules`, `masikShivaratriRules`,
+`purnimaVratRules`, `purnimaSnanaRules`, `amavasyaRules`, `sankrantiRules`, `oneOffFestivalRules`,
+`regionalFestivalRules` (each
+`(year)`), `CHHATH_RULE`, and `allRules(year)`. Grammar types: `Observance`,
+`FestivalRule`, `FestivalResult`, `Kala`, `TithiRef`, `Paksha`. Observance kinds
+include `tithi-pervades` (with `udaya` / `max-window-fraction` precedence, an
+`adhika:"prefer-adhika"` leap-month policy, and a `nearest-window` fallback),
+`solar-ingress`, `moonrise`, `solar-arghya`, `derived`, `nakshatra-pervades`
+(Onam), and `weekday-relative` (Varalakṣmī).
+
+`allRules(year)` covers ~195 observances: the 24 major festivals, every Ekādaśī,
+Sankaṣṭī Caturthī, Pradoṣa Vrata, Masik Śivarātri, Pūrṇimā Vrata (vrat) and Pūrṇimā
+snāna-dāna, Amāvāsyā, all 12 Sankrāntis, Chhath, the HSNA one-offs (Ugadi, the Teej
+trio, Nag Panchami, Rath Yatra, Tulsi Vivah, Anant Chaturdashi, …), and ~21 further
+regional festivals & jayantis (Ratha Saptamī, Narasimha/Paraśurāma/Sītā/Gaṅgā jayantis,
+Vat Sāvitrī, Vishwakarma, Kālī Chaudas, Onam, Varalakṣmī, …) — validated against Drik
+Panchang's New Delhi and Calgary calendars (residual cases are ±1-day convention edges,
+pinned in the tests).
+
+## The rule grammar
+
+A festival is authored as a [`FestivalRule`](src/types.ts) whose `observance.kind`
+declares how its civil date is resolved:
+
+| `kind` | Resolves by | Examples |
+|---|---|---|
+| `tithi-pervades` | A tithi pervading a kāla window on the chosen day, picked by a `precedence` policy (`max-window-fraction`, `udaya`, `first`, `second`). Optional `nakshatra` filter, `avoidKarana: "vishti"` (Bhadra), `adhika: "prefer-adhika"` (leap-month policy), and a `fallback` (`previous-day` / `next-day` / `nearest-window`) | most lunar festivals |
+| `solar-ingress` | The Sun's sidereal ingress into a rāśi | Makar Saṅkrānti, Vishwakarma |
+| `moonrise` | Tithi live at moonrise | Karva Chauth, Sankaṣṭī |
+| `solar-arghya` | Tithi at sunset and the next sunrise | Chhath |
+| `derived` | An offset from another festival | Holi = Holikā + 1 |
+| `nakshatra-pervades` | The day a named nakṣatra is at sunrise while the Sun is in a given rāśi | Onam (Śravaṇa in Siṃha) |
+| `weekday-relative` | The latest weekday before another festival's date | Varalakṣmī (Friday before Śrāvaṇa Pūrṇimā) |
+
+`allRules(year)` returns `CORE_RULES` plus every recurring and regional observance
+generated for that year (see the generators listed under **API overview → 5**).
+
+## Scope of validation
+
+This package computes panchanga values via `astronomy-engine` and is validated for
+conformance to Drik Panchang (Smārta, pūrṇimānta) for the locations and years covered by
+`test/fixtures`. It has **not** been independently verified by a traditional pandit or
+Jyotisha authority — verify computed values against your local authority before ritual
+use.
+
+## Development
+
+```sh
+npm install      # install dependencies
+npm test         # vitest run — unit suites + Drik-Panchang conformance
+npm run build    # tsc → dist/ (ESM .js + .d.ts + source/declaration maps)
+```
+
+Tests live in `test/` (~370 cases): per-module unit suites plus the Drik-Panchang
+conformance checks — `conformance.test.ts` (2026 New Delhi) and **five Calgary suites**
+(the HSNA temple's city) whose EXPECTED dates are transcribed from Drik Panchang's Calgary
+calendar (geoname-id 5913490): `conformance-calgary.test.ts` (24 core festivals),
+`-vratas` (Ekādaśī, Saṅkaṣṭī, Pūrṇimā vrat & snāna, Amāvāsyā, minor Saṅkrāntis), `-oneoff`
+(HSNA regional festivals) and `-regional` (21 further festivals/jayantis incl. Onam &
+Varalakṣmī). All 24 core festivals and all 24 in-year Ekādaśīs match Drik Calgary exactly;
+the few remaining ±1 convention edges and definitional differences are pinned and
+documented. The suites also assert the **localisation invariant** — every Calgary date is
+within ±1 day of New Delhi — which is what catches a wrong convention (a single locale
+can't, since many conventions agree there).
+
+## Known convention edges
+
+Most differences from Drik Panchang are not errors — they are points where the tradition
+itself admits more than one reckoning, or where the engine intentionally follows HSNA. The
+ones to be aware of:
+
+- **Pūrṇimā / Amāvāsyā — vrat vs snāna.** `purnima-vrat-*` is the *moonrise* vrat day;
+  `purnima-snana-*` is the next-morning *snāna-dāna* day Drik lists as "X Purnima". At
+  far-western longitudes these are usually one civil day apart — both are correct, for
+  different observances.
+- **Gauṇa (Vaiṣṇava) Ekādaśī — not yet emitted.** When an Ekādaśī is Daśamī-viddha,
+  Vaiṣṇavas fast the next day ("Gauṇa"). The engine emits only the Smārta date; the
+  second-day reckoning is future work.
+- **Ganga Dussehra, Balram Jayanti — definitional, follow HSNA.** Ganga Dussehra uses the
+  adhika Jyeṣṭha when present (matching Drik); Balram Jayanti follows HSNA's Kṛṣṇa-Ṣaṣṭhī
+  rather than Drik's Śukla-Ṣaṣṭhī.
+- **Maha Navami (Durga) — Sandhi rule, +1 known diff.** Drik can place Navamī on the
+  Aṣṭamī-udaya day via the Sandhi-Pūjā convention, which the generic tithi grammar does
+  not express.
+- **Pinned ±1 edges:** Kārtika Pūrṇimā snāna, Sarva-Pitṛ Amāvāsyā, Mithuna Saṅkrānti,
+  Phulera Dooj, Hariyali Teej / Nag Panchami / Kansh Vadh (New Delhi). Each is a two-day
+  tithi straddling sunrise where the day-attribution convention is genuinely borderline;
+  the tests pin the produced date so any change is surfaced consciously.
+
+## Tech stack
+
+- **Language:** TypeScript 6 (`strict`), ES2022 target, NodeNext modules, ESM-only.
+- **Runtime dependency:** [`astronomy-engine`](https://github.com/cosinekitty/astronomy)
+  — the only one; provides ephemeris (Sun/Moon position, rise/set, moon-phase search,
+  precession).
+- **Tooling:** `tsc` for the build, [Vitest](https://vitest.dev) 4 for tests. No bundler,
+  linter, or CI.
+
+## License
+
+MIT © 2026 Hindu Society of North America

package/dist/ayanamsha.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Lahiri (Chitrapakṣa) ayanāṁśa and sidereal longitudes.
+ *
+ * MODEL
+ * -----
+ * Lahiri ayanāṁśa = a canonical constant anchor at J2000.0 plus the accumulated
+ * **general precession in longitude** from J2000.0 to the date, computed with the
+ * **IAU 1976 (Lieske et al. 1977)** precession series. This is the same polynomial
+ * given by Meeus, *Astronomical Algorithms* (2nd ed.), ch. 21 ("Precession"), for
+ * the precession of ecliptical coordinates — Meeus' general-precession-in-longitude
+ * polynomial IS the IAU 1976 series.
+ *
+ *   ayanāṁśa(T) = 23.853222° + pA(T)
+ *
+ * where T is the time in Julian centuries of Terrestrial Time (TT) from J2000.0 and
+ * pA(T) is the accumulated general precession in longitude in degrees.
+ *
+ * ANCHOR
+ * ------
+ * At J2000.0 the mean Lahiri ayanāṁśa is **23.853222°**. This is the canonical
+ * Swiss Ephemeris `SE_SIDM_LAHIRI` / ICRC value, expressed as the Swiss Ephemeris
+ * user-defined mode `swe_set_sid_mode(SE_SIDM_USER, 2451545.0, 23.853222)`. Official
+ * Lahiri is "an arbitrary value at an arbitrary epoch propagated by IAU 1976
+ * precession" — it is NOT a distinct precession series. There is no festival-date
+ * tuning here; the anchor and series are fixed.
+ *
+ * PRECESSION SERIES (IAU 1976 / Meeus ch. 21), referred to J2000.0 (arcseconds):
+ *
+ *   pA(T) = 5029.0966″·T + 1.11113″·T² − 0.000006″·T³
+ *
+ * The leading coefficient, 5029.0966″/Julian century, is the IAU 1976 rate of
+ * general precession in longitude at J2000.0 (Lieske et al. 1977,
+ * A&A 58, 1). (In Meeus' general two-epoch form the T² and T³ coefficients also
+ * carry T₀ terms; with the fixed reference epoch J2000.0, T₀ = 0 and they drop out.)
+ *
+ * MEAN vs TRUE
+ * ------------
+ * The **mean** ayanāṁśa (precession only) is the core. It matches published Lahiri
+ * tables and is what the frozen reference values are checked against.
+ *
+ * Drik Panchang and most published "display" panchāngas use the **true** ("with
+ * nutation") ayanāṁśa: mean + nutation in longitude Δψ. Pass `{ nutation: true }`
+ * to get it. The nutation amplitude is ≤ ~17″ (< 0.3 arcmin), so either value
+ * satisfies the < 1 arcmin reference tolerance, but the two are distinct and the
+ * caller chooses. Festival-date code will pass `{ nutation: true }`.
+ */
+import { Body, type FlexibleDateTime } from "astronomy-engine";
+/** Canonical Lahiri anchor: mean ayanāṁśa at J2000.0, in degrees. */
+export declare const LAHIRI_ANCHOR_J2000_DEG = 23.853222;
+export interface AyanamshaOptions {
+    /**
+     * When true, add nutation in longitude Δψ to obtain the **true** ("with
+     * nutation") ayanāṁśa used for display (e.g. Drik Panchang). Default false
+     * (mean ayanāṁśa, precession only).
+     */
+    nutation?: boolean;
+}
+/**
+ * Lahiri (Chitrapakṣa) ayanāṁśa in degrees for the given instant.
+ *
+ * Mean by default (precession only). Pass `{ nutation: true }` for the true
+ * ("with nutation") value.
+ */
+export declare function ayanamsha(date: FlexibleDateTime, options?: AyanamshaOptions): number;
+/** Normalize an angle in degrees into the range [0, 360). */
+export declare function normalize360(deg: number): number;
+/**
+ * Sidereal (Lahiri) ecliptic longitude of a body, in degrees, normalized to
+ * [0, 360).
+ *
+ *   sidereal = tropical-of-date − ayanāṁśa(date)
+ *
+ * Both the tropical longitude (from astronomy-engine) and the ayanāṁśa here use
+ * the **true** equinox of date: the tropical longitudes are apparent
+ * (true-ecliptic-of-date), so we subtract the **true** ayanāṁśa (with nutation)
+ * to keep the equinox definition consistent on both sides.
+ */
+export declare function siderealLongitude(date: FlexibleDateTime, body: Body): number;
+/**
+ * Sidereal solar rāśi (zodiac sign) index, 0..11.
+ * 0 = Meṣa (Aries), 1 = Vṛṣabha, …, 11 = Mīna (Pisces).
+ */
+export declare function siderealSunRashi(date: FlexibleDateTime): number;
+//# sourceMappingURL=ayanamsha.d.ts.map

package/dist/ayanamsha.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ayanamsha.d.ts","sourceRoot":"","sources":["../src/ayanamsha.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAML,IAAI,EACJ,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAE1B,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,YAAY,CAAC;AAKjD,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAaD;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,gBAAgB,EACtB,OAAO,GAAE,gBAAqB,GAC7B,MAAM,CAWR;AAED,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGhD;AAqBD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,IAAI,GACT,MAAM,CAIR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAE/D"}

package/dist/ayanamsha.js

@@ -0,0 +1,124 @@
+/**
+ * Lahiri (Chitrapakṣa) ayanāṁśa and sidereal longitudes.
+ *
+ * MODEL
+ * -----
+ * Lahiri ayanāṁśa = a canonical constant anchor at J2000.0 plus the accumulated
+ * **general precession in longitude** from J2000.0 to the date, computed with the
+ * **IAU 1976 (Lieske et al. 1977)** precession series. This is the same polynomial
+ * given by Meeus, *Astronomical Algorithms* (2nd ed.), ch. 21 ("Precession"), for
+ * the precession of ecliptical coordinates — Meeus' general-precession-in-longitude
+ * polynomial IS the IAU 1976 series.
+ *
+ *   ayanāṁśa(T) = 23.853222° + pA(T)
+ *
+ * where T is the time in Julian centuries of Terrestrial Time (TT) from J2000.0 and
+ * pA(T) is the accumulated general precession in longitude in degrees.
+ *
+ * ANCHOR
+ * ------
+ * At J2000.0 the mean Lahiri ayanāṁśa is **23.853222°**. This is the canonical
+ * Swiss Ephemeris `SE_SIDM_LAHIRI` / ICRC value, expressed as the Swiss Ephemeris
+ * user-defined mode `swe_set_sid_mode(SE_SIDM_USER, 2451545.0, 23.853222)`. Official
+ * Lahiri is "an arbitrary value at an arbitrary epoch propagated by IAU 1976
+ * precession" — it is NOT a distinct precession series. There is no festival-date
+ * tuning here; the anchor and series are fixed.
+ *
+ * PRECESSION SERIES (IAU 1976 / Meeus ch. 21), referred to J2000.0 (arcseconds):
+ *
+ *   pA(T) = 5029.0966″·T + 1.11113″·T² − 0.000006″·T³
+ *
+ * The leading coefficient, 5029.0966″/Julian century, is the IAU 1976 rate of
+ * general precession in longitude at J2000.0 (Lieske et al. 1977,
+ * A&A 58, 1). (In Meeus' general two-epoch form the T² and T³ coefficients also
+ * carry T₀ terms; with the fixed reference epoch J2000.0, T₀ = 0 and they drop out.)
+ *
+ * MEAN vs TRUE
+ * ------------
+ * The **mean** ayanāṁśa (precession only) is the core. It matches published Lahiri
+ * tables and is what the frozen reference values are checked against.
+ *
+ * Drik Panchang and most published "display" panchāngas use the **true** ("with
+ * nutation") ayanāṁśa: mean + nutation in longitude Δψ. Pass `{ nutation: true }`
+ * to get it. The nutation amplitude is ≤ ~17″ (< 0.3 arcmin), so either value
+ * satisfies the < 1 arcmin reference tolerance, but the two are distinct and the
+ * caller chooses. Festival-date code will pass `{ nutation: true }`.
+ */
+import { MakeTime, SunPosition, GeoVector, Ecliptic, e_tilt, Body, } from "astronomy-engine";
+/** Canonical Lahiri anchor: mean ayanāṁśa at J2000.0, in degrees. */
+export const LAHIRI_ANCHOR_J2000_DEG = 23.853222;
+/** Julian days per Julian century. */
+const DAYS_PER_CENTURY = 36525;
+/**
+ * Accumulated general precession in longitude pA(T), IAU 1976 / Meeus ch. 21,
+ * referred to J2000.0.
+ *
+ * @param T time in Julian centuries (TT) from J2000.0
+ * @returns pA in arcseconds
+ */
+function accumulatedPrecessionArcsec(T) {
+    return 5029.0966 * T + 1.11113 * T * T - 0.000006 * T * T * T;
+}
+/**
+ * Lahiri (Chitrapakṣa) ayanāṁśa in degrees for the given instant.
+ *
+ * Mean by default (precession only). Pass `{ nutation: true }` for the true
+ * ("with nutation") value.
+ */
+export function ayanamsha(date, options = {}) {
+    const time = MakeTime(date);
+    const T = time.tt / DAYS_PER_CENTURY; // Julian centuries TT from J2000.0
+    let result = LAHIRI_ANCHOR_J2000_DEG + accumulatedPrecessionArcsec(T) / 3600;
+    if (options.nutation) {
+        // e_tilt(...).dpsi is nutation in longitude Δψ in arcseconds (IAU 2000B).
+        result += e_tilt(time).dpsi / 3600;
+    }
+    return result;
+}
+/** Normalize an angle in degrees into the range [0, 360). */
+export function normalize360(deg) {
+    const r = deg % 360;
+    return r < 0 ? r + 360 : r;
+}
+/**
+ * Tropical ecliptic longitude **of date** (true equinox of date, apparent) of a
+ * body, in degrees.
+ *
+ * - Sun: `SunPosition(date).elon` — apparent geocentric true-ecliptic-of-date
+ *   longitude (precession + nutation applied).
+ * - Other bodies: `Ecliptic(GeoVector(body, date, true)).elon` — geocentric
+ *   apparent (aberration-corrected) vector rotated to the true ecliptic of date.
+ *
+ * Both are referred to the **true** (nutating) equinox of date, so they pair
+ * consistently with the **true** ayanāṁśa.
+ */
+function tropicalLongitudeOfDate(date, body) {
+    if (body === Body.Sun) {
+        return SunPosition(date).elon;
+    }
+    return Ecliptic(GeoVector(body, date, /* aberration */ true)).elon;
+}
+/**
+ * Sidereal (Lahiri) ecliptic longitude of a body, in degrees, normalized to
+ * [0, 360).
+ *
+ *   sidereal = tropical-of-date − ayanāṁśa(date)
+ *
+ * Both the tropical longitude (from astronomy-engine) and the ayanāṁśa here use
+ * the **true** equinox of date: the tropical longitudes are apparent
+ * (true-ecliptic-of-date), so we subtract the **true** ayanāṁśa (with nutation)
+ * to keep the equinox definition consistent on both sides.
+ */
+export function siderealLongitude(date, body) {
+    const tropical = tropicalLongitudeOfDate(date, body);
+    const ayan = ayanamsha(date, { nutation: true });
+    return normalize360(tropical - ayan);
+}
+/**
+ * Sidereal solar rāśi (zodiac sign) index, 0..11.
+ * 0 = Meṣa (Aries), 1 = Vṛṣabha, …, 11 = Mīna (Pisces).
+ */
+export function siderealSunRashi(date) {
+    return Math.floor(siderealLongitude(date, Body.Sun) / 30);
+}
+//# sourceMappingURL=ayanamsha.js.map

package/dist/ayanamsha.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ayanamsha.js","sourceRoot":"","sources":["../src/ayanamsha.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EACL,QAAQ,EACR,WAAW,EACX,SAAS,EACT,QAAQ,EACR,MAAM,EACN,IAAI,GAEL,MAAM,kBAAkB,CAAC;AAE1B,qEAAqE;AACrE,MAAM,CAAC,MAAM,uBAAuB,GAAG,SAAS,CAAC;AAEjD,sCAAsC;AACtC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAW/B;;;;;;GAMG;AACH,SAAS,2BAA2B,CAAC,CAAS;IAC5C,OAAO,SAAS,GAAG,CAAC,GAAG,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,QAAQ,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAChE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,IAAsB,EACtB,UAA4B,EAAE;IAE9B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,gBAAgB,CAAC,CAAC,mCAAmC;IACzE,IAAI,MAAM,GAAG,uBAAuB,GAAG,2BAA2B,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE7E,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,0EAA0E;QAC1E,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC;IACrC,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC;IACpB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,uBAAuB,CAAC,IAAsB,EAAE,IAAU;IACjE,IAAI,IAAI,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;QACtB,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;IAChC,CAAC;IACD,OAAO,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACrE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAsB,EACtB,IAAU;IAEV,MAAM,QAAQ,GAAG,uBAAuB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,OAAO,YAAY,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAsB;IACrD,OAAO,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;AAC5D,CAAC"}

package/dist/eclipses.d.ts

@@ -0,0 +1,58 @@
+/**
+ * src/eclipses.ts — grahaṇa (solar & lunar eclipses).
+ *
+ * Wraps astronomy-engine's eclipse search to enumerate the eclipses of a given
+ * year, with their contact timings, type, local visibility, and sūtak window.
+ *
+ * Conventions:
+ *  • A grahaṇa "counts" for a location only when it is VISIBLE there — a lunar
+ *    eclipse when the Moon is above the horizon during the umbral/penumbral
+ *    phase, a solar eclipse when the Sun is above the horizon and the disc is
+ *    obscured. Sūtak (the abstention period) applies only to a visible eclipse.
+ *  • Sūtak begins before first contact: 9 hours (3 prahara) for a Chandra
+ *    Grahaṇa, 12 hours (4 prahara) for a Sūrya Grahaṇa, and runs to mokṣa (last
+ *    contact). This is the widely-used Smārta convention.
+ *
+ * Timings are UTC instants. Lunar contact times are derived from the eclipse
+ * peak and astronomy-engine's semi-durations (sd_*, in minutes).
+ */
+import { type GeoLocation, type IsoWindow } from "./time.js";
+/**
+ * Eclipse type (grahaṇa kind), as a local string union so consumers can name
+ * the discriminant without reaching into the `astronomy-engine` dependency.
+ */
+export type GrahanKind = "penumbral" | "partial" | "total" | "annular";
+export interface LunarEclipse {
+    kind: GrahanKind;
+    /** ISO-UTC instant of greatest eclipse. */
+    peak: string;
+    penumbral: IsoWindow;
+    /** Umbral partial phase; null for a penumbral-only eclipse. */
+    partial: IsoWindow | null;
+    /** Totality; null unless the eclipse is total. */
+    total: IsoWindow | null;
+    /** Whether the Moon is above the horizon at peak in `loc` (null if no loc). */
+    visible: boolean | null;
+    /** Sūtak window (9h before umbral first contact → mokṣa) when visible; else null. */
+    sutak: IsoWindow | null;
+}
+export interface SolarEclipse {
+    kind: GrahanKind;
+    /** ISO-UTC instant of greatest eclipse (global). */
+    peak: string;
+    /** Local circumstances at `loc` when the eclipse is seen there; else null. */
+    local: {
+        partialStart: string;
+        peak: string;
+        partialEnd: string;
+        obscuration: number;
+    } | null;
+    visible: boolean | null;
+    /** Sūtak window (12h before local first contact → last contact); else null. */
+    sutak: IsoWindow | null;
+}
+/** All lunar eclipses whose peak falls in calendar `year` (UTC). */
+export declare function lunarEclipses(year: number, loc?: GeoLocation): LunarEclipse[];
+/** All solar eclipses whose greatest-eclipse instant falls in calendar `year`. */
+export declare function solarEclipses(year: number, loc?: GeoLocation): SolarEclipse[];
+//# sourceMappingURL=eclipses.d.ts.map

package/dist/eclipses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eclipses.d.ts","sourceRoot":"","sources":["../src/eclipses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAeH,OAAO,EAAoB,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAQ/E;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAIvE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,SAAS,CAAC;IACrB,+DAA+D;IAC/D,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IAC1B,kDAAkD;IAClD,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,+EAA+E;IAC/E,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,qFAAqF;IACrF,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9F,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,+EAA+E;IAC/E,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CACzB;AA4BD,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,YAAY,EAAE,CA6C7E;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,YAAY,EAAE,CAuC7E"}