panchang-ts 5.1.1 → 5.2.0

package/README.md

@@ -6,12 +6,16 @@
 Pure TypeScript Hindu Panchang (almanac), Jyotish, and Birth Chart calculations.
 Zero runtime dependencies. Works offline in React Native (Hermes), Node.js, and browsers.
 
-**Fast** (~0.25 ms trimmed, ~0.41 ms full) · **Typed** (full TypeScript) · **Offline** (pure JS math) · **8,772 tests across 137 files**
+**Fast** (~0.25 ms trimmed, ~0.41 ms full) · **Typed** (full TypeScript) · **Offline** (pure JS math) · **8,805 tests across 138 files**
 
 > 📖 **Full documentation: [dharmagya.app/docs/panchang-ts](https://dharmagya.app/docs/panchang-ts)**
-> This README covers install, quick start, and the 5.0 → 5.1 and 4.x → 5 migrations in full,
-> plus a per-feature quick reference. The complete reference — every option, result field,
-> table format, accuracy bound and performance note — lives on the docs site.
+> This README covers install, quick start, and the 5.1 → 5.2, 5.0 → 5.1 and 4.x → 5 migrations
+> in full, plus a per-feature quick reference. The complete reference (every option, result field,
+> table format, accuracy bound and performance note) lives on the docs site.
+
+A Go port of the same engine ships from the same repository, held to this package's
+exact arithmetic by a parity harness. See
+[the repository](https://github.com/ishankgupta95/panchang-ts) if you need it.
 
 ---
 
@@ -46,12 +50,12 @@ console.log(result!.calendar.samvat.vikramSamvat);     // 2081
 
 ### Reading Output Times
 
-Every `Date` in a result is a **real instant** — `.getTime()` is the correct
+Every `Date` in a result is a **real instant**: `.getTime()` is the correct
 epoch millisecond. Every instant has a `*Local` companion: an offset-carrying
 ISO 8601 string, which is what you want for display.
 
 ```typescript
-result!.sun.rise;            // Date — 2025-01-14T01:39:44.172Z (the actual moment)
+result!.sun.rise;            // Date: 2025-01-14T01:39:44.172Z (the actual moment)
 result!.sun.riseLocal;       // "2025-01-14T07:09:44.172+05:30"
 result!.inauspicious.rahuKalam.start;    // Date
 result!.inauspicious.rahuKalam.startLocal;
@@ -73,7 +77,7 @@ const noon = new Date((result!.sun.rise.getTime() + result!.sun.set.getTime()) /
 formatInZone(noon, result!.timezone.offsetMinutes);  // "2025-01-14T12:27:31.086+05:30"
 ```
 
-> **Changed in v5 — this is the breaking change most likely to affect you.**
+> **Changed in v5. This is the breaking change most likely to affect you.**
 > Through 4.x every published `Date` was the true instant *shifted* by the UTC
 > offset, and the README told you to read it back with `getUTC*`. That worked
 > only as long as you did nothing else with the value: `JSON.stringify` emitted
@@ -84,7 +88,7 @@ formatInZone(noon, result!.timezone.offsetMinutes);  // "2025-01-14T12:27:31.086
 > Migration is mechanical: `x.getUTCHours()` → read `xLocal`, or format the
 > instant. See [Upgrading from 4.x](#upgrading-from-4x).
 
-`moon.rise` / `moon.set` can be `null` — the Moon occasionally does not rise or
+`moon.rise` / `moon.set` can be `null`: the Moon occasionally does not rise or
 set on a given calendar day, which is normal. `moon.riseLocal` / `moon.setLocal`
 are `null` exactly when they are.
 
@@ -97,7 +101,7 @@ Through 4.x it was ~50 flat fields; the groups are what tell you where to look.
 |---|---|
 | `sun` | `rise` / `set` / `nextRise` (+ `*Local`), day and night lengths, the Sun's `siderealLongitude` and `nakshatra` |
 | `moon` | `rise` / `set` (+ `*Local`), the Moon's `siderealLongitude` and `rashi` |
-| `angas` | the five limbs — `tithis`, `nakshatras`, `yogas`, `karanas`, `vara` |
+| `angas` | the five limbs: `tithis`, `nakshatras`, `yogas`, `karanas`, `vara` |
 | `calendar` | `masa` (solar), `chandramasa` (lunar), `samvat` |
 | `muhurtas` | `abhijit`, `brahma`, `vijaya`, `godhuli`, `nishita`, `amritKala`, `madhyahna`, `pratahSandhya`, `sayahnaSandhya`, `doGhati` |
 | `inauspicious` | `rahuKalam`, `gulikaKalam`, `yamaganda`, `durMuhurta`, `varjyam`, `bhadra`, `gandaMula`, `panchaka`, `panchakaInfo`, `panchakaRahita` |
@@ -109,7 +113,7 @@ Top level: `date`, `location`, `timezone`, `ayanamsa`, `specialYogas`,
 **Nothing is optional.** Every field is always present. A value that does not
 apply is `null`; a collection that does not apply is `[]`. That holds whether
 the reason is the domain (no Bhadra window today) or your options (you did not
-pass `janmaRashi`, so `chandraBalam` is `null`) — the result *shape* never
+pass `janmaRashi`, so `chandraBalam` is `null`). The result *shape* never
 depends on what you passed.
 
 `getInstantPanchang` uses the same group names for the subset an instant can
@@ -124,32 +128,148 @@ answer: `sun`, `moon`, `angas`, `calendar`, `inauspicious`. There is no
 | Single-moment snapshot ("what's active right now?") or birth-chart casting | `getInstantPanchang` |
 
 `getInstantPanchang` emits a `festivals` field but only checks rule predicates
-at the given instant — it skips canonical-time refinements (madhyahna /
+at the given instant: it skips canonical-time refinements (madhyahna /
 pradosha / nishita / chandrodaya), transit-based Sankranti, and Smarta/Vaishnava
 Ekadashi split. For reliable festival dating, use `getDailyPanchang`.
 
+### If you have no location
+
+`location` is required and stays required. Nothing here silently guesses where you are, because a
+panchang computed for the wrong place does not look wrong: it returns a complete, plausible result
+with some dates off by one.
+
+There are three reference frames, and a result is always in one of them:
+
+| frame | point | when |
+|---|---|---|
+| `practical` | the location you passed | you have real coordinates. The only frame correct for a real user |
+| `traditional` | **Ujjain** 23.1765N, 75.7885E | the classical madhya rekha of the Surya Siddhanta. The default |
+| `modern` | **Central Station** 23.1833N, 82.5E | the 1955 Calendar Reform Committee reference for the Rashtriya Panchang |
+
+Why the frame matters at all: a tithi, nakshatra, yoga or karana **ends at one instant worldwide**.
+Only the civil day it gets labelled with depends on your sunrise, along with everything else
+rise/set derived (rahu kalam, choghadiya, pradosha, nishita, moonrise anchors).
+
+```typescript
+import { getDailyPanchang, resolveLocation, IST_OFFSET_MINUTES } from 'panchang-ts';
+
+// maybeLocation may be undefined; traditional (Ujjain) is the default frame
+const { location, reference } = resolveLocation(maybeLocation);
+const day = getDailyPanchang(date, location, { timezone: IST_OFFSET_MINUTES });
+
+if (reference !== 'practical') {
+  // say so, the way a printed panchang names the city it was computed for
+  console.info(`Computed for the ${reference} reference, not your location.`);
+}
+```
+
+Pass `'modern'` as the second argument to fall back to the Central Station instead, or use
+`referenceLocation('traditional' | 'modern')` if you only want the point. `'practical'` is
+reported, never selected: passing a location is what makes a result practical.
+
+**Price the fallbacks before you rely on them.** Measured over 730 days against 48 Indian cities,
+the tithi at the reference's sunrise differs from the city's own on up to **5.9% of days** for
+Ujjain and **4.0%** for the Central Station. Ujjain is the better of the two for most users
+(population-weighted 1.18% against 1.80%, since India's metros lie west of the IST meridian) and
+the worse in the tail. Outside India both degrade without limit.
+
+`IST_OFFSET_MINUTES` (330) is exact for the Central Station, whose longitude is the IST meridian.
+For Ujjain it is the civil clock rather than its local mean time, which is 303.2 minutes; the
+26.8-minute gap is what the classical deshantara correction exists to close.
+
+A half-filled location throws rather than being completed from a reference point, and
+`{ latitude: 0, longitude: 0 }` is treated as the real place it is, not as missing.
+
+Note that the shipped static tables (`panchang-ts/festivals`, `/eclipses`, `/muhurta`) are
+pre-computed for Varanasi, which is a fourth point again.
+
+---
+
+## Upgrading to 5.2
+
+No type breaks and no removed exports. What changes is output: a set of dates that
+were wrong, or missing entirely, are now right. If you cache festival dates, diff
+them against a rebuild before you ship, and key on `festivals[].key` rather than on
+the label, because 27 user-visible strings changed punctuation in both `en` and `hi`.
+
+### Festivals that used to vanish for a whole year now appear
+
+A tithi that begins and ends between two consecutive sunrises is current at no
+sunrise. A rule keyed on the sunrise tithi matched it on no day of the year, so the
+festival disappeared from that year entirely. Ugadi and Gudi Padwa were absent from
+2026 at every location; Navaratri 2027, Gangaur 2025, both Teejes, Govardhan Puja,
+Bhai Dooj, Anant Chaturdashi, Kartika Purnima and Chhath Kharna were missing at some
+cities and present at others. The Hindu day that wholly contains the tithi now claims it, which
+is what the reference almanac publishes.
+
+Measured over eight Indian cities across 2020 to 2030: **87 dates added, and no
+existing date moves.** Every addition belongs to a city and year where the festival
+previously had no date at all, so nothing is rescheduled.
+
+Four festivals are deliberately left out, because the reference does not put them on
+the containing day: Narak Chaturdashi and Chhath Usha Arghya, which it publishes on
+the day the tithi ends, and Holi and Phagli, which are anchored to pradosha.
+
+### Three festivals move to a different date
+
+These are the ones to diff for. They are corrections, not additions.
+
+| festival | was | now |
+|---|---|---|
+| Vat Savitri Amavasya | roughly 30 days late, every year | 7 of 7 checked years match the reference |
+| Rig Upakarma | 9 of 13 checked years right | 13 of 13 |
+| Sama Upakarma | 4 of 13 checked years right | 13 of 13 |
+
+Vat Savitri Amavasya was filed under the wrong lunar month. The vrat falls on
+purnimanta Jyeshtha Amavasya, and an amavasya ends its amanta month, so the two
+namings sit a month apart; the rule had been selecting the following new moon since
+the festival was added. It is now also anchored to aparahna rather than sunrise, with
+the later day taking a span that reaches aparahna twice. `vat_savitri_purnima` is
+unaffected and still correct, because a purnima sits inside the amanta month it names.
+
+Both Upakarma rules matched on the nakshatra at sunrise and nothing else. Sama
+Upakarma fired a **second** time in six of thirteen years, on the Bhadrapada Krishna
+Amavasya that carries Hasta again, and was a day late in five more. Rig Upakarma
+emitted two dates when its nakshatra spanned two sunrises (2019, 2029), a date in the
+wrong paksha when the nakshatra slipped into Krishna (2020), and nothing at all in
+the one year it fell outside Shukla paksha entirely (2022). Both now emit exactly one date in all 88
+city-years of the eight-city sweep. Sama Upakarma is anchored to aparahna and is
+therefore longitude sensitive: in 2026 it is the 13th of September at Kolkata and the
+12th elsewhere, which is what the reference publishes.
+
+### Numbers that changed
+
+`getUpcomingSolarEclipse` did not check that an eclipse ended after the instant it
+was asked to search from, so range walkers could return the same eclipse repeatedly
+and drop others. `computeEclipsesInRange(2000 to 2011, Varanasi)` returned 277
+entries of which 249 were one 2007 partial; it now returns 32 distinct entries.
+Shadbala Kala Bala is now anchored to the preceding sunrise rather than the following
+one, moving 1009 of 2016 sampled births. Narayan dasha durations exclude adjacent
+signs from rasi drishti. Gulika and Mandi use a day/night test that matches their own
+definition.
+
 ---
 
-## Upgrading to 5.1 — part 2
+## Upgrading to 5.1, part 2
 
 Two deliberate type breaks, both correcting fields that did not match
-DrikPanchang (the project's parity oracle), in the same style as part 1's
+the reference almanac (the project's parity oracle), in the same style as part 1's
 `varjyam` break.
 
 ### `inauspicious.durMuhurta` is now `DurMuhurtaPeriod[]`
 
 ```diff
 - const [dm1, dm2] = r.inauspicious.durMuhurta;
-+ r.inauspicious.durMuhurta.forEach((dm) => show(dm)); // 1–2 windows
++ r.inauspicious.durMuhurta.forEach((dm) => show(dm)); // 1-2 windows
 + // dm.segment is 'day' or 'night' (only Tuesday carries a night window)
 ```
 
-The old table emitted two day windows every day and matched drik on none of
+The old table emitted two day windows every day and matched the almanac on none of
 the seven weekdays. The corrected classical Muhurta-Chintamani table gives
-one window on Sunday and Wednesday, two elsewhere — and Tuesday's second
+one window on Sunday and Wednesday, two elsewhere, and Tuesday's second
 window falls at **night** (the 7th of the 15 sunset→sunrise muhurtas), so
 the exactly-two-day-windows tuple could not survive. Verified against 58
-consecutive drik day-pages across two cities; a full drik week is pinned.
+consecutive almanac day-pages across two cities; a full almanac week is pinned.
 
 ### `muhurtas.amritKala` is now `TimePeriod[]`
 
@@ -158,18 +278,18 @@ consecutive drik day-pages across two cities; a full drik week is pinned.
 + r.muhurtas.amritKala.forEach(show);   // [] when the day has none
 ```
 
-Amrit Kala shares Varjyam's architecture (drik prints them from the same
+Amrit Kala shares Varjyam's architecture (the almanac prints them from the same
 frame): each window anchors at its nakshatra's own start, offset by a
 per-nakshatra count of nakshatra-elastic ghatikas, spans exactly 4 such
-ghatikas, and belongs to the Hindu day its **start** falls in — 0–2 windows
-per day. The old sunrise-anchored single window disagreed with drik by up
+ghatikas, and belongs to the Hindu day its **start** falls in (0-2 windows
+per day). The old sunrise-anchored single window disagreed with the almanac by up
 to ~16 h. `computeAmritKala` is replaced by
 `computeAmritKalaWindows(sunriseUtc, nextSunriseUtc, getMoon)`.
 
 ### Ekadashi splits: Smarta first, Vaishnava second
 
-On the days drik prints an Ekadashi twice, the **earlier** day is the Smarta
-fast and the **later** one the Vaishnava fast — drik says so in prose on every
+On the days the almanac prints an Ekadashi twice, the **earlier** day is the Smarta
+fast and the **later** one the Vaishnava fast. The almanac says so in prose on every
 Ekadashi date-time page. Two corrections bring the library in line:
 
 ```diff
@@ -183,11 +303,10 @@ Ekadashi date-time page. Two corrections bring the library in line:
 ```
 
 Both the Dashami-viddha and the vriddha-Dwadashi (Pakshavardhini) splits now
-match drik across every pair it publishes in 2024–2028. `getDailyPanchang`
+match the almanac across every pair it publishes in 2024-2028. `getDailyPanchang`
 callers that keyed off `smarta_ekadashi` / `vaishnava_ekadashi` on split days
 will see the two swap places; `computeEkadashiDatesForYear` is unchanged.
-Custom locale packs need the renamed viddha description keys — see the
-CHANGELOG.
+Custom locale packs need the renamed viddha description keys.
 
 ### Regional solar new years land on their own days
 
@@ -203,12 +322,11 @@ keyed, with a piecewise `vasa` segment list on `BhadraInfo`), night-transit
 Sankranti dates (+ a new `moment` field on `SankrantiEvent`), kshaya-Dwadashi
 Ekadashi advance, Vijayadashami/Karva Chauth/Janmashtami kala rules, the
 Kali Yuga year boundary, `scoreMuhurta` special-yoga parity, eastern-
-longitude Gulika/Mandi, and the opt-in Ashtakavarga reductions. See the
-CHANGELOG for each rule and its drik evidence.
+longitude Gulika/Mandi, and the opt-in Ashtakavarga reductions.
 
 ---
 
-## Upgrading to 5.1 — part 1 (from 5.0)
+## Upgrading to 5.1, part 1 (from 5.0)
 
 One deliberate type break, two corrected dasha tables, and one opt-in flag.
 
@@ -221,24 +339,24 @@ One deliberate type break, two corrected dasha tables, and one opt-in flag.
 
 5.0 evaluated only the nakshatra active at sunrise and dropped the second
 Varjyam window printed panchangs show on transition days. 5.1 publishes every
-window, in start order, under DrikPanchang's attribution rule: a window belongs
+window, in start order, under the almanac's attribution rule: a window belongs
 to the Hindu day its **start** falls in (one that begins before sunrise and
-runs past it is yesterday's), and window instants are unclamped — an end can
+runs past it is yesterday's), and window instants are unclamped, so an end can
 land after next sunrise. Validated window-for-window against a 61-day
-DrikPanchang sweep (Aug–Sep 2026, two full nakshatra cycles): 62/62 match.
+reference-almanac sweep (Aug-Sep 2026, two full nakshatra cycles): 62/62 match.
 
 Two value-level corrections ride along: **Mula carries a second tyajya spell**
-(elapsed ghatikas 20 *and* 56 — DrikPanchang, ProKerala and B.V. Raman's
+(elapsed ghatikas 20 *and* 56; the reference almanac, ProKerala and B.V. Raman's
 *Muhurta* concur), so Mula days now emit the window 5.0 missed; and the
 standalone `computeVarjyam` primitive returns the *earliest* of a nakshatra's
 spells overlapping the day. New export: `computeVarjyamWindows(sunriseUtc,
 nextSunriseUtc, getMoon)`.
 
-### Yogini and Ashtottari starting lords were wrong — now classical
+### Yogini and Ashtottari starting lords were wrong, now classical
 
 - **Yogini** used `nakshatraIndex % 8`, off by three Yoginis for every birth.
-  Now the classical Devi-Bhagavata formula — (1-based janma nakshatra + 3) mod
-  8; remainder 1 = Mangala … 0 = Sankata — so Ashwini → Bhramari, Pushya →
+  Now the classical Devi-Bhagavata formula: (1-based janma nakshatra + 3) mod
+  8, remainder 1 = Mangala … 0 = Sankata, so Ashwini → Bhramari, Pushya →
   Dhanya. Verified against published worked examples and PyJHora.
 - **Ashtottari** used a years-proportional split of the zodiac from a Krittika
   anchor, matching no source. Now the classical Ardradi **group table**
@@ -256,11 +374,11 @@ and should be discarded.
 computeAshtakoot(boy, girl, { ganaCancellation: true });
 ```
 
-Default output is byte-identical to 5.0 (DrikPanchang's published 36-guna
-table applies no Gana cancellation, and drik parity stays the default
+Default output is byte-identical to 5.0 (the reference almanac's published 36-guna
+table applies no Gana cancellation, and reference-almanac parity stays the default
 standard). With the flag raised, a doshic Gana score (≤ 1) is restored to the
 full 6 when the two Moons' sign lords are the same graha or mutual naisargika
-friends, recorded in `cancellations` — the condition set attested across
+friends, recorded in `cancellations`: the condition set attested across
 independent pandit corpora; weaker ones are documented on `AshtakootOptions`
 and deliberately not encoded.
 
@@ -272,10 +390,10 @@ Three changes move numbers that 4.x produced, and one option is gone.
 
 ### Lahiri ayanamsa corrected by +38″
 
-The library's Lahiri constant sat 38 arcseconds behind DrikPanchang's — it used
-`23.853211°` at J2000 (the widely-repeated 23° 51′ 11.6″ figure) where Drik
-computes `23.863801°`. The replacement was solved from Drik's own published
-values across 1950–2050, which agree on it to within 0.01″ — a century-wide
+The library's Lahiri constant sat 38 arcseconds behind the reference almanac's: it
+used `23.853211°` at J2000 (the widely-repeated 23° 51′ 11.6″ figure) where the
+almanac computes `23.863801°`. The replacement was solved from the almanac's own published
+values across 1950-2050, which agree on it to within 0.01″, a century-wide
 baseline, so the precession polynomial is pinned too, not just the epoch
 constant. Every sidereal output moves with it:
 
@@ -284,32 +402,32 @@ constant. Every sidereal output moves with it:
 | Nakshatra end-times | ~69 s later than 4.x (carries the ayanamsa once) |
 | Yoga end-times | ~129 s later than 4.x (carries it twice) |
 | Planetary longitudes, rashi, pada, lagna, divisionals, dashas | shifted +0.0106° |
-| Tithi / karana end-times | unchanged — Moon − Sun cancels the ayanamsa |
+| Tithi / karana end-times | unchanged: Moon − Sun cancels the ayanamsa |
 | Raman / KP / True Chitra / Thirukanitham | moved by the same +38″; their offsets from Lahiri are preserved |
 
-Worst-case end-time drift vs Drik dropped from 131 s to 60 s, and the sign split
-by ayanamsa exposure — nakshatra and yoga early, tithi and karana late — is gone.
+Worst-case end-time drift vs the almanac dropped from 131 s to 60 s, and the sign split
+by ayanamsa exposure (nakshatra and yoga early, tithi and karana late) is gone.
 If you have snapshot tests or cached charts from 4.x, expect them to need
 re-pinning.
 
 ### ΔT now uses measurement, so every published time moves ~6 s
 
-4.x took ΔT (TT − UT) entirely from Espenak–Meeus. Its post-2005 branches are an
-extrapolation published in 2006, and Earth's rotation did not follow it — by
+4.x took ΔT (TT − UT) entirely from Espenak-Meeus. Its post-2005 branches are an
+extrapolation published in 2006, and Earth's rotation did not follow it. By
 2026 the model reads about **5.9 s high**, drifting a further ~0.6 s each year.
 Because this library reports *times*, that lands directly on published values.
 
 v5 takes ΔT from the leap-second chain (`32.184 + (TAI − UTC)`, exact, and
 within the 0.9 s band leap seconds maintain) wherever ΔT has actually been
-measured, and resumes Espenak–Meeus beyond it carrying the offset it had
+measured, and resumes Espenak-Meeus beyond it carrying the offset it had
 accrued. Against JPL Horizons the measured era now agrees to **0.005 s** at
 every decade from 1980, where 4.x was seconds out.
 
 | Output | Effect |
 |---|---|
 | Tithi / nakshatra / yoga / karana end-times | ~5.7 s later for 2025 dates, growing with the model's drift |
-| Sankranti and other transit instants | same shift — it is one uniform correction, not per-element |
-| Sunrise / sunset / moonrise / moonset | barely moved — the error scales against the 15°/hr sky rotation |
+| Sankranti and other transit instants | same shift: it is one uniform correction, not per-element |
+| Sunrise / sunset / moonrise / moonset | barely moved: the error scales against the 15°/hr sky rotation |
 | Dates a panchang element is *filed under* | unchanged except where a transit sits within seconds of sunrise |
 
 That last row is the one to know about. `computeSankrantisForYear` publishes a
@@ -323,7 +441,7 @@ near sunrise are where a day could flip.
 `getInstantPanchang` located sunrise by searching forward from `date − 12 h`.
 For an evening instant that start point is already past the morning's sunrise,
 so it found *tomorrow's* and rolled the weekday back a day. Any query after
-roughly 7 pm returned the previous vara — and with it the wrong Rahu Kalam,
+roughly 7 pm returned the previous vara, and with it the wrong Rahu Kalam,
 Gulika Kalam, Yamaganda, Choghadiya, Hora, Anandadi yoga and special yogas.
 `getDailyPanchang` was never affected. If you cached instant-mode results from
 4.x for evening timestamps, discard them.
@@ -333,7 +451,7 @@ Gulika Kalam, Yamaganda, Choghadiya, Hora, Anandadi yoga and special yogas.
 `precision: 'standard' | 'high'` and the `Precision` type no longer exist.
 Element transitions are now solved by secant iteration, which converges to the
 root rather than stopping at a fixed tolerance, so there is nothing left for the
-option to select — and the tighter setting no longer buys anything. Removing it
+option to select, and the tighter setting no longer buys anything. Removing it
 from your options object is the whole migration; leaving it in is a type error,
 not a silent no-op.
 
@@ -343,7 +461,7 @@ Solar rise/set is computed from a canonical anchor and cached per location-day,
 so it no longer depends on which instant the caller happened to start searching
 from. Values shift by ≤108 ms vs 4.x, and two calls for the same day now agree
 exactly instead of differing by up to 109 ms. Windows derived proportionally
-from the day length — Varjyam, Bhadra, the slot systems — move by a little more
+from the day length (Varjyam, Bhadra, the slot systems) move by a little more
 than that. This removes an inconsistency rather than introducing an
 approximation: 4.x returned a different sunrise depending on which caller asked.
 
@@ -353,7 +471,7 @@ The same treatment sunrise received, now applied to the Moon. `getMoonrise` /
 `getMoonset` resolve through a canonical per-UTC-day cache, so an event has one
 timestamp no matter which caller asks or from which instant they searched.
 Published `moon.rise` / `moon.set` shift by **≤182 ms** vs 4.x. Nothing else in the
-result moves — verified over 11,520 daily results across six locations and three
+result moves, verified over 11,520 daily results across six locations and three
 centuries: zero changes to any index, name, boolean, festival date or other
 timestamp.
 
@@ -361,8 +479,8 @@ timestamp.
 
 `getFestivalsForYear` read a pre-built table; `getFestivalsInRange` ran the
 engine. Two near-identical names, completely different inputs and semantics. v5
-settles one convention across all four families — festivals, eclipses, moon
-phases and muhurta:
+settles one convention across all four families (festivals, eclipses, moon
+phases and muhurta):
 
 | 4.x | v5 | what it does |
 |---|---|---|
@@ -371,8 +489,8 @@ phases and muhurta:
 | `getFestivalsYearRange` | `readFestivalsYearRange` | reads a table |
 | `getEclipsesForYear` / `ForDate` / `YearRange` | `readEclipsesForYear` / … | reads a table |
 | `getMoonPhasesForYear` / `ForDate` / `YearRange` | `readMoonPhasesForYear` / … | reads a table |
-| — | `readMuhurtaForYear` / `ForDate` / `YearRange` | **new** — reads a table |
-| — | `readBestMuhurtaDays` | **new** — top-scoring days |
+| n/a | `readMuhurtaForYear` / `ForDate` / `YearRange` | **new**: reads a table |
+| n/a | `readBestMuhurtaDays` | **new**: top-scoring days |
 | `getFestivalsInRange` | `computeFestivalsInRange` | runs the engine |
 | `getEclipsesInRange` | `computeEclipsesInRange` | runs the engine |
 | `getMoonPhasesInRange` | `computeMoonPhasesInRange` | runs the engine |
@@ -380,7 +498,7 @@ phases and muhurta:
 | `getEkadashiDatesForYear` | `computeEkadashiDatesForYear` | runs the engine |
 | `getSankrantisForYear` | `computeSankrantisForYear` | runs the engine |
 
-**Every 4.x name still works** — they are deprecated aliases pointing at the same
+**Every 4.x name still works**: they are deprecated aliases pointing at the same
 functions, kept through v5. Nothing breaks today; the old names will go in v6.
 
 New single-year entry points, the shape most callers reach for first:
@@ -419,7 +537,7 @@ Only days that pass the rule are stored unless you pass `includeFailures: true`.
 indices, rather than repeating every localized string at every occurrence. A
 10-year festival table goes from 315 KB to **89.9 KB (28.5%)**; a 10-year
 moon-phase table from 106 KB to **29.7 KB (28.0%)**. Resolved output is
-identical — verified across every year and both locales.
+identical, verified across every year and both locales.
 
 Gzip already hid most of this on the wire, so the win is **parse time and
 resident memory**, which is the constraint that actually bites on Hermes.
@@ -432,7 +550,7 @@ engine output.
 table built with 4.x keeps working; only `key` is unavailable from it, and comes
 back as `''`.
 
-### Published `Date`s are real instants — the flagship change
+### Published `Date`s are real instants: the flagship change
 
 ```diff
 - result.sunrise.getTime()      // NOT when sunrise happened (off by the UTC offset)
@@ -441,7 +559,7 @@ back as `''`.
 + result.sun.riseLocal          // "2025-01-14T07:09:44.172+05:30"
 ```
 
-Applies to **every** `Date` in `DailyPanchangResult` and to every `TimePeriod` —
+Applies to **every** `Date` in `DailyPanchangResult` and to every `TimePeriod`:
 `sun.rise`, `sun.set`, `sun.nextRise`, `moon.rise`, `moon.set`, all the muhurtas
 and inauspicious periods, all four slot systems, the element
 `startTime`/`endTime` arrays, the eclipse contacts and sutak window. Each gains
@@ -459,7 +577,7 @@ a `*Local` companion: `sun.riseLocal`, `inauspicious.rahuKalam.startLocal`,
 `getInstantPanchang` results carry **no** `*Local` fields: that call takes no
 timezone, so there is no zone to render a wall clock in.
 
-**Cost:** rendering the strings adds ~0.04 ms per daily panchang — invisible on
+**Cost:** rendering the strings adds ~0.04 ms per daily panchang, invisible on
 a cold call and ~20% of a fully cached warm one. The release warms to
 **0.17 ms**, against published 4.3.1's **6.20 ms**.
 
@@ -472,7 +590,7 @@ a cold call and ~20% of a fully cached warm one. The release warms to
 ```
 
 `options.timezone` has always accepted `number | string`, but the result carried
-only a number — so passing `'America/New_York'` produced a result that could not
+only a number, so passing `'America/New_York'` produced a result that could not
 say which zone produced it. `zone` is present only when you passed a zone name.
 
 **The DST limit, now stated explicitly.** The offset is resolved **once per
@@ -485,7 +603,7 @@ whole truth.
 ### The result object is grouped
 
 `DailyPanchangResult` had ~50 flat top-level fields mixing five categories.
-v5 sorts them into seven groups — see [The result is grouped](#the-result-is-grouped)
+v5 sorts them into seven groups. See [The result is grouped](#the-result-is-grouped)
 for the full table. This is a large break, and it lands in the same release as
 the `Date` change on purpose: migrating both at once is one pass over your read
 sites, not two.
@@ -514,7 +632,7 @@ Every rename, in full:
 | `varjyam` / `bhadra` / `gandaMula` / `panchaka` / `panchakaRahita` | `inauspicious.*` (same names) |
 | `choghadiya` / `hora` | `periods.choghadiya` / `periods.hora` |
 | `gowriPanchangam` | `periods.gowri` |
-| `eclipse.magnitude` (disc *area*) | `eclipse.obscuration` — same value; the new `eclipse.magnitude` is the *diameter* fraction catalogues publish, and is negative for a penumbral lunar eclipse |
+| `eclipse.magnitude` (disc *area*) | `eclipse.obscuration`: same value; the new `eclipse.magnitude` is the *diameter* fraction catalogues publish, and is negative for a penumbral lunar eclipse |
 
 Unmoved: `date`, `location`, `timezone`, `ayanamsa`, `specialYogas`,
 `anandadiYoga`, `festivals`, `eclipse`, `chandraBalam`, `tarabala`.
@@ -527,12 +645,12 @@ For `getInstantPanchang`: `tithi` / `nakshatra` / `yoga` / `karana` / `vara` →
 
 ### One rule for "not applicable": always present, `null` or `[]`
 
-4.x used three conventions and you could not predict which you would get —
+4.x used three conventions and you could not predict which you would get:
 `| null` for `bhadra` / `varjyam` / `eclipse`, `?`-optional for `chandraBalam` /
 `tarabala`, and an empty array for `panchakaRahita` / `festivals`. v5 has one
 rule: **every field is always present**, a value that does not apply is `null`,
 and a collection that does not apply is `[]`. (Since 5.1, `varjyam` is a
-collection and follows the `[]` arm — see [Upgrading from 5.0](#upgrading-from-50).)
+collection and follows the `[]` arm; see [Upgrading from 5.0](#upgrading-from-50).)
 
 ```diff
 - if ('chandraBalam' in r) …        // 4.x: field absent without janmaRashi
@@ -563,7 +681,7 @@ always `undefined`.
 
 `sun.dinamanaMinutes` / `sun.dayDurationMinutes` and `sun.ratrimanaMinutes` /
 `sun.nightDurationMinutes` are the same numbers under classical and English
-names. Both pairs stay — consumers use both vocabularies — and the types now say
+names. Both pairs stay (consumers use both vocabularies) and the types now say
 plainly that they are aliases, never independently computed.
 
 `calendar.chandramasa` keeps its casing beside `moon.rashi` and `sun.nakshatra`.
@@ -575,15 +693,15 @@ the **lunar** one, which was previously left to guesswork.
 
 - `EclipseInfo` / `EclipseSubtype` are now exported. 4.x shipped
   `getUpcomingLunarEclipse` and friends without the type they return.
-- `festivals[].key` — stable, language-independent festival id. Match on this,
+- `festivals[].key`: stable, language-independent festival id. Match on this,
   never on `name`.
-- `bhadra.locationName` — localized display name; `bhadra.location` stays the
+- `bhadra.locationName`: localized display name; `bhadra.location` stays the
   machine-readable key.
-- `MuhurtaScore.factors` — structured scoring inputs alongside English `reasons`.
-- `BirthChart.byPlanet` — the nine placements keyed by graha.
+- `MuhurtaScore.factors`: structured scoring inputs alongside English `reasons`.
+- `BirthChart.byPlanet`: the nine placements keyed by graha.
 - `eclipse.description` is now localized. Under `language: 'hi'` it was
   previously emitted in English, including inside `festivals[].description`.
-- `sections` on `getDailyPanchang` — opt into a narrower, cheaper call. See
+- `sections` on `getDailyPanchang`: opt into a narrower, cheaper call. See
   [Performance](#performance).
 
 ---
@@ -592,7 +710,7 @@ the **lunar** one, which was previously left to guesswork.
 
 | Category | Features |
 |---|---|
-| **Pancha Anga** | Tithi, Nakshatra, Yoga, Karana, Vara — with all intra-day transitions |
+| **Pancha Anga** | Tithi, Nakshatra, Yoga, Karana, Vara, with all intra-day transitions |
 | **Lunar Calendar** | Chandra Masa (Purnimanta + Amanta), Adhika (leap) detection, Vikram + Shaka Samvat |
 | **Solar Calendar** | Saura Masa, Surya Nakshatra, Sankranti (transit-based) |
 | **Sun & Moon** | Sunrise, Sunset, Moonrise, Moonset (Meeus apparent-upper-limb), Chandra Rashi |
@@ -602,7 +720,7 @@ the **lunar** one, which was previously left to guesswork.
 | **Special Yogas** | Anandadi (28-cycle), Amrit Siddhi, Sarvartha Siddhi, Ravi/Guru Pushya, Dwi-/Tripushkar, Jwalamukhi, Aadal, Vidaal, Ravi |
 | **Festivals (80+)** | Ekadashi (Smarta/Vaishnava split), Pradosha, Sankranti, classical (Diwali/Holi/Shivaratri…), regional across 21 states + Nepal |
 | **Eclipses** | Solar/lunar detection, subtype, magnitude, horizon visibility, sutak window |
-| **Planetary Positions** | All 9 grahas (sidereal) with rashi, nakshatra, pada, retrograde — mean or true Rahu/Ketu |
+| **Planetary Positions** | All 9 grahas (sidereal) with rashi, nakshatra, pada, retrograde; mean or true Rahu/Ketu |
 | **Dashas** | Vimshottari (3-level), Ashtottari, Yogini, Chara, Narayan |
 | **Personal Transits** | Chandra Balam, Tarabala (9-cycle), Sade Sati |
 | **Birth Chart** | Lagna, Bhava under 3 house systems, D1/D2/D3/D7/D9/D10/D12/D30, Planetary Dignity |
@@ -620,14 +738,14 @@ the **lunar** one, which was previously left to guesswork.
 
 ## Used By
 
-- [dharmagya.app](https://dharmagya.app) — Daily Panchang and Hindu calendar ([Play Store](https://play.google.com/store/apps/details?id=com.ishank1995.dharmagya))
+- [dharmagya.app](https://dharmagya.app): Daily Panchang and Hindu calendar ([Play Store](https://play.google.com/store/apps/details?id=com.ishank1995.dharmagya))
 
 ---
 
 # Feature Reference
 
 A quick tour with runnable snippets. **Each section links to its full page on
-the docs site** — every option, field, and caveat lives there.
+the docs site**: every option, field, and caveat lives there.
 
 ## Pancha Anga & the daily result
 
@@ -639,8 +757,8 @@ const r = getDailyPanchang(date, location, { timezone: 330 })!;
 r.angas.tithis.forEach(t => console.log(t.name, t.paksha, t.endTime));
 r.angas.vara.name;                     // "Mangalawara"
 r.calendar.chandramasa.isAdhika;       // true during leap months
-r.muhurtas.brahma;                     // TimePeriod | null — and 9 more muhurtas
-r.inauspicious.rahuKalam;              // { start, end } — and 9 more windows
+r.muhurtas.brahma;                     // TimePeriod | null, and 9 more muhurtas
+r.inauspicious.rahuKalam;              // { start, end }, and 9 more windows
 r.periods.choghadiya.day[0].name;      // 16 Choghadiya + Gowri + 24 Hora slots
 r.anandadiYoga.name; r.specialYogas;   // Anandadi + Amrit/Sarvartha Siddhi, …
 
@@ -656,7 +774,7 @@ console.log(i.angas.tithi.name, i.angas.nakshatra.name);
 
 ```typescript
 r.festivals.forEach(f => console.log(f.key, f.name, f.type, f.deferralDate));
-// `name` is localized, so match on `key` — never on `name`:
+// `name` is localized, so match on `key`, never on `name`:
 const hasDiwali = r.festivals.some(f => f.key === 'diwali');
 
 // Scope regional variants: 21 state slugs + 'nepal' + 'all' (default)
@@ -667,7 +785,7 @@ import { buildFestivalsTable } from 'panchang-ts';
 import { readFestivalsForYear, readFestivalsForDate } from 'panchang-ts/festivals';
 ```
 
-No table ships with the package — festival dates are observer-dependent, so you
+No table ships with the package: festival dates are observer-dependent, so you
 build one for your users' location and years (`npm run festivals:gen` is a
 worked example).
 
@@ -699,7 +817,7 @@ import { scoreMuhurta, computeAuspiciousDatesInRange, vivahRule } from 'panchang
 
 const s = scoreMuhurta(new Date('2026-05-12'), DELHI, vivahRule, { timezone: 330 });
 s.score;            // 0..100; passes when ≥ 50
-s.factors;          // structured, stable codes — localize/filter on these
+s.factors;          // structured, stable codes: localize/filter on these
 s.reasons;          // diagnostic English
 
 computeAuspiciousDatesInRange(vivahRule, start, end, DELHI, { timezone: 330 });
@@ -774,7 +892,7 @@ import {
 
 computeAshtakoot({ rashi: 4, nakshatra: 9 }, { rashi: 0, nakshatra: 1 });
 // → { totalScore: 0..36, koots: KootScore[8], cancellations: string[] }
-// Opt-in Gana-dosha cancellation (default off — preserves drik 36-guna parity):
+// Opt-in Gana-dosha cancellation (default off, preserves almanac 36-guna parity):
 computeAshtakoot(boy, girl, { ganaCancellation: true });
 
 computeMangalCompatibility(boyChart, girlChart);   // Manglik is a PAIRWISE verdict
@@ -826,7 +944,7 @@ getHinduNewYear(2026, 'tamil-nadu', DELHI, { timezone: 330 });  // region-aware
 ```typescript
 const hi = getDailyPanchang(date, loc, { timezone: 330, language: 'hi' })!;
 hi.angas.tithis[0].name;       // "कृष्ण चतुर्दशी"
-hi.angas.vara.englishName;     // "Tuesday" — englishName always English
+hi.angas.vara.englishName;     // "Tuesday", englishName always English
 
 // All options: timezone (number | IANA string), ayanamsa (5), language (en|hi),
 // masaSystem (purnimanta|amanta), region, computeEndTimes, sections,
@@ -834,12 +952,12 @@ hi.angas.vara.englishName;     // "Tuesday" — englishName always English
 ```
 
 Machine-readable keys never change with language: match on `festival.key`,
-`bhadra.location`, `eclipse.kind`, `factors[].code` — render `name` /
+`bhadra.location`, `eclipse.kind`, `factors[].code`; render `name` /
 `locationName` / `description` / `reasons`.
 
 ## Types & Exports
 
-📖 [Types & Exports →](https://dharmagya.app/docs/panchang-ts/types) — the key
+📖 [Types & Exports →](https://dharmagya.app/docs/panchang-ts/types): the key
 interfaces (`TithiInfo`, `FestivalInfo`, `EclipseInfo`, `GrahaPosition`, …) and
 the complete export list of the main entry and the four engine-free subpaths
 (`panchang-ts/festivals`, `/eclipses`, `/moon-phases`, `/muhurta`).
@@ -849,7 +967,7 @@ the complete export list of the main entry and the four engine-free subpaths
 ## React Native / Hermes
 
 Works with Expo and bare React Native (Hermes engine). Pass `timezone` as a
-**number** — IANA strings need `Intl`, which older Hermes versions lack.
+**number**: IANA strings need `Intl`, which older Hermes versions lack.
 
 Two-pass rendering pattern for smooth UI:
 
@@ -857,7 +975,7 @@ Two-pass rendering pattern for smooth UI:
 import { getDailyPanchang } from 'panchang-ts';
 import { InteractionManager } from 'react-native';
 
-// Pass 1 — cheapest useful result: elements, slots, muhurtas (~0.25 ms).
+// Pass 1 (cheapest useful result): elements, slots, muhurtas (~0.25 ms).
 const fast = getDailyPanchang(date, location, {
   timezone: 330,
   sections: [],
@@ -865,7 +983,7 @@ const fast = getDailyPanchang(date, location, {
 });
 setState(fast);
 
-// Pass 2 — background, everything (~0.41 ms).
+// Pass 2 (background): everything (~0.41 ms).
 InteractionManager.runAfterInteractions(() => {
   setState(getDailyPanchang(date, location, { timezone: 330 }));
 });
@@ -877,35 +995,35 @@ InteractionManager.runAfterInteractions(() => {
 
 📖 [Full accuracy notes →](https://dharmagya.app/docs/panchang-ts/accuracy)
 
-8,772 tests across 137 files, including fixtures cross-verified against reference
-panchang calculations spanning 2025–2026 across 10 Indian cities plus New York,
+8,805 tests across 138 files, including fixtures cross-verified against reference
+panchang calculations spanning 2025-2026 across 10 Indian cities plus New York,
 London, Sydney, Dubai, Singapore (diaspora fixtures cover DST on
 `America/New_York`).
 
 | Element | Accuracy |
 |---|---|
 | Sunrise / Sunset | ≤29 s observed vs reference minute-midpoint (±45 s tolerance) |
-| Moonrise / Moonset | Meeus apparent-upper-limb (refraction + parallax); ~3–5 min vs simpler-horizon authorities is expected |
+| Moonrise / Moonset | Meeus apparent-upper-limb (refraction + parallax); ~3-5 min vs simpler-horizon authorities is expected |
 | Tithi / Nakshatra / Yoga / Karana names | Exact match vs reference |
-| Tithi / Nakshatra / Yoga / Karana end-times | ≤60 s vs Drik across all 20 audited comparisons |
-| Ayanamsa (Lahiri) | Reproduces DrikPanchang's published value to ~0.01″ across 1950–2050 |
-| Planetary positions (Sun–Saturn) | ±0.02° sidereal |
+| Tithi / Nakshatra / Yoga / Karana end-times | ≤60 s vs the reference almanac across all 20 audited comparisons |
+| Ayanamsa (Lahiri) | Reproduces the reference almanac's published value to ~0.01″ across 1950-2050 |
+| Planetary positions (Sun-Saturn) | ±0.02° sidereal |
 | Planetary positions (Rahu/Ketu) | ≤0.5° mean node, ≤0.6° true node (typical) |
 | Lagna sidereal longitude | Cross-checked against Jagannath Hora reference charts |
 | D1 / D9 house placement | Exact match vs reference for 9-graha placement |
 | Ashtakoot total | ±1 point per pair across 30+ matched pairs |
-| Varjyam windows | count + position vs DrikPanchang over a 61-day / two-nakshatra-cycle sweep, ≤2 min (62/62 windows) |
-| Sade Sati arc start/end | ±1–2 days vs authoritative ephemerides |
+| Varjyam windows | count + position vs the reference almanac over a 61-day / two-nakshatra-cycle sweep, ≤2 min (62/62 windows) |
+| Sade Sati arc start/end | ±1-2 days vs authoritative ephemerides |
 
 **Festival dating** uses tithi-at-sunrise; a few festivals have authorities on
 other rules (tithi-at-midnight for Janmashtami / Shivaratri / Diwali,
 madhyahna-vyapini for Ganesh Chaturthi edge years) where output can drift
-±1 day — the exact list is
+±1 day. The exact list is
 [documented](https://dharmagya.app/docs/panchang-ts/accuracy#festival-tradeoff).
 
 **Detection conventions:** Aadal / Vidaal follow the classical Moon-from-Sun
 nakshatra-distance rule, not the Tamil-Vakya weekday rule. Varjyam lists every
-window whose start falls in the Hindu day (Drik's attribution; Mula carries two
+window whose start falls in the Hindu day (the almanac's attribution; Mula carries two
 tyajya spells). Do Ghati does not rotate by weekday.
 
 ---
@@ -914,7 +1032,7 @@ tyajya spells). Do Ghati does not rotate by weekday.
 
 📖 [Full performance notes →](https://dharmagya.app/docs/panchang-ts/performance)
 
-Measured at Pune, Apple M-series, Node — median of 11 processes. **Distinct
+Measured at Pune, Apple M-series, Node (median of 11 processes). **Distinct
 days** is the calendar-scan cost; **same day repeated** is what a UI
 re-rendering one date sees. Last column is published 4.3.1, benchmarked beside
 this release.
@@ -927,12 +1045,12 @@ this release.
 
 **A default day is ~15× cheaper than 4.3.1**, a repeated day ~37×. The levers:
 
-- **`sections`** — skip the optional ephemeris-backed blocks (`'festivals'`,
+- **`sections`** skips the optional ephemeris-backed blocks (`'festivals'`,
   `'eclipse'`, `'moonTimes'`, `'lunarWindows'`). Narrowing is exactly
   output-neutral: every field a narrowed call computes is identical to the full
   call's; omitted sections sit at their documented `null` / `[]`.
-- **`computeEndTimes: false`** — drops the `endTime` transition searches;
-  ~5–10% — use it to drop fields you don't want, not to go faster.
+- **`computeEndTimes: false`** drops the `endTime` transition searches;
+  ~5-10%. Use it to drop fields you don't want, not to go faster.
 
 Range helpers narrow internally: `computeEkadashiDatesForYear` **~18 ms/year**
 (4.3.1: ~2,360), `computeFestivalsInRange` **~131 ms/year** (~2,180),
@@ -941,7 +1059,7 @@ cached process-wide (bounded, 20k entries), which also makes them
 single-valued.
 
 One deliberate regression: raw chart primitives (`computeRashiChart`,
-`computeNavamsa`) cost ~0.32 ms vs ~0.10 in 4.3.1 — the price of an
+`computeNavamsa`) cost ~0.32 ms vs ~0.10 in 4.3.1, the price of an
 order-of-magnitude accuracy gain against JPL DE441. `computeShadbala` /
 `computeBhavaBala` went the other way, ~2× faster.
 
@@ -970,7 +1088,7 @@ Error codes: `INVALID_DATE`, `INVALID_LATITUDE`, `INVALID_LONGITUDE`,
 `CIRCUMPOLAR` (Placidus-KP houses above ±66.5°).
 
 **Polar locations.** `getDailyPanchang` and `getInstantPanchang` return `null`
-rather than throwing — the Hindu day is undefined when sunrise can't be
+rather than throwing: the Hindu day is undefined when sunrise can't be
 computed. The low-level `getSunrise` / `getSunset` primitives still throw
 `PanchangError(NO_SUNRISE)` / `PanchangError(NO_SUNSET)` for direct callers
 who need the precise reason. `getMoonrise` / `getMoonset` return `null` (normal
@@ -995,7 +1113,7 @@ dependencies**, and is `sideEffects: false`.
 
 ## Acknowledgements
 
-As of v5 the package has **no runtime dependencies** — the ephemeris, ΔT model
+As of v5 the package has **no runtime dependencies**: the ephemeris, ΔT model
 and event searches are the library's own. Two projects still deserve credit:
 [astronomy-engine](https://github.com/cosinekitty/astronomy) by Don Cross (MIT),
 the runtime engine through 4.x and now the dev-time baseline the own ephemeris