panchang-ts 3.1.0 → 4.1.0

package/README.md

@@ -5,7 +5,7 @@
 Pure TypeScript Hindu Panchang (almanac), Jyotish, and Birth Chart calculations.
 Zero native dependencies. Works offline in React Native (Hermes), Node.js, and browsers.
 
-**Fast** (~0.1 ms names-only, ~0.5 ms full) | **Typed** (full TypeScript types) | **Offline** (pure JS math, no network) | **7,156 tests**
+**Fast** (~0.1 ms names-only, ~0.5 ms full) · **Typed** (full TypeScript) · **Offline** (pure JS math) · **8,103 tests across 96 files**
 
 ---
 
@@ -13,51 +13,11 @@ Zero native dependencies. Works offline in React Native (Hermes), Node.js, and b
 
 ```bash
 npm install panchang-ts
-# or
-pnpm add panchang-ts
-# or
-yarn add panchang-ts
+# or: pnpm add panchang-ts / yarn add panchang-ts
 ```
 
 ---
 
-## Features at a Glance
-
-Every category below is implemented end-to-end, cross-verified against reference panchang
-sources, and exposed through the public API. Click a row to jump to its usage example.
-
-| Category | Features | Jump to |
-|----------|----------|---------|
-| **Pancha Anga (5 limbs)** | Tithi, Nakshatra, Yoga, Karana, Vara — with all transitions through the day | [↓](#1-pancha-anga--the-five-limbs) |
-| **Lunar Calendar** | Chandra Masa (Purnimanta + Amanta), Adhika (leap-month) detection, Vikram Samvat, Shaka Samvat | [↓](#2-lunar-calendar) |
-| **Solar Calendar** | Saura Masa, Surya Nakshatra, Sankranti (transit-based) | [↓](#3-solar-calendar) |
-| **Sun & Moon** | Sunrise, Sunset, Moonrise, Moonset, Chandra Rashi (Moon sign) | [↓](#4-sun--moon) |
-| **Auspicious Muhurta** | Brahma, Abhijit, Vijaya, Godhuli, Nishita, Madhyahna, Pratah / Sayahna Sandhya, Amrit Kala | [↓](#5-auspicious-muhurta) |
-| **Inauspicious Periods** | Rahu Kalam, Gulika Kalam, Yamaganda, Dur Muhurta, Varjyam, Ganda Mula, Bhadra Kala, Panchaka | [↓](#6-inauspicious-periods) |
-| **Time-Slot Systems** | Choghadiya (16), Gowri Panchangam / Nalla Neram (16), Hora (24), Do Ghati (30), Panchaka Rahita | [↓](#7-time-slot-systems) |
-| **Special Yogas** | Anandadi (28-name cycle), Amrit Siddhi, Sarvartha Siddhi, Ravi / Guru Pushya, Dwipushkar, Tripushkar, Jwalamukhi, Aadal, Vidaal, Ravi | [↓](#8-special-yogas) |
-| **Festivals (80+)** | Ekadashi (Smarta + Vaishnava split), Pradosha, Sankranti variants, classical festivals (Diwali, Holi, Shivaratri…), regional festivals across 21 states + Nepal | [↓](#9-festivals) |
-| **Eclipses (Grahan)** | Solar + lunar detection, subtype, magnitude, observer-horizon visibility, sutak window | [↓](#10-eclipses) |
-| **Planetary Positions** | All 9 grahas (sidereal) with rashi, nakshatra, pada, retrograde — mean or true Rahu/Ketu | [↓](#11-planetary-positions) |
-| **Vimshottari Dasha** | Maha → Antar → Pratyantar (3-level) breakdown from birth | [↓](#12-vimshottari-dasha) |
-| **Personal Transits** | Chandra Balam, Tarabala (9-tara cycle), Sade Sati (Saturn arc) | [↓](#13-personal-transits) |
-| **Birth Chart (Kundli)** | Lagna (sidereal), Bhava under 3 house systems, D1 / D2 / D3 / D7 / D9 / D10 / D12 / D30 charts, Planetary Dignity | [↓](#14-birth-chart-kundli) |
-| **Compatibility & Doshas** | Ashtakoot Guna Milan (36-point), Mangal Dosha, Kaal Sarp Dosha (12 subtypes), Pitru Dosha | [↓](#15-compatibility--doshas) |
-| **Aspects & Strength** | Drishti (graha aspects), Shadbala (six-fold strength) | [↓](#16-aspects--strength) |
-| **Dasha Systems** | Vimshottari (Maha→Antar→Pratyantar), Ashtottari, Yogini, Chara (Jaimini) | [↓](#17-dasha-systems) |
-| **Muhurta Engine** | Configurable scoring + 13 stock occasions (vivah, griha pravesh, namakarana, …) | [↓](#18-muhurta-engine) |
-| **Calendar Conversion** | Gregorian↔Hindu, Kali Yuga year, Hindu New Year, yearly Ekadashi / Sankranti / festival listings | [↓](#19-calendar-conversion) |
-| **Localization** | English + Hindi (Devanagari) on every returned name | [↓](#20-localization) |
-| **Configuration** | 5 ayanamsas (Lahiri, Raman, KP, True Chitrapaksha, Thirukanitham), 2 masa systems, 3 house systems, 21 regional festival scopes | [↓](#21-configuration) |
-
----
-
-## Used By
-
-- [dharmagya.app](https://dharmagya.app) — Daily Panchang and Hindu calendar
-
----
-
 ## Quick Start
 
 ```typescript
@@ -68,222 +28,172 @@ const result = getDailyPanchang(
   { latitude: 23.1765, longitude: 75.7885 },  // Ujjain, India
   { timezone: 330 },                          // IST = UTC+5:30 = 330 minutes
 );
-// result is `DailyPanchangResult | null` — null only at polar latitudes
-// where sunrise can't be computed. Anywhere else, narrow with `if (!result) return;`
-
-console.log(result.tithis[0].name);           // "Krishna Chaturdashi"
-console.log(result.nakshatras[0].name);       // "Mrigashira"
-console.log(result.vara.name);                // "Mangalawara"
-console.log(result.chandramasa.name);         // "Magha"
-console.log(result.samvat.vikramSamvat);      // 2081
+// → DailyPanchangResult | null. Null only at polar latitudes where
+//   sunrise can't be computed. Anywhere else, narrow with `if (!result) return;`.
+
+console.log(result!.tithis[0].name);          // "Krishna Chaturdashi"
+console.log(result!.nakshatras[0].name);      // "Mrigashira"
+console.log(result!.vara.name);               // "Mangalawara"
+console.log(result!.chandramasa.name);        // "Magha"
+console.log(result!.samvat.vikramSamvat);     // 2081
 ```
 
 ### Reading Output Times
 
-All `Date` objects in the result are **offset-adjusted** to the requested timezone. Always
-read time components via `getUTC*` methods — `.getHours()` would use your system zone:
+All `Date` objects are **offset-adjusted** to the requested timezone. Read time
+components via `getUTC*` — `.getHours()` would use your system zone:
 
 ```typescript
-const sunrise = result.sunrise;
+const sunrise = result!.sunrise;
 const h = sunrise.getUTCHours();    // 7
-const m = sunrise.getUTCMinutes();  // 4
-// → Sunrise at 07:04 local time
-
-function fmt(d: Date) {
-  const h = d.getUTCHours(), m = d.getUTCMinutes();
-  return `${h}:${String(m).padStart(2, '0')}`;
-}
-fmt(result.rahuKalam.start); // "09:04"
+const m = sunrise.getUTCMinutes();  // 4 → 07:04 local time
 ```
 
-`moonrise` and `moonset` can be `null` — the Moon occasionally does not rise or set on a
-given calendar day, which is normal.
+`moonrise` / `moonset` can be `null` — the Moon occasionally does not rise or
+set on a given calendar day, which is normal.
 
 ### `getDailyPanchang` vs `getInstantPanchang`
 
-| Use case | Recommended | Why |
-|----------|-------------|-----|
-| "What Panchang elements are active right now?" | `getInstantPanchang` | Single-moment snapshot; no sunrise needed |
-| Birth chart / muhurta picking at a specific instant | `getInstantPanchang` | Exact element at that UTC moment |
-| Daily calendar / almanac row for a date | `getDailyPanchang` | Lists all element transitions for the day |
-| Today's festivals & observances | `getDailyPanchang` | Full canonical-time festival refinement |
-| Rahu Kalam / Choghadiya / Gowri / Hora / muhurtas | `getDailyPanchang` | Computed from sunrise, sunset, day length |
-| Eclipse detection with sutak window | `getDailyPanchang` | Overlapping the day needs the day window |
-
-`getInstantPanchang` does emit `festivals`, but evaluates rules against the elements at the
-given instant only. It does not run canonical-time refinements (madhyahna / pradosha /
-nishita / chandrodaya), transit-based Sankranti, Ekadashi viddha (Smarta/Vaishnava split),
-or Bhadra-aware Raksha Bandhan exclusion. For reliable festival dating, use
-`getDailyPanchang`.
+| Use case | Use |
+|---|---|
+| Daily calendar, festivals, muhurtas, time-slots (Choghadiya/Hora/Gowri), eclipses with sutak | `getDailyPanchang` |
+| 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 /
+pradosha / nishita / chandrodaya), transit-based Sankranti, and Smarta/Vaishnava
+Ekadashi split. For reliable festival dating, use `getDailyPanchang`.
 
-# Feature Reference
+---
 
-Each section below shows how to access one feature category. Every feature is also
-returned as a field on the unified `DailyPanchangResult` from `getDailyPanchang(…)` if you
-prefer one call over the per-feature helpers.
+## Features at a Glance
 
-## 1. Pancha Anga — the Five Limbs
+| Category | Features |
+|---|---|
+| **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 |
+| **Auspicious Muhurta** | Brahma, Abhijit, Vijaya, Godhuli, Nishita, Madhyahna, Pratah/Sayahna Sandhya, Amrit Kala |
+| **Inauspicious Periods** | Rahu Kalam, Gulika Kalam, Yamaganda, Dur Muhurta, Varjyam, Ganda Mula, Bhadra Kala, Panchaka |
+| **Time-Slot Systems** | Choghadiya, Gowri Panchangam (Tamil "Nalla Neram"), Hora, Do Ghati, Panchaka Rahita |
+| **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 |
+| **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 |
+| **Compatibility & Doshas** | Ashtakoot (36-point), Pathu Porutham (Tamil 10-fold), Mangal, Kaal Sarp (12 subtypes), Pitru |
+| **Strength & Aspects** | Drishti, Shadbala (6-fold), Ashtakavarga (Bhinna + Sarva, with reductions), Bhava Bala, Argala |
+| **Yogas & Karakas** | 25 named yogas (with cancellations), 7- and 8-Karaka Jaimini |
+| **Annual & Sensitive** | Varshaphala (Tajik + 27 Sahams), Tithi Pravesha, Arudha padas, Hora/Ghati/Bhava/Sripati lagnas, Upagrahas |
+| **KP & Prashna** | KP sub-lord at any longitude, Placidus-KP cuspal sub-lords, KP significators, Prashna chart |
+| **Muhurta Engine** | Configurable scoring + 13 stock occasions (vivah, griha pravesh, namakarana, …) |
+| **Calendar Conversion** | Gregorian↔Hindu, Kali Yuga year, Hindu New Year, yearly Ekadashi/Sankranti/festival listings |
+| **Localization** | English + Hindi (Devanagari) |
+| **Configuration** | 5 ayanamsas (Lahiri, Raman, KP, True Chitrapaksha, Thirukanitham), 2 masa systems, 3 house systems |
 
-Tithi, Nakshatra, Yoga, Karana, Vara — with start / end times for every transition during
-the Hindu day.
+---
 
-```typescript
-import { getDailyPanchang } from 'panchang-ts';
+## Used By
 
-const r = getDailyPanchang(date, location, { timezone: 330 })!;
+- [dharmagya.app](https://dharmagya.app) — Daily Panchang and Hindu calendar ([Play Store](https://play.google.com/store/apps/details?id=com.ishank1995.dharmagya))
 
-// Tithis active during the day (usually 1-2)
-r.tithis.forEach(t => {
-  console.log(t.name, t.paksha, t.completionPercentage, t.endTime);
-});
+---
 
-// Nakshatras (with pada)
-r.nakshatras.forEach(n => console.log(n.name, n.pada, n.endTime));
+# Feature Reference
 
-// Yogas (27-name lunisolar cycle)
-r.yogas.forEach(y => console.log(y.name, y.endTime));
+Each daily field is also returned from `getDailyPanchang` if you prefer one call
+over per-feature helpers.
 
-// Karanas (half-tithi; usually 2-4 per day)
-r.karanas.forEach(k => console.log(k.name, k.type, k.endTime));
+## Pancha Anga
 
-// Vara (weekday)
-console.log(r.vara.name, r.vara.englishName);  // "Mangalawara", "Tuesday"
-```
+```typescript
+const r = getDailyPanchang(date, location, { timezone: 330 })!;
 
-For a single-instant snapshot use `getInstantPanchang`:
+r.tithis.forEach(t => console.log(t.name, t.paksha, t.completionPercentage, t.endTime));
+r.nakshatras.forEach(n => console.log(n.name, n.pada, n.endTime));
+r.yogas.forEach(y => console.log(y.name, y.endTime));
+r.karanas.forEach(k => console.log(k.name, k.type, k.endTime));
+console.log(r.vara.name, r.vara.englishName);   // "Mangalawara", "Tuesday"
 
-```typescript
+// Single-instant snapshot:
 import { getInstantPanchang } from 'panchang-ts';
-
 const i = getInstantPanchang(new Date(), location)!;
 console.log(i.tithi.name, i.nakshatra.name, i.yoga.name, i.karana.name, i.vara.name);
 ```
 
-## 2. Lunar Calendar
-
-Chandra Masa with **Purnimanta** (North Indian, default) and **Amanta** (South Indian)
-naming, **Adhika** (leap-month) detection, **Vikram** and **Shaka** samvat year numbers.
+## Lunar & Solar Calendar
 
 ```typescript
 const r = getDailyPanchang(date, loc, { timezone: 330, masaSystem: 'purnimanta' })!;
 
-console.log(r.chandramasa.name);           // "Magha"   (active system)
-console.log(r.chandramasa.amantaName);     // "Pausha"  (South Indian)
-console.log(r.chandramasa.purnimantaName); // "Magha"   (North Indian)
-console.log(r.chandramasa.isAdhika);       // false (true during leap months)
+r.chandramasa.name;           // active system (default: Purnimanta / North Indian)
+r.chandramasa.amantaName;     // South Indian
+r.chandramasa.purnimantaName; // North Indian
+r.chandramasa.isAdhika;       // true during leap months
+r.samvat.vikramSamvat;        // 2081
+r.samvat.shakaSamvat;         // 1946
 
-console.log(r.samvat.vikramSamvat);        // 2081
-console.log(r.samvat.shakaSamvat);         // 1946
+r.masa.name;                  // current solar month (Mesha … Meena)
+r.suryaNakshatra.name;        // Sun's nakshatra
+r.chandraRashi.name;          // Moon sign
 ```
 
-## 3. Solar Calendar
-
-Saura Masa (solar month), Surya Nakshatra (the Sun's nakshatra, ~13–14 day transit),
-Sankranti (solar-month boundary, transit-based — emitted as a festival).
-
-```typescript
-const r = getDailyPanchang(date, loc, { timezone: 330 })!;
-
-console.log(r.masa.name);              // "Makara" (current solar month)
-console.log(r.suryaNakshatra.name);    // "Uttara Ashadha"
-console.log(r.chandraRashi.name);      // "Mithuna" (Moon sign)
-
-// Sankranti and its regional variants emit through r.festivals — see §9.
-```
-
-## 4. Sun & Moon
-
-Sunrise, sunset, moonrise, moonset (Meeus apparent-upper-limb), plus Chandra Rashi
-(Moon's zodiac sign).
+## Sun, Moon & Muhurta
 
 ```typescript
 import { getSunrise, getSunset, getMoonrise, getMoonset } from 'panchang-ts';
 
-const loc = { latitude: 28.6139, longitude: 77.2090 };  // New Delhi
-
-const sunrise = getSunrise(localMidnightUtc, loc);
-const sunset  = getSunset(sunrise, loc);
-
-// Moonrise / moonset can be null on days the Moon doesn't rise/set
-const moonrise = getMoonrise(localMidnightUtc, loc);
+const sunrise  = getSunrise(localMidnightUtc, loc);
+const sunset   = getSunset(sunrise, loc);
+const moonrise = getMoonrise(localMidnightUtc, loc); // null on some days (normal)
 const moonset  = getMoonset(localMidnightUtc, loc);
 
-// Or read all of them off the daily result:
-const r = getDailyPanchang(date, loc, { timezone: 330 })!;
-console.log(r.sunrise, r.sunset, r.moonrise, r.moonset, r.nextSunrise);
-console.log(r.dayDurationMinutes, r.nightDurationMinutes);
-```
-
-## 5. Auspicious Muhurta
-
-Classical auspicious time windows: Brahma, Abhijit, Vijaya, Godhuli, Nishita, Madhyahna,
-Pratah / Sayahna Sandhya, and nakshatra-keyed Amrit Kala.
-
-```typescript
+// Or read off the daily result:
 const r = getDailyPanchang(date, loc, { timezone: 330 })!;
+r.sunrise; r.sunset; r.moonrise; r.moonset; r.nextSunrise;
+r.dayDurationMinutes; r.nightDurationMinutes;
 
+// Auspicious muhurtas
 r.brahmaMuhurta;     // two muhurtas before sunrise
-r.abhijitMuhurta;    // 8th day-muhurta — universally auspicious
-r.vijayaMuhurta;     // 11th day-muhurta — auspicious for success
-r.godhuliMuhurta;    // "cow-dust" — sunset muhurta
+r.abhijitMuhurta;    // 8th day-muhurta; null on Wednesday (Drik convention)
+r.vijayaMuhurta;     // 11th day-muhurta
+r.godhuliMuhurta;    // "cow-dust" sunset muhurta
 r.nishitaMuhurta;    // midnight muhurta (Shivaratri)
 r.madhyahna;         // solar noon ±24 min
-r.pratahSandhya;     // dawn twilight, ends *at* sunrise
-r.sayahnaSandhya;    // dusk twilight, starts *at* sunset
+r.pratahSandhya;     // dawn twilight, ends at sunrise
+r.sayahnaSandhya;    // dusk twilight, starts at sunset
 r.amritKala;         // nakshatra-specific window (null when nakshatra has none)
-
-// Direct helpers:
-import {
-  computeBrahmaMuhurta, computeAbhijitMuhurta, computeVijayaMuhurta,
-  computeGodhuliMuhurta, computeNishitaMuhurta, computeMadhyahna,
-  computePratahSandhya, computeSayahnaSandhya, computeAmritKala,
-} from 'panchang-ts';
 ```
 
-`pratahSandhya` and `sayahnaSandhya` are asymmetric — width = `nightDuration / 10`
-(~62–81 min depending on season), matching DrikPanchang within ±2 min.
-
-## 6. Inauspicious Periods
+`pratahSandhya` / `sayahnaSandhya` width = `nightDuration / 10` (~62–81 min).
 
-Rahu Kalam, Gulika Kalam, Yamaganda, Dur Muhurta (2 windows), Varjyam (BPHS-keyed
-~96-min forbidden window), Ganda Mula (Moon in root nakshatras), Bhadra Kala (Vishti
-karana with earth/heaven/paatal location), Panchaka.
+## Inauspicious Periods
 
 ```typescript
 const r = getDailyPanchang(date, loc, { timezone: 330 })!;
 
 r.rahuKalam;       // { start, end }
-r.gulikaKalam;     // { start, end }
-r.yamaganda;       // { start, end }
-r.durMuhurta;      // [TimePeriod, TimePeriod] — two ~48-min windows
+r.gulikaKalam;
+r.yamaganda;
+r.durMuhurta;      // two ~48-min windows
 r.varjyam;         // { start, end } | null
-r.gandaMula;       // { active: boolean, severity: 'mild' | 'severe' | null, ... }
+r.gandaMula;       // { active, severity: 'mild'|'severe'|null, ... }
 r.bhadra;          // { start, end, location: 'earth'|'heaven'|'paatal', isActive } | null
 r.panchaka;        // boolean — Moon in last 5 nakshatras
-
-// Direct helpers (varaIndex: 0=Sun ... 6=Sat):
-import {
-  computeRahuKalam, computeGulikaKalam, computeYamaganda,
-  computeVarjyam, computeGandaMula,
-} from 'panchang-ts';
-
-const rahu = computeRahuKalam(sunrise, sunset, varaIndex);
 ```
 
-## 7. Time-Slot Systems
-
-Four parallel slot systems covering the Hindu day:
+## Time-Slot Systems
 
 ```typescript
 const r = getDailyPanchang(date, loc, { timezone: 330 })!;
 
-// Choghadiya — 8 day + 8 night slots, each named (Amrit, Kaal, Shubh, Rog, ...) and rated
+// Choghadiya — 8 day + 8 night named, rated slots (Amrit, Kaal, Shubh, Rog, …)
 r.choghadiya.day.forEach(s => console.log(s.name, s.qualityName, s.start, s.end));
-r.choghadiya.night.forEach(s => console.log(s.name, s.qualityName));
 
-// Gowri Panchangam (Tamil "Nalla Neram") — 8 day + 8 night slots
+// Gowri Panchangam ("Nalla Neram") — 8 day + 8 night Tamil slots
 r.gowriPanchangam.day.forEach(s => console.log(s.name, s.qualityName));
 
 // Hora — 12 day + 12 night planetary hours (Chaldean order)
@@ -292,193 +202,157 @@ r.hora.day.forEach(h => console.log(h.planet, h.start, h.end));
 // Do Ghati Muhurta — 15 day + 15 night ~48-min deity-keyed slots (no vara rotation)
 r.doGhatiMuhurta.day.forEach(g => console.log(g.name, g.start, g.end));
 
-// Panchaka Rahita — slices of the day FREE of Panchaka ([] when Panchaka pervades)
+// Panchaka Rahita — slices of the day FREE of Panchaka ([] when it pervades)
 r.panchakaRahita.forEach(slice => console.log(slice.start, slice.end));
 ```
 
-## 8. Special Yogas
-
-Auspicious / inauspicious yogas formed by Vara × Tithi × Nakshatra combinations and
-Moon-from-Sun nakshatra-distance rules. The 28-name **Anandadi Yoga** cycle is also
-returned at sunrise.
+## Special Yogas
 
 ```typescript
 const r = getDailyPanchang(date, loc, { timezone: 330 })!;
 
-// Anandadi Yoga (Vara × Nakshatra cycle of 28 names)
-console.log(r.anandadiYoga.name);   // "Ananda"
-
-// Special yogas active today
+r.anandadiYoga.name;   // 28-cycle name e.g. "Ananda"
 r.specialYogas.forEach(y => {
+  // type: amrit_siddhi | sarvartha_siddhi | ravi_pushya | guru_pushya
+  //     | dwipushkar | tripushkar | jwalamukhi (inauspicious)
+  //     | aadal | vidaal | ravi (Moon-from-Sun nakshatra-distance rules)
   console.log(y.name, y.type);
-  // type: 'amrit_siddhi' | 'sarvartha_siddhi' | 'ravi_pushya' | 'guru_pushya'
-  //     | 'dwipushkar' | 'tripushkar'   ← actions doubled / tripled
-  //     | 'jwalamukhi'                  ← inauspicious (Muhurta-chintamani 6.32)
-  //     | 'aadal' | 'vidaal' | 'ravi'   ← Moon-from-Sun nakshatra-distance rules
 });
 ```
 
-## 9. Festivals
-
-**80+ festivals** spanning pan-Indian, regional, and classical observances:
-
-- **Ekadashi** — 26 named variants (Putrada, Shat Tila, Nirjala, Devshayani, …) with
-  **Smarta / Vaishnava split** via Dashami-viddha rule; Smarta fast emits a `deferralDate`
-  for Dwadashi.
-- **Pradosha** — 7 weekday-qualified variants (Som, Bhauma, Shani, …) on both pakshas.
-- **Sankranti** — transit-based detection plus regional variants (Pongal, Vishu, Baisakhi,
-  Pohela Boishakh, Bohag / Magh / Kati Bihu, Uttarayan, Ayyappa Makara Jyothi, Raja
-  Sankranti, Harela, Sair, Singh Sankranti). **Lohri** fires on the Hindu day immediately
-  preceding Makara Sankranti under Punjab / Haryana / Himachal scopes.
-- **Canonical-time classical festivals** — Ganesh Chaturthi (madhyahna), Shivaratri
-  (nishita), Diwali, Holi, Raksha Bandhan (Bhadra-aware), Karva Chauth (chandrodaya),
-  Janmashtami, Dussehra, Navaratri, Ram Navami, Hanuman Jayanti, Akshaya Tritiya &
-  Parashurama Jayanti (madhyahna-vyapini), Makar Sankranti.
-- **Regional festivals** — Gudi Padwa, Gangaur, Karaga, Bonalu, Varamahalakshmi,
-  Bathukamma, Hariyali / Kajari / Hartalika Teej, Govardhan Puja, Bhai Dooj, Phagli,
-  Jagannath Rath Yatra, Raja Parba 3-day arc.
-- **Regional & seasonal** — Chhath (4-day sequence), Vat Savitri, Upakarma, Onam.
-- **Monthly observances** — Masik Shivaratri, Vinayaka Chaturthi, Masik Karthigai, Pushya
-  days, Shravan Somvar, and other month + weekday patterns.
+## Festivals (80+)
 
-```typescript
-const r = getDailyPanchang(date, loc, { timezone: 330 })!;
+Covers Ekadashi (26 variants, Smarta/Vaishnava split via Dashami-viddha; Smarta
+fast emits a `deferralDate` for Dwadashi), Pradosha, Sankranti + regional
+variants (Pongal, Vishu, Baisakhi, Pohela Boishakh, Bihu, Uttarayan, Lohri…),
+canonical-time classical (Janmashtami, Shivaratri, Ganesh Chaturthi, Diwali,
+Holi, Raksha Bandhan — Bhadra-aware, Karva Chauth, Akshaya Tritiya…),
+regional (Gudi Padwa, Gangaur, Teej variants, Onam, Chhath…), monthly
+observances (Masik Shivaratri, Pushya days, Shravan Somvar…).
 
+```typescript
 r.festivals.forEach(f => {
+  // type: major | minor | ekadashi | smarta_ekadashi | vaishnava_ekadashi
+  //     | pradosha | sankranti | eclipse
   console.log(f.name, f.type, f.deferralDate);
-  // type: 'major' | 'minor' | 'ekadashi'
-  //     | 'smarta_ekadashi' | 'vaishnava_ekadashi'   ← Smarta sets deferralDate
-  //     | 'pradosha' | 'sankranti' | 'eclipse'
 });
 ```
 
-### Regional festival scoping
+### Regional scoping
 
-The `region` option scopes regional festival variants to one Indian state. Pan-Indian
-festivals (Diwali, Holi, Raksha Bandhan, the canonical `sankranti` event) emit regardless.
+`region` scopes regional variants to one Indian state. Pan-Indian festivals
+emit regardless.
 
 ```typescript
-// Default — every regional variant emits on Makar Sankranti day:
-const all = getDailyPanchang(jan14, chennai, { timezone: 330 })!;
-all.festivals.map(f => f.name);
-// → ["Sankranti", "Makar Sankranti", "Pongal", "Uttarayan",
-//    "Magh Bihu", "Ayyappa Makara Jyothi"]
-
-// Scope to Tamil Nadu — drops Bihu/Ayyappa/Uttarayan:
-const tn = getDailyPanchang(jan14, chennai, { timezone: 330, region: 'tamil-nadu' })!;
-tn.festivals.map(f => f.name);
-// → ["Sankranti", "Makar Sankranti", "Pongal"]
-
-// Lohri fires on the Hindu day BEFORE Makara transit, scoped to Punjab/Haryana/Himachal
-const lohri = getDailyPanchang(jan13, amritsar, { timezone: 330, region: 'punjab' })!;
-lohri.festivals.some(f => f.name === 'Lohri');  // true
+// All regional variants (default):
+getDailyPanchang(jan14, chennai, { timezone: 330 })!.festivals.map(f => f.name);
+// → ["Sankranti","Makar Sankranti","Pongal","Uttarayan","Magh Bihu","Ayyappa Makara Jyothi"]
+
+// Tamil Nadu only:
+getDailyPanchang(jan14, chennai, { timezone: 330, region: 'tamil-nadu' })!
+  .festivals.map(f => f.name);
+// → ["Sankranti","Makar Sankranti","Pongal"]
+
+// Lohri fires on the Hindu day BEFORE Makara transit, in Punjab/Haryana/Himachal scope:
+getDailyPanchang(jan13, amritsar, { timezone: 330, region: 'punjab' })!
+  .festivals.some(f => f.name === 'Lohri'); // true
 ```
 
-`FestivalRegion` covers 21 Indian states + `'nepal'` + `'all'` (default). See
-[Types](#types--exports) for the full slug list.
+`FestivalRegion` covers 21 Indian states + `'nepal'` + `'all'` (default). The
+legacy slugs `'tamil'`, `'bengal'`, `'north-india'` are still accepted and
+mapped internally.
 
-## 10. Eclipses
-
-Solar / lunar eclipse detection with subtype, magnitude, observer-horizon visibility, and
-classical pre-eclipse **sutak** impurity window.
+## Eclipses
 
 ```typescript
 const r = getDailyPanchang(date, loc, { timezone: 330 })!;
-
 if (r.eclipse) {
-  console.log(r.eclipse.kind);                 // 'solar' | 'lunar'
-  console.log(r.eclipse.subtype);              // 'partial' | 'total' | 'annular' | 'penumbral'
-  console.log(r.eclipse.magnitude);            // 0..1 fraction of disc obscured at peak
-  console.log(r.eclipse.visibleFromLocation);  // body above horizon at peak?
-  console.log(r.eclipse.start, r.eclipse.peak, r.eclipse.end);
-  console.log(r.eclipse.sutakStart, r.eclipse.sutakEnd);
+  r.eclipse.kind;                 // 'solar' | 'lunar'
+  r.eclipse.subtype;              // 'partial' | 'total' | 'annular' | 'penumbral'
+  r.eclipse.magnitude;            // 0..1 fraction obscured at peak
+  r.eclipse.visibleFromLocation;  // body above horizon at peak?
+  r.eclipse.start; r.eclipse.peak; r.eclipse.end;
+  r.eclipse.sutakStart; r.eclipse.sutakEnd;
   // Sutak: 12 h (4 prahara) before solar, 9 h (3 prahara) before lunar
 }
 
-// Or look ahead:
 import { getUpcomingSolarEclipse, getUpcomingLunarEclipse } from 'panchang-ts';
-const next = getUpcomingSolarEclipse(new Date(), loc, /* withinDays */ 365);
+const next = getUpcomingSolarEclipse(new Date(), loc, 365 /* days */);
 ```
 
-## 11. Planetary Positions
-
-All 9 grahas (Sun → Saturn + Rahu / Ketu) — geocentric, sidereal — with rashi, nakshatra,
-pada, retrograde flag. Optional `nodeType: 'true'` upgrades Rahu / Ketu from mean node
-(±2° worst-case) to Meeus's dominant periodic correction (~±0.6°).
+## Planetary Positions
 
 ```typescript
 import { computePlanetaryPositions, GRAHA_ABBR } from 'panchang-ts';
 
-const grahas = computePlanetaryPositions(new Date(), 'lahiri');
-console.log(grahas.jupiter.rashi.name);       // "Dhanu"
-console.log(grahas.jupiter.degreeInRashi);    // 18.42
-console.log(grahas.jupiter.nakshatra.name);   // "Purva Ashadha"
-console.log(grahas.jupiter.nakshatra.pada);   // 3
-console.log(grahas.saturn.isRetrograde);      // true / false
-console.log(GRAHA_ABBR['Jupiter']);           // "Ju"
+const g = computePlanetaryPositions(new Date(), 'lahiri');
+g.jupiter.rashi.name;       // "Dhanu"
+g.jupiter.degreeInRashi;    // 18.42
+g.jupiter.nakshatra.name;   // "Purva Ashadha"
+g.jupiter.nakshatra.pada;   // 3
+g.saturn.isRetrograde;
+GRAHA_ABBR['Jupiter'];      // "Ju"
 
-// True node (more accurate Rahu / Ketu)
-const grahasTrue = computePlanetaryPositions(new Date(), 'lahiri', undefined, 'true');
+// True node (sharper Rahu/Ketu via Meeus periodic correction)
+const gT = computePlanetaryPositions(new Date(), 'lahiri', undefined, 'true');
 ```
 
-## 12. Vimshottari Dasha
+## Dashas
 
-Maha → Antar → Pratyantar (3-level) breakdown, derived from a birth moment alone or from
-an explicit Moon longitude.
+Five classical systems:
 
 ```typescript
 import {
-  computeVimshottariDasha, computeVimshottariDashaFromBirth,
-  computeVimshottariPratyantar, getSiderealMoonLongitude,
+  computeVimshottariDashaFromBirth, computeVimshottariPratyantar,
+  computeAshtottariDasha, computeYoginiDasha, computeCharaDasha, computeNarayanDasha,
 } from 'panchang-ts';
 
-// Convenience: from birth date alone (Moon longitude derived)
-const dasha = computeVimshottariDashaFromBirth(birthDate, 'lahiri');
-console.log(dasha.currentMahaDashaLord);                // "Rahu"
-console.log(dasha.mahaDashas[0]!.antarDashas[0]!.lord); // "Rahu"
+// 1. Vimshottari — 120-year, 9-lord, with 3-level Maha→Antar→Pratyantar.
+const vim = computeVimshottariDashaFromBirth(birth, 'lahiri');
+const pratyantars = computeVimshottariPratyantar(vim.mahaDashas[0]!.antarDashas[0]!);
 
-// Or pass an explicit Moon sidereal longitude
-const moonLon = getSiderealMoonLongitude(birthDate, 'lahiri');
-const dasha2  = computeVimshottariDasha(birthDate, moonLon);
+// 2. Ashtottari — 108-year, 8-lord cycle (no Ketu).
+const ash = computeAshtottariDasha(birth, moonLon);
 
-// Pratyantar — third-level sub-sub-periods within an Antardasha
-const firstAntar  = dasha.mahaDashas[0]!.antarDashas[0]!;
-const pratyantars = computeVimshottariPratyantar(firstAntar);  // PratyantarDasha[9]
-```
+// 3. Yogini — 36-year, 8 yoginis.
+const yog = computeYoginiDasha(birth, moonLon);
+yog.mahaDashas[0]!.yogini;   // 'Dhanya'
+yog.mahaDashas[0]!.lord;     // 'Jupiter'
+
+// 4. Chara (Jaimini) — sign-based, 9-8-7 years per modality, forward only.
+const cha = computeCharaDasha(birth, loc);
+
+// 5. Narayan (Jaimini) — sign-based, parity-based direction.
+//    Vishama-pada lagna {Aries, Taurus, Gemini, Libra, Scorpio, Sag} → forward
+//    Sama-pada   lagna {Cancer, Leo, Virgo, Capricorn, Aquarius, Pisces} → backward
+const nar = computeNarayanDasha(birth, loc);
+nar.direction;               // 'forward' | 'backward'
 
-## 13. Personal Transits
+// Narayan variable-duration variant (Sanjay Rath):
+const narV = computeNarayanDasha(birth, loc, 'lahiri', { duration: 'variable' });
+narV.mahaDashas[0]!.years;   // 0..12 from rashi-to-lord count (+1 exalt, -1 debil)
+```
 
-Daily transit-based favorability relative to the native's birth Moon. Pass `janmaRashi`
-or `janmaNakshatra` to `getDailyPanchang` and the corresponding field is added to the
-result; or call the helpers directly.
+## Personal Transits
 
 ```typescript
 const r = getDailyPanchang(date, loc, {
   timezone: 330,
-  janmaRashi: 3,        // 0 = Mesha ... 11 = Meena
-  janmaNakshatra: 0,    // 0 = Ashwini ... 26 = Revati
+  janmaRashi: 3,        // 0 = Mesha … 11 = Meena
+  janmaNakshatra: 0,    // 0 = Ashwini … 26 = Revati
 })!;
-
-r.chandraBalam!;  // { house, quality: 'strong' | 'weak', name, englishName }
+r.chandraBalam!;  // { house, quality: 'strong'|'weak', name, englishName }
 r.tarabala!;      // { taraIndex, name, englishName, quality }
 
-// Direct helpers:
-import { computeChandraBalam, computeTarabala, computeSadeSati } from 'panchang-ts';
-
-computeChandraBalam(3 /* janma */, 6 /* transit Moon rashi */);
-computeTarabala(0 /* janma nakshatra */, 4 /* transit Moon nakshatra */);
-
-// Sade Sati — Saturn currently transiting 12th, 1st, or 2nd from natal Moon
-const sadeSati = computeSadeSati(natalMoonRashiIndex, new Date());
+import { computeSadeSati } from 'panchang-ts';
+const ss = computeSadeSati(natalMoonRashiIndex, new Date());
 // → { active, phase: 1|2|3|null, currentArcStart, currentArcEnd, nextArcStart }
 ```
 
-## 14. Birth Chart (Kundli)
+## Birth Chart
 
-Sidereal **Lagna**, **Bhava** under three house systems, **D1 (Rashi)** + six classical
-divisional charts (**D2 Hora**, **D3 Drekkana**, **D7 Saptamsa**, **D9 Navamsa**, **D10
-Dasamsa**, **D12 Dwadasamsa**, **D30 Trimsamsa**) placing all 9 grahas, and **Planetary
-Dignity**.
+Sidereal Lagna, Bhava under three house systems, D1 + six classical divisional
+charts (D2/D3/D7/D9/D10/D12/D30), and Planetary Dignity.
 
 ```typescript
 import {
@@ -489,206 +363,291 @@ import {
 const birth = new Date('1995-08-15T05:30:00Z');
 const loc   = { latitude: 28.6139, longitude: 77.2090 };
 
-// 1. Lagna (sidereal ascendant)
 const lagna = computeLagna(birth, loc, 'lahiri', 'en');
-//   → { siderealLongitude, rashi, degreeInRashi, nakshatra, pada }
 
-// 2. Bhava (12 houses)
-//   - 'whole-sign'  (default classical Vedic) — each rashi is one house
-//   - 'equal'       — each house spans 30° starting at lagna's exact degree
-//   - 'placidus-kp' — true cuspal positions; throws PanchangError('CIRCUMPOLAR') > ±66.5°
+// Bhava — 'whole-sign' (default) | 'equal' | 'placidus-kp'.
+// Placidus-KP throws PanchangError('CIRCUMPOLAR') beyond ±66.5°.
 const houses = computeBhava(birth, loc, { houseSystem: 'whole-sign' });
 
-// 3. D1 (Rashi) chart — lagna + bhava + 9 grahas with house placement
+// D1 — full Rashi chart with 9-graha house placement.
 const d1 = computeRashiChart(birth, loc, { houseSystem: 'whole-sign' });
-d1.planets.find(p => p.planet === 'Jupiter')?.house;          // e.g. 5
+d1.planets.find(p => p.planet === 'Jupiter')?.house;
 d1.planets.find(p => p.planet === 'Saturn')?.isRetrograde;
 
-// 4. D9 (Navamsa) chart — classical sign-based per-rashi-type rule
-const d9 = computeNavamsa(birth, loc);
+// Divisional charts (D2 Hora, D3 Drekkana, D7 Saptamsa, D9 Navamsa,
+// D10 Dasamsa, D12 Dwadasamsa, D30 Trimsamsa).
+const d9  = computeNavamsa(birth, loc);
+const d10 = computeDivisionalChart(birth, loc, 'D10');
+const d30 = computeDivisionalChart(birth, loc, 'D30');
 
-// 5. Divisional charts (D2/D3/D7/D10/D12/D30) via the unified API
-const d10 = computeDivisionalChart(birth, loc, 'D10');   // career
-const d30 = computeDivisionalChart(birth, loc, 'D30');   // misfortune
-//   → { divisional: 'D10', lagnaRashi, planets[] }
-
-// 6. Planetary dignity (BPHS Ch.3-4)
-computeDignity('Mars',    0);   // 'moolatrikona' (Aries)
-computeDignity('Mars',    9);   // 'exalted' (Capricorn)
-computeDignity('Sun',     6);   // 'debilitated' (Libra)
+// Planetary dignity (BPHS Ch.3-4).
+computeDignity('Mars', 0);   // 'moolatrikona' (Aries)
+computeDignity('Mars', 9);   // 'exalted' (Capricorn)
+computeDignity('Sun',  6);   // 'debilitated' (Libra)
 ```
 
-The seven divisional kinds are: **D2 Hora** (wealth), **D3 Drekkana** (siblings),
-**D7 Saptamsa** (children), **D9 Navamsa** (partner / dharma), **D10 Dasamsa** (career),
-**D12 Dwadasamsa** (parents), **D30 Trimsamsa** (misfortune). Each follows its classical
-per-rashi-type mapping per BPHS Ch. 6; D30 uses the non-uniform 5-segment split with
-Mars / Saturn / Jupiter / Mercury / Venus rulership (no Sun / Moon segments).
-
-Birth-chart helpers accept the full ayanamsa set including `'true-chitra'` (True
-Chitrapaksha) and `'thirukanitham'` (Tamil-Vakya). Pass via `options.ayanamsa` or the
-ayanamsa positional arg.
-
-## 15. Compatibility & Doshas
+Birth-chart helpers accept the full ayanamsa set including `'true-chitra'` and
+`'thirukanitham'`.
 
-**Ashtakoot Guna Milan** (36-point marriage compatibility), **Mangal Dosha** (Manglik
-with cancellations), **Kaal Sarp Dosha** (12 named subtypes by Rahu's house), and
-**Pitru Dosha** (ancestral affliction triggers).
+## Compatibility & Doshas
 
 ```typescript
 import {
-  computeAshtakoot, computeMangalDosha,
-  computeKaalSarp, computePitruDosha,
+  computeAshtakoot, computePathuPorutham,
+  computeMangalDosha, computeKaalSarp, computePitruDosha,
 } from 'panchang-ts';
 
-// Ashtakoot — from natal Moons
+// Ashtakoot (North Indian, 36-point) — Varna, Vashya, Tara, Yoni,
+// Graha Maitri, Gana, Bhakoot, Nadi (max 1/2/3/4/5/6/7/8).
 const match = computeAshtakoot(
-  { rashi: 4, nakshatra: 9 },   // boy:  Simha / Magha
-  { rashi: 0, nakshatra: 1 },   // girl: Mesha / Bharani
+  { rashi: 4, nakshatra: 9 },
+  { rashi: 0, nakshatra: 1 },
 );
 // → { totalScore: 0..36, koots: KootScore[8], cancellations: string[] }
-// Koots in canonical order: Varna, Vashya, Tara, Yoni, Graha Maitri, Gana, Bhakoot, Nadi
-// (max scores 1, 2, 3, 4, 5, 6, 7, 8 respectively)
-
-// Mangal Dosha — checks Mars from lagna, Moon, and Venus
-const mangal = computeMangalDosha(d1);
-// → { afflicted, fromLagna, fromMoon, fromVenus, cancellations }
-
-// Kaal Sarp Dosha — all 7 visible planets between Rahu and Ketu axis
-const ksd = computeKaalSarp(d1);
-// → { afflicted, subtype, partial, rahuHouse, ketuHouse }
-// subtype is one of: anant, kulik, vasuki, shankhpal, padma, mahapadma,
-// takshak, karkotak, shankhachud, ghatak, vishdhar, sheshnag — by Rahu's house.
-
-// Pitru Dosha — Sun + Rahu/Ketu in same house, OR Sun + Saturn in 9th
-const pitru = computePitruDosha(d1);
-// → { afflicted, reasons: string[] }
-```
 
-**Documented limitations** — Mangal Dosha cancellations only cover Mars in own sign
-(Aries / Scorpio) or exalted (Capricorn); other classical cancellations (mutual Mangalik,
-Mars-Jupiter aspect, Mars-Saturn conjunction) are not applied. Ashtakoot Vashya koot is
-simplified to single-vashya per rashi. Pitru Dosha surfaces the two highest-frequency
-classical triggers (Sun + node, Sun + Saturn in 9th); the full BPHS catalog of triggers
-(debilitated 9th lord, 9th lord in dusthana, etc.) is out of scope.
+// Opt-in Bhakoot cancellations need extra natal data:
+// `lagnaRashi` enables same-lagna-lord + same-7th-lord rules;
+// `navamsaRashi` enables the same-Navamsa-lord rule.
+const richer = computeAshtakoot(
+  { rashi: 4, nakshatra: 9, lagnaRashi: 7, navamsaRashi: 2 },
+  { rashi: 0, nakshatra: 1, lagnaRashi: 1, navamsaRashi: 5 },
+);
+
+// Pathu Porutham (Tamil/Kerala, 10-fold) — binary pass/fail per koot.
+// Three vetoes (Yoni, Rajju, Vedha) flip `recommended` regardless of count.
+const tp = computePathuPorutham(
+  { rashi: 4, nakshatra: 9 },
+  { rashi: 0, nakshatra: 1 },
+);
+tp.totalPasses;   // 0..10
+tp.recommended;   // no veto + ≥5 passes
+
+// Doshas
+computeMangalDosha(d1);
+//   Mars in 1/2/4/7/8/12 from Lagna, Moon, AND Venus (Drik rule set).
+//   Cancellations: Mars in own sign/exalted, conjunct Jup/Moon/Venus,
+//   or aspected by Jupiter (5/7/9 sign-aspect).
+//   Severity (anshik/purna) is computed pre-cancellation.
+
+computeKaalSarp(d1);
+//   12 subtypes by Rahu's house: anant, kulik, vasuki, shankhpal, padma,
+//   mahapadma, takshak, karkotak, shankhachud, ghatak, vishdhar, sheshnag.
+
+computePitruDosha(d1);
+//   9-rule classical catalog: Sun+Rahu/Ketu/Saturn in 9th; 9th lord
+//   debilitated/combust/dusthana; Saturn or nodes in 9th from natal Moon;
+//   malefics (Mars/Saturn/Rahu/Ketu) in 5th from natal Moon.
+```
 
-## 16. Aspects & Strength
+**Limitations.** Ashtakoot Vashya koot uses single-vashya per rashi.
+Bhakoot Parivartana (rashi-lord exchange) cancellation needs per-graha
+position data not carried by the `NatalMoon` shape and is not modelled.
 
-**Drishti** (planetary aspects per BPHS Ch. 26) and **Shadbala** (six-fold strength per
-BPHS Ch. 27).
+## Strength & Aspects
 
 ```typescript
-import { computeAspects, computeShadbala } from 'panchang-ts';
-
-// Aspects — every graha aspects the 7th house from itself; malefics gain
-// extra special aspects (Mars 4 + 8, Jupiter 5 + 9, Saturn 3 + 10).
-const aspects = computeAspects(d1);
-// → { Sun: [houses…], Moon: [...], …, Saturn: [...], Rahu: [...], Ketu: [...] }
-//
-// Default treats Rahu/Ketu with the 7th-only BPHS-literal rule. Pass
-// { nodeAspects: '5-and-9' } to extend nodes with Jupiter-like 5/9 aspects
-// (BV Raman / KP convention).
-
-// Shadbala — 7 visible grahas, 6 components per planet, in Virupas (60 V = 1 Rupa).
+import {
+  computeAspects, computeShadbala, computeBhavaBala, computeAshtakavarga,
+} from 'panchang-ts';
+
+// Drishti — every graha aspects the 7th; malefics gain extras
+// (Mars 4+8, Jupiter 5+9, Saturn 3+10). Node aspect mode is configurable:
+const aspects = computeAspects(d1);                         // BPHS 7th-only on nodes
+const aspExt  = computeAspects(d1, { nodeAspects: '5-and-9' }); // KP/BV Raman extension
+
+// Shadbala — 7 visible grahas, 6 components, in Virupas (60 V = 1 Rupa).
+// Sthana = Uchcha + Saptavargaja (D1/D2/D3/D7/D9/D12/D30 dignity sum)
+//        + Ojha-Yugma (rashi+navamsa parity) + Drekkana (gender decanate).
+//   Range [0, 420 V]. Dig is directional cusp; Kala = Nathonatha + Paksha;
+//   Chesta is retrograde-bucket; Naisargika is fixed rank; Drik is weighted aspects.
 const bala = computeShadbala(birth, loc);
-// → { Sun: { sthana, dig, kala, chesta, naisargika, drik, total }, Moon: …, … }
-//
-// Components implemented at the simplified-model level used by ProKerala /
-// PyJHora — Uchcha-only Sthana, Dig from directional cusp, Nathonatha + Paksha
-// for Kala, retrograde-bucket Chesta, fixed Naisargika rank, weighted Drik.
+
+// Bhava Bala — 12-bhava strength built on top of Shadbala.
+// Per-bhava: { bhavadhipati, dik, drik, sthana, total }.
+const bhavaBala = computeBhavaBala(birth, loc);
+
+// Ashtakavarga — 12-rashi bindu grids (BPHS Ch. 66).
+const av = computeAshtakavarga(d1);
+av.sarvashtaka;             // 12 cells, each 0..56, total 336
+av.bhinnashtaka.Jupiter;    // 12-cell grid; Jupiter total = 56 (chart-invariant)
+// Other invariants: Sun=47, Moon=49, Mars=39, Mercury=54, Venus=52, Saturn=39.
+
+// Trikona + Ekadhipatya Sodhana reductions (BPHS Ch. 67):
+const avR = computeAshtakavarga(d1, { reductions: true });
+avR.reduced!.sarvashtaka;
 ```
 
-Both functions return additive surface — they do **not** modify the
-`getDailyPanchang` / birth-chart pipelines. Call them on demand.
+Rahu and Ketu are not Ashtakavarga receivers or contributors (classical
+Parashara scheme).
 
-## 17. Dasha Systems
+## Yogas & Karakas
 
-Four classical dasha systems are exposed:
+```typescript
+import { computeYogas, computeJaiminiKarakas } from 'panchang-ts';
+
+// ~25 named yogas — Pancha Mahapurusha (Ruchaka/Bhadra/Hamsa/Malavya/Sasha),
+// lunar (Gajakesari, Sunapha, Anapha, Durudhura, Kemadruma), solar
+// (Budha-Aditya, Veshi, Vasi, Ubhayachari), Raja (kendra/trikona-lord,
+// Dharma-Karmadhipati, Vipareeta, Lakshmi), Dhana (2-11, 5-9, Vasumati),
+// Vargottama, Yogakaraka, Neecha Bhanga, Daridra.
+const yogas = computeYogas(d1);
+// → [{ name, type, reasons[], bhanga?: { applies, reasons[] } }, …]
+
+// Optional cancellation annotations: 5 Pancha Mahapurusha + Gajakesari
+// surface `bhanga` (Sun/Moon conjunct or Jupiter combust/debilitated).
+// Neecha Bhanga: dispositor in kendra from Lagna OR Moon; lord-of-
+// exaltation-rashi in kendra from Lagna or Moon; mutual exchange;
+// dispositor aspecting the debilitated planet.
+
+// Filter by type / pass D9 for Vargottama:
+const d9 = computeNavamsa(birth, loc);
+const all = computeYogas(d1, { types: ['raja','dhana'], navamsa: d9 });
+
+// Jaimini Karakas — Atmakaraka (highest degree-in-rashi) … Darakaraka (lowest).
+const k7 = computeJaiminiKarakas(d1);                              // 7-graha Parashara default
+const k8 = computeJaiminiKarakas(d1, { variant: '8-jaimini' });    // adds Rahu (degree reversed),
+                                                                   // inserts Pitrukaraka at 5th
+```
+
+Yoga and Karaka names are English/transliterated proper nouns and intentionally
+**not** locale-resolved.
+
+## Annual & Sensitive Layers
 
 ```typescript
 import {
-  computeVimshottariDashaFromBirth, computeVimshottariPratyantar,
-  computeAshtottariDasha, computeYoginiDasha, computeCharaDasha,
+  computeVarshaphala, computeTithiPravesha, computeArudhas,
+  computeHoraLagna, computeGhatiLagna, computeBhavaLagna, computeSripatiLagna,
+  computeUpagrahas, computeArgala,
 } from 'panchang-ts';
 
-const birth = new Date('1995-08-15T05:30:00Z');
-const loc   = { latitude: 28.6139, longitude: 77.2090 };
+// Varshaphala — Tajik annual chart for the Nth solar return.
+const v = computeVarshaphala(birth, 30, loc);
+v.solarReturnInstant;
+v.varshaLagna.rashi.name;
+v.muntha.rashi; v.muntha.house;     // muntha = (natalLagnaRashi + 30) mod 12
+v.yearLord;                          // strongest of 4 candidates by Shadbala
+v.sahams.Punya.house;
+v.sahams.Vivaha.rashi;
+// 27 Sahams: Punya, Vidya, Yasas, Mitra, Karma, Vivaha, Putra, Roga, Marana,
+// Rajya, Raja, Bandhu, Dharma, Gnati, Apamrityu, Bhratri, Matri, Pitri, Sama,
+// Bandhana, Karyasiddhi, Vyapara, Sastra, Asha, Labha, Susha, Tapas.
+
+// Tithi Pravesha — annual chart cast when Sun is in natal sidereal sign AND
+// Sun-Moon separation equals natal separation. Preserves natal tithi exactly.
+const tp = computeTithiPravesha(birth, 30, loc);
+tp.natalTithi === tp.praveshTithi;   // always true
+
+// Arudha padas — image/reflection of each bhava. Arudha[0] = Arudha Lagna (AL).
+const a = computeArudhas(d1);
+a[0]!.bhava;            // 1 — AL
+a[0]!.arudhaRashi;      // 0..11
+a[6]!.bhava;            // 7 — Darapada (spouse pada)
+
+// Special lagnas — time-derived sensitive points from sunrise on/before birth.
+computeHoraLagna(birth, loc);     // 30°/hour (1 rashi/hour)
+computeGhatiLagna(birth, loc);    // 75°/hour (1 rashi/24 min)
+computeBhavaLagna(birth, loc);    // 15°/hour (1 rashi/2 hours)
+computeSripatiLagna(birth, loc);  // = natal lagna (cusp 1)
+
+// Sripati cusps 2–12 (opt-in) — 4 angular cusps + trisected intermediates.
+// Defined at every latitude (unlike Placidus).
+const sripati = computeSripatiLagna(birth, loc, 'lahiri', 'en', { includeCusps: true });
+sripati.cusps;  // number[12] of bhava madhyas; cusps[0/3/6/9] = ASC/IC/DSC/MC
+
+// Upagrahas — Gulika, Mandi (rising-asc at Saturn segment start/midpoint),
+// plus Sun-derived Dhuma, Vyatipata, Parivesha, Indrachapa, Upaketu.
+const u = computeUpagrahas(birth, loc);
+u.gulika.longitude; u.gulika.rashi; u.gulika.house;
+
+// Argala (Jaimini) — planets in 2/4/11 from a bhava form Argala (intervention);
+// 3/10/12 form Virodhargala (counter). Each planet hits exactly 6 of 12 bhavas.
+const arg = computeArgala(d1);
+arg[0]!.argala; arg[0]!.virodhargala;
+
+// Trikonargala (5/9 trine, opt-in) — Ketu reversal: 5th-from → virodhaka,
+// 9th-from → source.
+const argT = computeArgala(d1, { includeTrikonargala: true });
+argT[0]!.trikona!.sources;
+argT[0]!.trikona!.virodhakas;
+```
 
-// 1. Vimshottari (120-year, 9-lord) — already in v1; pratyantar (3-level) added in v3
-const vim = computeVimshottariDashaFromBirth(birth);
-const pratyantars = computeVimshottariPratyantar(vim.mahaDashas[0].antarDashas[0]);
+## KP & Prashna
 
-// 2. Ashtottari (108-year, 8-lord, no Ketu) — used when Moon in Krishna Paksha
-const moonLon = /* sidereal Moon longitude */ 145.7;
-const ash = computeAshtottariDasha(birth, moonLon);
-//   → mahaDashas[0..7], lord cycle Sun(6)→Moon(15)→Mars(8)→Mercury(17)→
-//     Saturn(10)→Jupiter(19)→Rahu(12)→Venus(21)
-
-// 3. Yogini (36-year, 8 yoginis with planetary lords)
-const yog = computeYoginiDasha(birth, moonLon);
-yog.mahaDashas[0].yogini;   // 'Dhanya' (Magha → nakshatra 10, 10 % 8 = 2)
-yog.mahaDashas[0].lord;     // 'Jupiter' (Dhanya's planet)
+```typescript
+import {
+  computeKpSubLord, computeKpCuspalSubLords, computeKpSignificators,
+  computePrashnaChart,
+} from 'panchang-ts';
 
-// 4. Chara (Jaimini, sign-based, 9-8-7 years per modality)
-const cha = computeCharaDasha(birth, loc);
-cha.mahaDashas[0].rashi;    // lagna's rashi
-cha.mahaDashas[0].lord;     // sign-lord planet
-cha.mahaDashas[0].years;    // 9 (movable) | 8 (fixed) | 7 (dual)
+// KP sub-lord at any sidereal longitude (243 sub-divisions across the zodiac,
+// proportional to Vimshottari years).
+const info = computeKpSubLord(45.5);    // 15°30' Taurus
+info.signLord;   // 'Venus'
+info.starLord;   // 'Moon'
+info.subLord;
+
+// Cuspal sub-lords (always Placidus-KP — KP's anchor scheme).
+const cusps = computeKpCuspalSubLords(birth, loc);
+cusps.cusps[0]!.subLord;   // ascendant
+cusps.cusps[6]!.subLord;   // descendant
+
+// Significators — for each planet, the houses it signifies via the 4-fold KP rule
+// (occupant + star-lord-occupant + owner + star-lord-owner).
+const sig = computeKpSignificators(d1);
+sig.byPlanet.Sun;
+sig.byHouse[10];
+
+// Prashna (horary) chart — cast at question moment from querent's location.
+const pchart = computePrashnaChart(
+  new Date('2026-05-09T14:30:00Z'),
+  { latitude: 19.0760, longitude: 72.8777 },
+);
+pchart.lagna.rashi.name;
+pchart.bhava.system;        // 'placidus-kp' by default (KP horary anchor)
+pchart.planets[1]!.house;   // Moon — primary mind significator
 ```
 
-**Sourcing:** Vimshottari per Parashara (BPHS Ch. 51); Ashtottari per Satya Acharya;
-Yogini per Sanjay Rath (1999) / Charak; Chara per Jaimini Sutras Ch. 1 (9-8-7 years
-variant). Documented limitations: Chara uses the forward zodiacal direction
-unconditionally (Sundar / Achyutananda variant); the reverse-direction rule for
-even-rashi lagnas is not currently exposed.
+Same return shape as a natal `BirthChart`. Pass `{ houseSystem: 'whole-sign' }`
+to `computePrashnaChart` for traditional Vedic Prashna.
 
-## 18. Muhurta Engine
-
-A configurable rule + scoring engine for picking auspicious dates. Ships with **13 stock
-rules** (vivah, griha pravesh, namakarana, vidyarambh, vahan kharidi, annaprashan,
-mundan, upanayanam, karnavedha, aksharabhyasam, seemantham, shop opening, travel
-start). Each rule is a pure data declaration — write your own without touching the
-engine.
+## Muhurta Engine
 
 ```typescript
 import { scoreMuhurta, findAuspiciousDates, vivahRule } from 'panchang-ts';
 
-// Score a single date
 const r = scoreMuhurta(new Date('2026-05-12'), DELHI, vivahRule, { timezone: 330 });
 // → { date, score: 0..100, passes: boolean, reasons: string[] }
 
-// Find all auspicious dates in a range, sorted by score descending
 const dates = findAuspiciousDates(
   vivahRule,
   new Date('2026-05-01'),
   new Date('2026-05-31'),
   DELHI,
   { timezone: 330 },
-);
-// → MuhurtaDay[] with full panchang attached for each result
+);   // MuhurtaDay[] sorted by score desc; full panchang attached
 
-// Custom rule
+// Custom rule (pure data, no engine code needed)
 const myRule: MuhurtaRule = {
   occasion: 'launch_party',
-  auspiciousVaras: [3, 4, 5],          // Wed/Thu/Fri
-  auspiciousNakshatras: [11, 12, 21],  // Uttara Phalguni / Hasta / Shravana
+  auspiciousVaras: [3, 4, 5],
+  auspiciousNakshatras: [11, 12, 21],
   excludeBhadra: true,
   excludeEkadashi: true,
   excludeAdhikaMasa: true,
 };
 ```
 
-Scoring model: starts at 50 (neutral), +10 per matching auspicious axis (tithi,
-nakshatra, vara, yoga), -15 per matching inauspicious axis, hard exclusions
-(`excludeBhadra` / `excludeEkadashi` / `excludeEclipse` / `excludeAdhikaMasa` /
-`excludeGandaMula` / `excludePanchaka` / `requirePaksha` mismatch) zero the score.
-Special yogas — Amrit Siddhi, Sarvartha Siddhi, Ravi Pushya, Guru Pushya — add +5;
-Jwalamukhi yoga subtracts -10. Final score clamped to 0..100; `passes: true` when
-score ≥ 50.
+13 stock rules: vivah, griha pravesh, namakarana, vidyarambh, vahan kharidi,
+annaprashan, mundan, upanayanam, karnavedha, aksharabhyasam, seemantham, shop
+opening, travel start.
 
-## 19. Calendar Conversion
+Scoring: starts at 50; +10 per matching auspicious axis (tithi / nakshatra /
+vara / yoga), -15 per inauspicious axis, hard exclusions zero the score.
+Special yogas (Amrit Siddhi, Sarvartha Siddhi, Ravi/Guru Pushya) add +5;
+Jwalamukhi subtracts -10. Clamped 0..100; `passes: true` when score ≥ 50.
 
-Gregorian↔Hindu lunar coordinates, Kali Yuga year, regional Hindu New Year, and
-yearly listings of Ekadashis / Sankrantis / festivals / eclipses.
+## Calendar Conversion
 
 ```typescript
 import {
@@ -698,323 +657,136 @@ import {
   getFestivalsInRange, getUpcomingEclipses,
 } from 'panchang-ts';
 
-// Gregorian → Hindu coordinates at sunrise
+// Gregorian → Hindu coords at sunrise
 const h = convertGregorianToHindu(new Date('2026-04-15'), DELHI, { timezone: 330 });
-// → { tithiName, tithi (1..30), pakshaTithi (1..15), paksha,
-//     masaName, masaIndex, isAdhika, vikramSamvat, shakaSamvat,
-//     varaName, varaIndex }
 
-// Hindu → Gregorian: which Gregorian dates correspond to a (samvat, masa, paksha, tithi)?
+// Hindu → Gregorian
 const dates = convertHinduToGregorian(
   { vikramSamvat: 2083, masaIndex: 0, paksha: 'shukla', pakshaTithi: 9 },
   DELHI, { timezone: 330 },
-);
-// dates[0] → Rama Navami in VS 2083
+);   // → Rama Navami in VS 2083
 
-getKaliYugaYear(new Date('2026-04-01'));         // 5127
-getHinduNewYear(2026, 'tamil-nadu', DELHI, { timezone: 330 });  // Puthandu
+getKaliYugaYear(new Date('2026-04-01'));                       // 5127
+getHinduNewYear(2026, 'tamil-nadu', DELHI, { timezone: 330 }); // Puthandu
 
-// Yearly listings
-getEkadashiDatesForYear(2026, DELHI, { timezone: 330 });   // ~24 Date[]
-getSankrantisForYear(2026, DELHI, { timezone: 330 });      // 12 SankrantiEvent[]
-getFestivalsInRange(start, end, DELHI, { timezone: 330 }); // FestivalDay[]
-getUpcomingEclipses(new Date(), DELHI, 5);                  // 5 EclipseInfo[]
+getEkadashiDatesForYear(2026, DELHI, { timezone: 330 });       // ~24 Date[]
+getSankrantisForYear(2026, DELHI, { timezone: 330 });          // 12 SankrantiEvent[]
+getFestivalsInRange(start, end, DELHI, { timezone: 330 });     // FestivalDay[]
+getUpcomingEclipses(new Date(), DELHI, 5);
 ```
 
-`getHinduNewYear` is region-aware: Tamil Nadu / Kerala / Punjab / Bengal / Assam use
-the **solar** (Mesha Sankranti) anchor; everywhere else uses **Chaitra Shukla Pratipada**
-(Ugadi / Gudi Padwa / Cheti Chand). When the Pratipada is a kshaya tithi (e.g. Ugadi
-2026), the function falls back to the Amanta-Chaitra-masa boundary.
+`getHinduNewYear` is region-aware: Tamil Nadu / Kerala / Punjab / Bengal / Assam
+use the **solar** (Mesha Sankranti) anchor; elsewhere uses **Chaitra Shukla
+Pratipada** (Ugadi / Gudi Padwa / Cheti Chand). When Pratipada is a kshaya
+tithi (e.g. Ugadi 2026), falls back to the Amanta-Chaitra-masa boundary.
 
-## 20. Localization
-
-All returned display names respect the `language` option. **English** and **Hindi
-(Devanagari)** are supported.
+## Localization & Configuration
 
 ```typescript
 const hi = getDailyPanchang(date, loc, { timezone: 330, language: 'hi' })!;
+hi.tithis[0].name;          // "कृष्ण चतुर्दशी"
+hi.vara.name;               // "मंगलवार"
+hi.chandramasa.name;        // "माघ"
+hi.choghadiya.day[0].name;  // "अमृत"
+hi.vara.englishName;        // "Tuesday" — englishName always English
 
-console.log(hi.tithis[0].name);              // "कृष्ण चतुर्दशी"
-console.log(hi.vara.name);                   // "मंगलवार"
-console.log(hi.chandramasa.name);            // "माघ"
-console.log(hi.choghadiya.day[0].name);      // "अमृत"
-
-// englishName is always English on Vara / Tarabala / Chandra Balam
-console.log(hi.vara.englishName);            // "Tuesday"
-```
-
-## 21. Configuration
-
-```typescript
+// All options:
 const r = getDailyPanchang(date, loc, {
-  timezone: 330,                          // number (UTC offset in min) or IANA string
-  ayanamsa: 'lahiri',                     // 'lahiri' | 'raman' | 'krishnamurti'
-                                          //   | 'true-chitra' | 'thirukanitham'
-  language: 'en',                         // 'en' | 'hi'
-  masaSystem: 'purnimanta',               // 'purnimanta' | 'amanta'
+  timezone: 330,                          // number (UTC offset min) or IANA string
+  ayanamsa: 'lahiri',                     // lahiri | raman | krishnamurti | true-chitra | thirukanitham
+  language: 'en',                         // en | hi
+  masaSystem: 'purnimanta',               // purnimanta | amanta
   region: 'all',                          // 21 state slugs + 'nepal' + 'all'
   computeEndTimes: true,                  // false → ~5x speedup, names only
-  precision: 'standard',                  // 'standard' (15 iter) | 'high' (25 iter)
+  precision: 'standard',                  // standard (15 iter) | high (25 iter)
   janmaRashi: undefined,                  // pass to add r.chandraBalam
   janmaNakshatra: undefined,              // pass to add r.tarabala
 });
 ```
 
-**Timezone handling** — `timezone` accepts either a number (UTC offset in minutes, e.g.
-`330` for IST) or an IANA zone name (e.g. `'America/New_York'`). IANA strings need `Intl`,
-which older Hermes versions don't fully support — pass a number on those targets. DST
-resolves automatically for IANA zones via the reference date.
+**Timezone.** Number (minutes from UTC, e.g. `330` for IST) or an IANA zone
+name (e.g. `'America/New_York'`). IANA strings need `Intl`, which older Hermes
+versions lack — pass a number on those targets. DST resolves automatically for
+IANA zones.
 
 ---
 
 ## Types & Exports
 
 <details>
-<summary><strong>Core Types</strong> — GeoLocation, TimePeriod</summary>
+<summary><strong>Core, Pancha Anga, Festivals</strong></summary>
 
 ```typescript
-interface GeoLocation {
-  latitude: number;    // -90 to 90
-  longitude: number;   // -180 to 180
-  elevation?: number;  // metres, default 0
-}
-
-interface TimePeriod {
-  start: Date;
-  end: Date;
-}
-```
-</details>
-
-<details>
-<summary><strong>Pancha Anga</strong> — TithiInfo, NakshatraInfo, YogaInfo, KaranaInfo, VaraInfo</summary>
+interface GeoLocation { latitude: number; longitude: number; elevation?: number; }
+interface TimePeriod  { start: Date; end: Date; }
 
-```typescript
 interface TithiInfo {
   index: number;               // 0-29
-  name: string;                // e.g. "Shukla Pratipada"
+  name: string;
   paksha: string;              // "Shukla"/"Krishna" (en), "शुक्ल"/"कृष्ण" (hi)
   number: number;              // 1-15 within the paksha
   completionPercentage: number;
   endTime: Date | null;
 }
-
-interface NakshatraInfo {
-  index: number;               // 0-26
-  name: string;
-  pada: number;                // 1-4
-  degreesInNakshatra: number;
-  completionPercentage: number;
-  endTime: Date | null;
-}
-
-interface DailyTithiInfo extends TithiInfo {
-  startTime: Date | null;      // null when isActiveAtSunrise is true
-  isActiveAtSunrise: boolean;
-}
-
-// DailyNakshatraInfo, DailyYogaInfo, DailyKaranaInfo follow the same pattern.
+// NakshatraInfo, YogaInfo, KaranaInfo follow the same pattern.
+// DailyTithiInfo extends with startTime + isActiveAtSunrise.
 
 interface VaraInfo {
-  index: number;       // 0 = Sunday ... 6 = Saturday
-  name: string;        // e.g. "Raviwara" (localized)
-  shortName: string;   // e.g. "Ravi" (localized)
-  englishName: string; // e.g. "Sunday" (always English)
-}
-
-interface KaranaInfo {
-  index: number;
-  name: string;
-  completionPercentage: number;
-  endTime: Date | null;
-  type: 'fixed' | 'movable';
-}
-
-// endTime / startTime are null when computeEndTimes: false.
-```
-</details>
-
-<details>
-<summary><strong>Lunar Calendar</strong> — ChandraMasaInfo, SamvatInfo, MasaInfo, RashiInfo</summary>
-
-```typescript
-interface ChandraMasaInfo {
-  index: number;            // 0 = Chaitra ... 11 = Phalguna (in the active system)
-  name: string;             // follows masaSystem option
-  isAdhika: boolean;        // true = leap/intercalary month
-  system: 'purnimanta' | 'amanta';
-  amantaIndex: number;
-  amantaName: string;
-  purnimantaIndex: number;
-  purnimantaName: string;
-}
-
-interface SamvatInfo {
-  vikramSamvat: number;  // e.g. 2081
-  shakaSamvat: number;   // e.g. 1946
-}
-
-interface MasaInfo {
-  index: number;  // 0 = Mesha ... 11 = Meena (solar month)
-  name: string;
-}
-
-interface RashiInfo {
-  index: number;  // 0 = Mesha ... 11 = Meena
-  name: string;
-}
-```
-</details>
-
-<details>
-<summary><strong>Time Slots</strong> — Choghadiya, Gowri, Hora, Do Ghati</summary>
-
-```typescript
-type ChoghadiyaQuality = 'auspicious' | 'inauspicious' | 'neutral';
-
-interface ChoghadiyaSlot extends TimePeriod {
-  index: number;
-  name: string;              // e.g. "Amrit", "Kaal" (localized)
-  quality: ChoghadiyaQuality;
-  qualityName: string;       // localized: "Auspicious", "शुभ"
-}
-
-interface ChoghadiyaInfo {
-  day: ChoghadiyaSlot[];     // 8 slots (sunrise -> sunset)
-  night: ChoghadiyaSlot[];   // 8 slots (sunset -> next sunrise)
-}
-
-// GowriSlot / GowriInfo mirror Choghadiya.
-
-interface HoraSlot extends TimePeriod {
-  planet: string;       // "Sun", "Venus", "Mercury", ...
-  planetIndex: number;  // 0-6 in Chaldean order
-}
-
-interface HoraInfo {
-  day: HoraSlot[];      // 12 slots (sunrise -> sunset)
-  night: HoraSlot[];    // 12 slots (sunset -> next sunrise)
-}
-
-interface DoGhatiInfo {
-  day: DoGhatiSlot[];   // 15 ~48-min deity-keyed slots
-  night: DoGhatiSlot[]; // 15 ~48-min deity-keyed slots
-}
-```
-</details>
-
-<details>
-<summary><strong>Special Yogas & Festivals</strong></summary>
-
-```typescript
-interface SpecialYogaInfo {
-  name: string;
-  type:
-    | 'amrit_siddhi' | 'sarvartha_siddhi' | 'ravi_pushya' | 'guru_pushya'
-    | 'dwipushkar'   // Bhadra-tithi + vara + nakshatra ∈ {Mrig, Chitra, Dhan} — doubled
-    | 'tripushkar'   // same Bhadra rules + nakshatra ∈ {Krit, Punar, U.Phal, Vish, U.Ash, P.Bhad} — tripled
-    | 'jwalamukhi'   // inauspicious — tithi × nakshatra (Muhurta-chintamani 6.32)
-    | 'aadal'        // auspicious — Moon-from-Sun nakshatra distance
-    | 'vidaal'       // inauspicious — Moon-from-Sun nakshatra distance
-    | 'ravi';        // auspicious — Moon-from-Sun nakshatra distance (27-scheme)
+  index: number;       // 0 = Sunday … 6 = Saturday
+  name: string;        // localized (e.g. "Raviwara")
+  shortName: string;
+  englishName: string; // always English
 }
 
 interface FestivalInfo {
   name: string;
-  type:
-    | 'major' | 'minor'
-    | 'ekadashi' | 'smarta_ekadashi' | 'vaishnava_ekadashi'
-    | 'pradosha' | 'sankranti' | 'eclipse';
+  type: 'major' | 'minor' | 'ekadashi' | 'smarta_ekadashi' | 'vaishnava_ekadashi'
+      | 'pradosha' | 'sankranti' | 'eclipse';
   description?: string;
-  /** Smarta-only: when Ekadashi is Dashami-viddha, the Dwadashi fast date. */
-  deferralDate?: Date;
+  deferralDate?: Date;  // Smarta Ekadashi → Dwadashi fast date
 }
 
 type FestivalRegion =
-  | 'all'             // default — emits every regional variant
-  // South
+  | 'all'
   | 'tamil-nadu' | 'kerala' | 'karnataka' | 'andhra-pradesh' | 'telangana'
-  // East
   | 'west-bengal' | 'odisha' | 'assam' | 'bihar' | 'jharkhand'
-  // West
   | 'gujarat' | 'maharashtra' | 'goa' | 'rajasthan'
-  // North / Central
   | 'punjab' | 'haryana' | 'himachal-pradesh' | 'uttarakhand'
   | 'uttar-pradesh' | 'madhya-pradesh'
-  // Neighbour
   | 'nepal';
 
-// Pre-v2.1 identifiers — accepted with a one-shot deprecation warning. Removed in v3.
-//   'tamil'       → 'tamil-nadu'
-//   'bengal'      → 'west-bengal'
-//   'north-india' → 'all'
-type LegacyFestivalRegion = 'tamil' | 'bengal' | 'north-india';
+// Legacy slugs accepted (mapped internally): 'tamil' → 'tamil-nadu',
+// 'bengal' → 'west-bengal', 'north-india' → 'all'.
 ```
 
-**Region-scoped festivals** (non-exhaustive):
-
-| Region | Festival names (keys) |
-|---|---|
-| `tamil-nadu` | pongal, puthandu, varamahalakshmi |
-| `kerala` | vishu, ayyappa_makara_jyothi, onam |
-| `karnataka` | karaga, varamahalakshmi |
-| `andhra-pradesh` | varamahalakshmi |
-| `telangana` | bonalu, varamahalakshmi, bathukamma_start, bathukamma_saddula |
-| `west-bengal` | pohela_boishakh, bhai_dooj |
-| `odisha` | singh_sankranti, raja_pahili, raja_sankranti, raja_basi |
-| `assam` | bohag_bihu, magh_bihu, kati_bihu |
-| `bihar` | singh_sankranti, hariyali_teej, govardhan_puja, bhai_dooj |
-| `gujarat` | uttarayan, govardhan_puja, bhai_dooj |
-| `maharashtra` | gudi_padwa, hartalika_teej, bhai_dooj |
-| `goa` | gudi_padwa |
-| `rajasthan` | gangaur, hariyali_teej, kajari_teej, hartalika_teej, govardhan_puja, bhai_dooj |
-| `punjab` | baisakhi, lohri, govardhan_puja |
-| `haryana` | baisakhi, lohri, govardhan_puja, bhai_dooj |
-| `himachal-pradesh` | sair, phagli, lohri |
-| `uttarakhand` | harela |
-| `uttar-pradesh` | hariyali_teej, kajari_teej, hartalika_teej, govardhan_puja, bhai_dooj |
-| `madhya-pradesh` | hariyali_teej, kajari_teej, hartalika_teej |
-| `nepal` | singh_sankranti, bhai_dooj |
 </details>
 
 <details>
-<summary><strong>Eclipses (Grahan)</strong> — EclipseInfo</summary>
+<summary><strong>Eclipses & Bhadra</strong></summary>
 
 ```typescript
-type EclipseSubtype = 'partial' | 'total' | 'annular' | 'penumbral';
-
 interface EclipseInfo {
   kind: 'solar' | 'lunar';
-  subtype: EclipseSubtype;
-  start: Date;              // UTC — observable phase begins
-  peak: Date;               // UTC — greatest eclipse
-  end: Date;                // UTC — observable phase ends
+  subtype: 'partial' | 'total' | 'annular' | 'penumbral';
+  start: Date; peak: Date; end: Date;
   visibleFromLocation: boolean;
-  magnitude: number;        // fraction of disc obscured at peak, [0, 1]
-  sutakStart: Date;         // 12 h before solar / 9 h before lunar
-  sutakEnd: Date;           // coincides with eclipse end (moksha)
+  magnitude: number;        // [0, 1] at peak
+  sutakStart: Date;         // 12 h pre-solar / 9 h pre-lunar
+  sutakEnd: Date;
   description: string;
 }
-```
-</details>
-
-<details>
-<summary><strong>Bhadra Kala</strong> — BhadraInfo</summary>
 
-```typescript
 interface BhadraInfo {
-  start: Date;
-  end: Date;
-  /** 'earth' = malefic for all work; 'heaven' / 'paatal' = non-terrestrial, milder. */
-  location: 'earth' | 'heaven' | 'paatal';
-  /** True when Bhadra is active at some point during the Hindu day window. */
+  start: Date; end: Date;
+  location: 'earth' | 'heaven' | 'paatal';   // 'earth' = malefic for all work
   isActive: boolean;
 }
 ```
+
 </details>
 
 <details>
-<summary><strong>Jyotish</strong> — Graha positions, Vimshottari Dasha, Chandra Balam, Tarabala</summary>
+<summary><strong>Jyotish</strong></summary>
 
 ```typescript
 type GrahaName = 'Sun' | 'Moon' | 'Mars' | 'Mercury' | 'Jupiter'
@@ -1022,49 +794,44 @@ type GrahaName = 'Sun' | 'Moon' | 'Mars' | 'Mercury' | 'Jupiter'
 
 interface GrahaPosition {
   planet: GrahaName;
-  siderealLongitude: number;   // degrees [0, 360)
+  siderealLongitude: number;
   rashi: RashiInfo;
-  degreeInRashi: number;       // [0, 30)
+  degreeInRashi: number;
   nakshatra: NakshatraInfo;
-  isRetrograde: boolean;       // always false for Sun/Moon; always true for Rahu/Ketu
-}
-
-interface PlanetaryPositions {
-  sun: GrahaPosition; moon: GrahaPosition; mars: GrahaPosition;
-  mercury: GrahaPosition; jupiter: GrahaPosition; venus: GrahaPosition;
-  saturn: GrahaPosition; rahu: GrahaPosition; ketu: GrahaPosition;
+  isRetrograde: boolean;     // always false for Sun/Moon; always true for Rahu/Ketu
 }
 
 type DashaLord = 'Ketu' | 'Venus' | 'Sun' | 'Moon' | 'Mars'
               | 'Rahu' | 'Jupiter' | 'Saturn' | 'Mercury';
 
-interface AntarDasha   { lord: DashaLord; startDate: Date; endDate: Date; }
-interface MahaDasha    { lord: DashaLord; startDate: Date; endDate: Date;
-                         years: number; antarDashas: AntarDasha[]; }
+interface MahaDasha   { lord: DashaLord; startDate: Date; endDate: Date;
+                        years: number; antarDashas: AntarDasha[]; }
 interface VimshottariDashaResult {
   currentMahaDashaLord: DashaLord;
   currentIndex: number;
-  mahaDashas: MahaDasha[];   // 9-entry sequence starting from birth
+  mahaDashas: MahaDasha[];
 }
 
 interface ChandraBalamInfo {
-  house: number;                       // 1 = janma rashi; 12 = rashi before janma
-  quality: 'strong' | 'weak';          // Shubha houses = 1,3,6,7,10,11
-  englishName: string;                 // "Shubha" | "Ashubha"
-  name: string;                        // localized
+  house: number;                  // 1 = janma rashi; 12 = rashi before janma
+  quality: 'strong' | 'weak';     // Shubha houses = 1,3,6,7,10,11
+  englishName: string;            // "Shubha" | "Ashubha"
+  name: string;
 }
 
 interface TarabalaInfo {
-  taraIndex: number;                   // 0..8 in the 9-tara cycle from janma nakshatra
-  englishName: string;                 // "Janma" | "Sampat" | "Vipat" | "Kshema" | "Pratyari"
-                                       // | "Sadhaka" | "Vadha" | "Mitra" | "Ati-Mitra"
+  taraIndex: number;              // 0..8 in 9-tara cycle from janma nakshatra
+  englishName: string;            // Janma | Sampat | Vipat | Kshema | Pratyari
+                                  // | Sadhaka | Vadha | Mitra | Ati-Mitra
   name: string;
   quality: 'auspicious' | 'inauspicious';
 }
 ```
+
 </details>
 
-### Full export list
+<details>
+<summary><strong>Full export list</strong></summary>
 
 ```typescript
 // Primary entry points
@@ -1085,15 +852,29 @@ computeMadhyahna, computePratahSandhya, computeSayahnaSandhya
 // Eclipses
 getUpcomingSolarEclipse, getUpcomingLunarEclipse, getEclipseDuringDay
 
-// Jyotish
+// Jyotish — planets, dashas, transits
 computePlanetaryPositions, GRAHA_ABBR
 computeVimshottariDasha, computeVimshottariDashaFromBirth, computeVimshottariPratyantar
-computeAshtottariDasha, computeYoginiDasha, computeCharaDasha
-computeChandraBalam, computeTarabala
+computeAshtottariDasha, computeYoginiDasha, computeCharaDasha, computeNarayanDasha
+computeChandraBalam, computeTarabala, computeSadeSati
+
+// Jyotish — chart
 computeLagna, computeBhava, computeRashiChart, computeNavamsa, computeDivisionalChart
-computeAspects, computeShadbala
-computeAshtakoot, computeMangalDosha, computeKaalSarp, computePitruDosha
-computeSadeSati, computeDignity
+computeHoraLagna, computeGhatiLagna, computeBhavaLagna, computeSripatiLagna
+computeDignity
+
+// Jyotish — strength, yogas, sensitive
+computeAspects, computeShadbala, computeBhavaBala, computeAshtakavarga
+computeYogas, computeJaiminiKarakas
+computeVarshaphala, computeTithiPravesha, computeArudhas, computeUpagrahas, computeArgala
+
+// Jyotish — compatibility, doshas
+computeAshtakoot, computePathuPorutham
+computeMangalDosha, computeKaalSarp, computePitruDosha
+
+// KP / Prashna
+computeKpSubLord, computeKpCuspalSubLords, computeKpSignificators
+computePrashnaChart
 
 // Muhurta engine
 scoreMuhurta, findAuspiciousDates, STOCK_MUHURTA_RULES
@@ -1110,31 +891,31 @@ getEkadashiDatesForYear, getSankrantisForYear, getFestivalsInRange, getUpcomingE
 PanchangError
 ```
 
+</details>
+
 ---
 
 ## React Native / Hermes
 
-Works with Expo and bare React Native (Hermes engine). Pass `timezone` as a **number** —
-IANA timezone strings (`'Asia/Kolkata'`) require `Intl`, which older Hermes versions don't
-fully support.
+Works with Expo and bare React Native (Hermes engine). Pass `timezone` as a
+**number** — IANA strings need `Intl`, which older Hermes versions lack.
 
-**Two-pass rendering** for smooth UI:
+Two-pass rendering pattern for smooth UI:
 
 ```typescript
 import { getDailyPanchang } from 'panchang-ts';
 import { InteractionManager } from 'react-native';
 
-// Pass 1 — instant, names only (~0.1 ms on Node, <100 ms on Hermes)
+// Pass 1 — instant, names only (~0.1 ms Node, <100 ms Hermes)
 const fast = getDailyPanchang(date, location, {
   timezone: 330,
   computeEndTimes: false,
 });
-setState(fast); // show names immediately
+setState(fast);
 
-// Pass 2 — background, full with end-times (~0.5 ms on Node, <500 ms on Hermes)
+// Pass 2 — background, full with end-times (~0.5 ms Node, <500 ms Hermes)
 InteractionManager.runAfterInteractions(() => {
-  const full = getDailyPanchang(date, location, { timezone: 330 });
-  setState(full); // update with transition times
+  setState(getDailyPanchang(date, location, { timezone: 330 }));
 });
 ```
 
@@ -1142,66 +923,54 @@ InteractionManager.runAfterInteractions(() => {
 
 ## Accuracy
 
-7,156 tests passing across 81 files, including fixtures cross-verified against reference
-panchang calculations spanning 2025–2026 across 10 Indian cities, plus New York, London,
-Sydney, Dubai, and Singapore (diaspora fixtures cover DST transitions on
+8,103 tests across 96 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 | Validation |
-|---------|----------|------------|
-| Sunrise / Sunset | ≤29 s observed vs reference minute-midpoint (±45 s tolerance) | 16 assertions |
-| Moonrise / Moonset | Meeus apparent-upper-limb (refraction + parallax); ~3–5 min vs simpler-horizon authorities is expected | Strict fixtures |
-| Tithi, Nakshatra, Yoga, Karana names | Exact match vs reference | Strict fixtures |
-| Tithi / Nakshatra / Yoga / Karana end-times | ±3 min tolerance, max 2.01 min observed | 20 assertions |
-| Ayanamsa | ±0.005° vs Swiss Ephemeris | Unit tests |
-| Planetary positions (Sun–Saturn) | ±0.02° vs reference sidereal | Fixtures |
-| Planetary positions (Rahu/Ketu, mean node) | ≤0.5° typical; ±2° tolerance | Fixtures |
-| Planetary positions (Rahu/Ketu, true node) | ≤0.6° typical (Meeus periodic correction) | Fixtures |
-| Rashi / Nakshatra / Retrograde flag | Exact match vs reference | Fixtures |
-| Festival dates | 12 cross-verified festivals (2025–2026) — see caveats below | Fixtures |
-| Choghadiya / Hora / Gowri slots | Derived from sunrise/sunset — inherits ±2 min | — |
-| Madhyahna midpoint, Anandadi Yoga, Ganda Mula active flag | Exact match across 50 reference fixtures | Cross-verify suite |
-| Pratah / Sayahna Sandhya start + end | ±2 min across all 50 fixtures | Cross-verify suite |
-| Varjyam start + end | ±2 min on every emit (transition days return `null` by design) | Cross-verify suite |
-| Lagna sidereal longitude | Cross-checked against Jagannath Hora reference charts | Birth-chart fixtures |
-| D1 (Rashi) & D9 (Navamsa) house placements | Exact match vs reference for 9-graha placement | Birth-chart fixtures |
-| Ashtakoot Guna Milan total score | ±1 point per pair across 30+ matched pairs | Match fixtures |
-| Sade Sati arc start / end | ±1–2 days vs authoritative ephemerides | Saturn-transit fixtures |
-
-**Detection sourcing notes.** **Aadal / Vidaal** follow the classical Moon-from-Sun
-nakshatra-distance rule (AstroShastra, HoraSarvam, Ernst Wilhelm), NOT the popular
-Tamil-Vakya weekday rule used by some online panchangs — output may differ from sites that
-use the weekday rule. **Varjyam** emits the sunrise-anchored nakshatra's window only —
-printed panchangs may show a second window on nakshatra-transition days. **Do Ghati
-Muhurta** does not rotate by weekday: the same 30-name deity-keyed sequence applies every
-day, verified against multiple reference sources for distinct weekdays.
+| 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 |
+| Tithi / Nakshatra / Yoga / Karana names | Exact match vs reference |
+| Tithi / Nakshatra / Yoga / Karana end-times | ±3 min tolerance, max 2.01 min observed |
+| Ayanamsa | ±0.005° vs Swiss Ephemeris |
+| Planetary positions (Sun–Saturn) | ±0.02° sidereal |
+| Planetary positions (Rahu/Ketu, mean node) | ≤0.5° typical; ±2° tolerance |
+| Planetary positions (Rahu/Ketu, true node) | ≤0.6° typical (Meeus periodic correction) |
+| 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 |
+| Sade Sati arc start/end | ±1–2 days vs authoritative ephemerides |
+
+**Detection notes.** **Aadal / Vidaal** follow the classical Moon-from-Sun
+nakshatra-distance rule (AstroShastra, HoraSarvam, Ernst Wilhelm), NOT the
+Tamil-Vakya weekday rule used by some online panchangs. **Varjyam** emits the
+sunrise-anchored nakshatra's window only. **Do Ghati Muhurta** does not rotate
+by weekday — the same 30-name deity-keyed sequence applies every day.
 
 ### Festival Detection — Documented Tradeoff
 
-The library uses **tithi-at-sunrise** to resolve a festival to a calendar day. Some
-traditional panchang authorities apply other classical rules (tithi-at-midnight,
-madhyahna-vyapini, kshaya-tithi handling) for certain festivals; where those rules pick a
-different day, our output can drift ±1 day. This is a rule-choice tradeoff, not a
-computation bug.
+The library uses **tithi-at-sunrise** to resolve a festival to a calendar day.
+Some authorities use other classical rules for certain festivals; where those
+rules pick a different day, output can drift ±1 day:
 
-| Alternative classical rule | Festivals affected |
-|----------------------------|--------------------|
+| Alternative rule | Affects |
+|---|---|
 | Tithi-at-midnight | Krishna Janmashtami, Maha Shivaratri, Diwali / Lakshmi Puja |
-| Madhyahna-vyapini (tithi overlapping noon) | Ganesh Chaturthi on edge years, Akshaya Tritiya 2026 |
-| Kshaya-tithi handling (tithi never at sunrise) | Ugadi 2026-03-19 (Pratipada is Kshaya) |
+| Madhyahna-vyapini | Ganesh Chaturthi (edge years), Akshaya Tritiya 2026 |
+| Kshaya-tithi handling | Ugadi 2026-03-19 (Pratipada is Kshaya) |
 
-If strict parity with a specific panchang authority matters for your use case, cross-check
-the above festival set for the target year. Everything else — Holi, Ugadi (non-Kshaya
-years), Rama Navami, Raksha Bandhan, Ganesh Chaturthi (normal years), Navaratri,
-Dussehra, Karva Chauth, Hanuman Jayanti — matches the canonical date across 2025 and 2026
-fixtures.
+Everything else — Holi, Ugadi (non-Kshaya years), Rama Navami, Raksha Bandhan,
+Ganesh Chaturthi (normal years), Navaratri, Dussehra, Karva Chauth, Hanuman
+Jayanti — matches the canonical date across 2025 and 2026 fixtures.
 
 ---
 
 ## Performance
 
 | Mode | Node.js | Hermes (budget Android) |
-|------|---------|------------------------|
+|---|---|---|
 | Names-only (`computeEndTimes: false`) | ~0.1 ms | <100 ms |
 | Full with end-times | ~0.5 ms | <500 ms |
 
@@ -1219,40 +988,42 @@ try {
   getDailyPanchang(date, location, options);
 } catch (e) {
   if (e instanceof PanchangError) {
-    console.error(e.code);    // e.g. 'INVALID_LATITUDE', 'INVALID_TIMEZONE'
+    console.error(e.code);     // e.g. 'INVALID_LATITUDE', 'INVALID_TIMEZONE'
     console.error(e.message);
   }
 }
 ```
 
-Error codes: `INVALID_DATE`, `INVALID_LATITUDE`, `INVALID_LONGITUDE`, `INVALID_ELEVATION`,
-`INVALID_TIMEZONE`, `INVALID_AYANAMSA`, `TIMEZONE_RESOLUTION_FAILED`, `NO_SUNRISE`,
-`NO_SUNSET`, `SEARCH_DIVERGED`, `CIRCUMPOLAR` (Placidus-KP houses above ±66.5°).
+Error codes: `INVALID_DATE`, `INVALID_LATITUDE`, `INVALID_LONGITUDE`,
+`INVALID_ELEVATION`, `INVALID_TIMEZONE`, `INVALID_AYANAMSA`,
+`TIMEZONE_RESOLUTION_FAILED`, `NO_SUNRISE`, `NO_SUNSET`, `SEARCH_DIVERGED`,
+`CIRCUMPOLAR` (Placidus-KP houses above ±66.5°).
 
-**Polar locations (no sunrise / no sunset):** `getDailyPanchang` and `getInstantPanchang`
-return `null` rather than throwing — the Hindu day is undefined when sunrise can't be
+**Polar locations.** `getDailyPanchang` and `getInstantPanchang` return `null`
+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 for the Moon).
+`PanchangError(NO_SUNRISE)` / `PanchangError(NO_SUNSET)` for direct callers
+who need the precise reason. `getMoonrise` / `getMoonset` return `null` (normal
+for the Moon).
 
 ---
 
 ## Compatibility
 
 | Environment | Support |
-|-------------|---------|
+|---|---|
 | Node.js 18+ | Supported |
 | React Native (Hermes) | Supported (pass `timezone` as number) |
 | Expo (managed + bare) | Supported |
-| Browser (modern) | Supported (ESM build) |
+| Browser (modern, ESM) | Supported |
 | Browser (legacy / IE) | Not supported |
 
 ---
 
 ## Acknowledgements
 
-[astronomy-engine](https://github.com/cosinekitty/astronomy) by Don Cross — the sole
-runtime dependency. MIT licensed.
+[astronomy-engine](https://github.com/cosinekitty/astronomy) by Don Cross — the
+sole runtime dependency. MIT licensed.
 
 ## License