panchang-ts 0.6.1 → 1.0.0

package/README.md

@@ -1,31 +1,32 @@
 # panchang-ts
 
+[![npm version](https://img.shields.io/npm/v/panchang-ts)](https://www.npmjs.com/package/panchang-ts)
+
 Pure TypeScript Hindu Panchang (almanac) calculations. Zero native dependencies.
 Works offline in React Native (Hermes), Node.js, and browsers.
 
-## Features
+**Fast** (~0.1 ms names-only, ~0.5 ms full) | **Typed** (full TypeScript types) | **Offline** (pure JS math, no network)
+
+---
 
-- **Pancha Anga (5 limbs):** Tithi, Nakshatra, Yoga, Karana, Vara — with mid-day transition times
-- **Lunar calendar:** Chandra Masa (lunar month + Adhika/leap detection), Vikram Samvat, Shaka Samvat
-- **Zodiac & asterism:** Chandra Rashi (Moon sign), Surya Nakshatra (Sun's asterism)
-- **Muhurta:** Brahma Muhurta, Abhijit Muhurta
-- **Inauspicious periods:** Rahu Kalam, Gulika Kalam, Yamaganda
-- **Choghadiya:** 16 time slots (8 day + 8 night), each named and rated auspicious/neutral/inauspicious
-- **Gowri Panchangam:** 16 Gowri Nalla Neram slots (8 day + 8 night) with 8-name cycle, vara-based starting index
-- **Hora:** 24 planetary hours per day (12 day + 12 night) in Chaldean order
-- **Astronomical events:** Sunrise, Sunset, Moonrise, Moonset
-- **Panchaka detection:** Flag when Moon is in the last 5 nakshatras (Dhanishta 3rd pada → Revati)
-- **Special Yogas:** Amrit Siddhi, Sarvartha Siddhi, Ravi Pushya, Guru Pushya — detected from Vara × Tithi/Nakshatra tables
-- **Dur Muhurta:** Two ~48-minute inauspicious windows per day, position varies by Vara
-- **Festival detection:** 24 major pan-Indian festivals, recurring Ekadashi & Pradosha Vrata, Sankranti; skips Adhika (leap) months automatically
-- **Daily mode:** Full sunrise-to-sunrise day with all element transitions
-- **Instant mode:** Elements active at an exact moment (birth charts, muhurta selection)
-- **3 ayanamsa systems:** Lahiri (default), B.V. Raman, KP (Krishnamurti)
-- **3 languages:** English, Sanskrit (Devanagari), Hindi
-- **Jyotish (Vedic astrology):** All 9 graha positions (geocentric, sidereal), Vimshottari Dasha with Antardasha breakdown
-- **React Native compatible:** Pure JS math, no native modules, tested on Hermes
-- **Fast:** ~0.1 ms names-only on Node.js; <100 ms on budget Android (Hermes)
-- **Typed:** Full TypeScript types for every result and option
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [API Reference](#api-reference)
+  - [`getDailyPanchang`](#getdailypanchangdate-location-options)
+  - [`getInstantPanchang`](#getinstantpanchangdate-location-options)
+  - [Options](#options)
+  - [Low-level Utilities](#low-level-utilities)
+- [Types](#types)
+- [React Native / Hermes](#react-native--hermes)
+- [Accuracy](#accuracy)
+- [Performance](#performance)
+- [Error Handling](#error-handling)
+- [Compatibility](#compatibility)
+
+---
 
 ## Install
 
@@ -53,10 +54,10 @@ console.log(result.tithis[0].name);           // "Krishna Chaturdashi"
 console.log(result.nakshatras[0].name);       // "Mrigashira"
 console.log(result.vara.name);                // "Mangalavara"
 
-// Lunar calendar
-console.log(result.chandramasa.name);         // "Pausha"
+// Lunar calendar (Purnimanta by default)
+console.log(result.chandramasa.name);         // "Magha"
+console.log(result.chandramasa.amantaName);   // "Pausha" (South Indian)
 console.log(result.samvat.vikramSamvat);      // 2081
-console.log(result.samvat.shakaSamvat);       // 1946
 
 // Zodiac
 console.log(result.chandraRashi.name);        // "Mithuna" (Moon in Gemini)
@@ -66,7 +67,7 @@ console.log(result.suryaNakshatra.name);      // "Uttara Ashadha"
 console.log(result.sunrise);                  // Date (read via getUTC*)
 console.log(result.moonrise);                 // Date | null
 
-// Muhurta
+// Muhurta & inauspicious periods
 console.log(result.brahmaMuhurta);            // { start: Date, end: Date }
 console.log(result.rahuKalam);                // { start: Date, end: Date }
 
@@ -75,36 +76,26 @@ result.choghadiya.day.forEach(slot => {
   console.log(slot.name, slot.qualityName);   // "Amrit", "Auspicious"
 });
 
-// Panchaka
-console.log(result.panchaka);                 // true | false
+// Gowri Panchangam — 8 daytime slots
+result.gowriPanchangam.day.forEach(slot => {
+  console.log(slot.name, slot.qualityName);   // "Amrit", "Auspicious"
+});
 
 // Special Yogas active today
 result.specialYogas.forEach(yoga => {
   console.log(yoga.name, yoga.type);          // "Guru Pushya Yoga", "guru_pushya"
 });
 
-// Dur Muhurta — two inauspicious windows
-const [dm1, dm2] = result.durMuhurta;
-console.log(fmt(dm1.start), '-', fmt(dm1.end)); // e.g. "11:36 - 12:24"
-console.log(fmt(dm2.start), '-', fmt(dm2.end));
-
 // Festivals today
 result.festivals.forEach(f => {
-  console.log(f.name, f.type);               // "Diwali", "major"
-});
-
-// Gowri Panchangam — 8 daytime slots
-result.gowriPanchangam.day.forEach(slot => {
-  console.log(slot.name, slot.qualityName);   // "Amrit", "Auspicious"
+  console.log(f.name, f.type);               // "Makar Sankranti", "major"
 });
-
-
 ```
 
-## Reading Output Times
+### Reading Output Times
 
 All `Date` objects in the result are **offset-adjusted** to the requested timezone.
-**Always read time components via `getUTC*` methods:**
+Always read time components via `getUTC*` methods:
 
 ```typescript
 const sunrise = result.sunrise;
@@ -125,6 +116,64 @@ Do **not** use `.getHours()` — it uses your system timezone, which may differ.
 `moonrise` and `moonset` can be `null` — the Moon occasionally does not rise or set
 on a given calendar day, which is normal.
 
+### Language & Masa System
+
+```typescript
+// Sanskrit names (Devanagari)
+const sa = getDailyPanchang(date, location, {
+  timezone: 330,
+  language: 'sa',
+});
+console.log(sa.tithis[0].name);              // "कृष्ण चतुर्दशी"
+console.log(sa.vara.name);                    // "मङ्गलवारः"
+
+// Hindi names
+const hi = getDailyPanchang(date, location, {
+  timezone: 330,
+  language: 'hi',
+});
+console.log(hi.tithis[0].name);              // "कृष्ण चतुर्दशी"
+
+// Amanta (South Indian) masa system
+const amanta = getDailyPanchang(date, location, {
+  timezone: 330,
+  masaSystem: 'amanta',
+});
+console.log(amanta.chandramasa.name);         // Amanta month name
+console.log(amanta.chandramasa.system);       // "amanta"
+```
+
+---
+
+## Features
+
+### Pancha Anga (5 Limbs)
+Tithi, Nakshatra, Yoga, Karana, Vara — with transition times throughout the day.
+
+### Lunar Calendar
+Chandra Masa with Adhika (leap month) detection, both **Purnimanta** (North Indian, default) and **Amanta** (South Indian) systems, Vikram Samvat, Shaka Samvat.
+
+### Muhurta & Auspicious Timing
+Brahma Muhurta, Abhijit Muhurta, Choghadiya (16 slots), Gowri Panchangam / Nalla Neram (16 slots), Hora (24 planetary hours), Dur Muhurta (2 inauspicious windows).
+
+### Inauspicious Periods
+Rahu Kalam, Gulika Kalam, Yamaganda, Panchaka detection.
+
+### Special Yogas & Festivals
+Amrit Siddhi, Sarvartha Siddhi, Ravi Pushya, Guru Pushya yoga detection. 24 major pan-Indian festivals, recurring Ekadashi & Pradosha Vrata, Sankranti — Adhika months auto-skipped.
+
+### Jyotish (Vedic Astrology)
+All 9 graha positions (geocentric, sidereal) with rashi, nakshatra, pada, and retrograde status. Vimshottari Dasha with Antardasha breakdown — from a birth moment alone or from an explicit Moon longitude. Chandra Balam (transit-Moon favorability relative to janma rashi).
+
+### Astronomy
+Sunrise, Sunset, Moonrise, Moonset, Chandra Rashi (Moon sign), Surya Nakshatra.
+
+### Localization
+3 languages: **English**, **Sanskrit** (Devanagari), **Hindi**. All returned display strings respect the `language` option.
+
+### Configuration
+3 ayanamsa systems (Lahiri, B.V. Raman, KP), 2 masa systems (Purnimanta, Amanta), adjustable precision, optional fast mode (`computeEndTimes: false` for ~5x speedup).
+
 ---
 
 ## API Reference
@@ -155,34 +204,33 @@ const result = getDailyPanchang(
 | `nextSunrise` | `Date` | Following day's sunrise (offset-adjusted) |
 | `dayDurationMinutes` | `number` | Length of daytime in minutes |
 | `nightDurationMinutes` | `number` | Length of night in minutes |
-| `tithis` | `DailyTithiInfo[]` | Tithis active during the day (usually 1–2) |
+| `tithis` | `DailyTithiInfo[]` | Tithis active during the day (usually 1-2) |
 | `nakshatras` | `DailyNakshatraInfo[]` | Nakshatras active during the day |
 | `yogas` | `DailyYogaInfo[]` | Yogas active during the day |
-| `karanas` | `DailyKaranaInfo[]` | Karanas active during the day (usually 2–4) |
+| `karanas` | `DailyKaranaInfo[]` | Karanas active during the day (usually 2-4) |
 | `vara` | `VaraInfo` | Weekday (Vara) |
 | `rahuKalam` | `TimePeriod` | Rahu Kalam start/end |
 | `gulikaKalam` | `TimePeriod` | Gulika Kalam start/end |
 | `yamaganda` | `TimePeriod` | Yamaganda start/end |
 | `abhijitMuhurta` | `TimePeriod` | Abhijit Muhurta start/end |
-| `brahmaMuhurta` | `TimePeriod` | Brahma Muhurta — two muhurtas (dayDuration/30 each) before sunrise; ends one muhurta before sunrise (≈ 48–24 min window for typical 12-h days) |
+| `brahmaMuhurta` | `TimePeriod` | Brahma Muhurta — two muhurtas before sunrise |
 | `masa` | `MasaInfo` | Solar month (Saura Masa) |
 | `chandramasa` | `ChandraMasaInfo` | Lunar month + Adhika (leap) flag |
 | `samvat` | `SamvatInfo` | Vikram Samvat and Shaka Samvat year numbers |
 | `chandraRashi` | `RashiInfo` | Moon's zodiac sign (changes every ~2.5 days) |
-| `suryaNakshatra` | `RashiInfo` | Sun's nakshatra (changes every ~13–14 days) |
-| `choghadiya` | `ChoghadiyaInfo` | 8 day slots + 8 night slots, each named and rated |
-| `gowriPanchangam` | `GowriInfo` | 8 day + 8 night Gowri Nalla Neram slots, each named and rated |
-
-| `hora` | `HoraInfo` | 12 day horas + 12 night horas, each with ruling planet |
-| `moonrise` | `Date \| null` | Moonrise (offset-adjusted); `null` if none that day |
-| `moonset` | `Date \| null` | Moonset (offset-adjusted); `null` if none that day |
+| `suryaNakshatra` | `RashiInfo` | Sun's nakshatra (changes every ~13-14 days) |
+| `choghadiya` | `ChoghadiyaInfo` | 8 day + 8 night slots, each named and rated |
+| `gowriPanchangam` | `GowriInfo` | 8 day + 8 night Gowri Nalla Neram slots |
+| `hora` | `HoraInfo` | 12 day + 12 night horas, each with ruling planet |
+| `moonrise` | `Date \| null` | Moonrise; `null` if none that day |
+| `moonset` | `Date \| null` | Moonset; `null` if none that day |
 | `panchaka` | `boolean` | `true` when Moon is in last 5 nakshatras |
-| `specialYogas` | `SpecialYogaInfo[]` | Auspicious yogas active today (may be empty) |
+| `specialYogas` | `SpecialYogaInfo[]` | Auspicious yogas active today |
 | `durMuhurta` | `[TimePeriod, TimePeriod]` | Two inauspicious ~48-min windows |
-| `festivals` | `FestivalInfo[]` | Festivals / observances today (may be empty) |
+| `festivals` | `FestivalInfo[]` | Festivals / observances today |
 | `ayanamsa` | `number` | Ayanamsa in degrees at sunrise |
-| `siderealSunAtSunrise` | `number` | Sun sidereal longitude at sunrise (°) |
-| `siderealMoonAtSunrise` | `number` | Moon sidereal longitude at sunrise (°) |
+| `siderealSunAtSunrise` | `number` | Sun sidereal longitude at sunrise (degrees) |
+| `siderealMoonAtSunrise` | `number` | Moon sidereal longitude at sunrise (degrees) |
 
 ---
 
@@ -201,7 +249,7 @@ const result = getInstantPanchang(
 
 console.log(result.tithi.name);              // "कृष्ण चतुर्दशी"
 console.log(result.nakshatra.name);          // "मृगशिरा"
-console.log(result.chandramasa.name);        // "पौष"
+console.log(result.chandramasa.name);        // "माघ"
 console.log(result.chandraRashi.name);       // "मिथुन"
 console.log(result.samvat.vikramSamvat);     // 2081
 console.log(result.panchaka);               // false
@@ -223,11 +271,11 @@ console.log(result.panchaka);               // false
 | `chandraRashi` | `RashiInfo` | Moon's zodiac sign |
 | `suryaNakshatra` | `RashiInfo` | Sun's nakshatra |
 | `panchaka` | `boolean` | `true` when Moon is in last 5 nakshatras |
-| `specialYogas` | `SpecialYogaInfo[]` | Auspicious yogas at this moment (may be empty) |
-| `festivals` | `FestivalInfo[]` | Festivals / observances at this moment (may be empty) |
+| `specialYogas` | `SpecialYogaInfo[]` | Auspicious yogas at this moment |
+| `festivals` | `FestivalInfo[]` | Festivals / observances at this moment |
 | `ayanamsa` | `number` | Ayanamsa in degrees |
-| `siderealSun` | `number` | Sun sidereal longitude (°) |
-| `siderealMoon` | `number` | Moon sidereal longitude (°) |
+| `siderealSun` | `number` | Sun sidereal longitude (degrees) |
+| `siderealMoon` | `number` | Moon sidereal longitude (degrees) |
 
 ---
 
@@ -239,9 +287,10 @@ console.log(result.panchaka);               // false
 |--------|------|---------|-------------|
 | `timezone` | `number \| string` | **required** | UTC offset in minutes (330 for IST). Use a number on Hermes — IANA strings require `Intl`. |
 | `ayanamsa` | `'lahiri' \| 'raman' \| 'krishnamurti'` | `'lahiri'` | Ayanamsa system |
-| `language` | `'en' \| 'sa' \| 'hi'` | `'en'` | Language for all element names (tithi, paksha, masa, etc.). `'sa'` = classical Sanskrit Devanagari, `'hi'` = modern Hindi Devanagari. |
-| `computeEndTimes` | `boolean` | `true` | Set `false` for ~5× faster, names-only output |
+| `language` | `'en' \| 'sa' \| 'hi'` | `'en'` | Language for all element names. `'sa'` = classical Sanskrit Devanagari, `'hi'` = modern Hindi Devanagari. |
+| `computeEndTimes` | `boolean` | `true` | Set `false` for ~5x faster, names-only output |
 | `precision` | `'standard' \| 'high'` | `'standard'` | Binary-search iterations (15 vs 25). High precision is rarely needed. |
+| `masaSystem` | `'purnimanta' \| 'amanta'` | `'purnimanta'` | Lunar month naming system. Purnimanta (North Indian) or Amanta (South Indian). |
 
 **`InstantPanchangOptions`** (optional for `getInstantPanchang`): same as above but without `timezone`.
 
@@ -249,7 +298,7 @@ console.log(result.panchaka);               // false
 
 ### Low-level Utilities
 
-These are exported for advanced use cases (building your own tools, visualisations, or debugging).
+Exported for advanced use cases — building custom tools, visualizations, or Jyotish applications.
 
 ```typescript
 import {
@@ -261,7 +310,9 @@ import {
   computeAbhijitMuhurta, computeBrahmaMuhurta,
   computeGowriPanchangam,
   // Jyotish
-  computePlanetaryPositions, computeVimshottariDasha,
+  computePlanetaryPositions,
+  computeVimshottariDasha, computeVimshottariDashaFromBirth,
+  computeChandraBalam,
   GRAHA_ABBR,
 } from 'panchang-ts';
 
@@ -280,40 +331,48 @@ const sunLon  = getSiderealSunLongitude(new Date(), 'lahiri');
 // Ayanamsa
 const ayan = getAyanamsa(new Date(), 'lahiri');  // e.g. 24.10
 
-// Inauspicious periods (varaIndex: 0=Sun … 6=Sat)
-const rahu  = computeRahuKalam(sunrise, sunset, varaIndex);   // { start, end }
+// Inauspicious periods (varaIndex: 0=Sun ... 6=Sat)
+const rahu   = computeRahuKalam(sunrise, sunset, varaIndex);   // { start, end }
 const gulika = computeGulikaKalam(sunrise, sunset, varaIndex);
-const yama  = computeYamaganda(sunrise, sunset, varaIndex);
+const yama   = computeYamaganda(sunrise, sunset, varaIndex);
 
 // Muhurta
-const abhijit    = computeAbhijitMuhurta(sunrise, sunset);    // { start, end }
-const brahma     = computeBrahmaMuhurta(sunrise, sunset);     // { start, end }
-
+const abhijit = computeAbhijitMuhurta(sunrise, sunset);    // { start, end }
+const brahma  = computeBrahmaMuhurta(sunrise, sunset);     // { start, end }
+```
 
-// Gowri Panchangam (varaIndex: 0=Sun … 6=Sat)
-const gowri = computeGowriPanchangam(sunrise, sunset, nextSunrise, varaIndex,
-  (i) => ['Udyog','Amrit','Roga','Laabh','Shubh','Kaal','Dhan','Chal'][i]!,
-  (q) => ({ auspicious: 'Auspicious', inauspicious: 'Inauspicious', neutral: 'Neutral' })[q],
-);
-// gowri.day  → 8 GowriSlot (sunrise → sunset)
-// gowri.night → 8 GowriSlot (sunset → next sunrise)
+**Jyotish (Vedic Astrology):**
 
-// Planetary positions (all 9 grahas, sidereal)
+```typescript
+// All 9 graha positions (sidereal — Rahu/Ketu use mean node)
 const grahas = computePlanetaryPositions(birthDate, 'lahiri');
-console.log(grahas.jupiter.rashi.name);  // e.g. "Dhanu"
-console.log(grahas.saturn.isRetrograde); // true/false
-console.log(GRAHA_ABBR['Jupiter']);      // "Ju"
+console.log(grahas.jupiter.rashi.name);   // "Dhanu"
+console.log(grahas.saturn.isRetrograde);  // true/false
+console.log(GRAHA_ABBR['Jupiter']);       // "Ju"
+
+// Vimshottari Dasha — convenience form: birth date only (Moon longitude derived)
+const dasha = computeVimshottariDashaFromBirth(birthDate, 'lahiri');
+console.log(dasha.currentMahaDashaLord);                   // "Rahu"
+console.log(dasha.mahaDashas[0]!.antarDashas[0]!.lord);    // "Rahu"
 
-// Vimshottari Dasha — pass birth date and Moon's sidereal longitude
+// Or pass an explicit Moon sidereal longitude (useful when you already have one)
 const moonLon = getSiderealMoonLongitude(birthDate, 'lahiri');
-const dasha = computeVimshottariDasha(birthDate, moonLon);
-console.log(dasha.currentMahaDashaLord);   // e.g. "Rahu"
-console.log(dasha.mahaDashas[0]!.antarDashas[0]!.lord); // e.g. "Rahu"
+const dasha2  = computeVimshottariDasha(birthDate, moonLon);
+
+// Chandra Balam — transit Moon's favorability vs. janma rashi
+// janmaRashi and transitMoonRashi are 0-indexed (0 = Mesha ... 11 = Meena)
+const cb = computeChandraBalam(3 /* Karka */, 6 /* Tula */);
+console.log(cb.house);        // 4
+console.log(cb.quality);      // "weak"
+console.log(cb.englishName);  // "Ashubha"
 ```
 
 ---
 
-### Types
+## Types
+
+<details>
+<summary><strong>Core Types</strong> — GeoLocation, TimePeriod</summary>
 
 ```typescript
 interface GeoLocation {
@@ -326,45 +385,70 @@ interface TimePeriod {
   start: Date;
   end: Date;
 }
+```
+</details>
 
-// ── Pancha Anga ──────────────────────────────────────────────────────────────
+<details>
+<summary><strong>Pancha Anga</strong> — TithiInfo, NakshatraInfo, YogaInfo, KaranaInfo, VaraInfo</summary>
 
+```typescript
 interface TithiInfo {
-  index: number;               // 0–29
+  index: number;               // 0-29
   name: string;                // e.g. "Shukla Pratipada"
-  paksha: string;              // "Shukla"/"Krishna" (en), "शुक्ल"/"कृष्ण" (sa/hi) — localized
-  number: number;              // 1–15 within the paksha
+  paksha: string;              // "Shukla"/"Krishna" (en), "शुक्ल"/"कृष्ण" (sa/hi)
+  number: number;              // 1-15 within the paksha
   completionPercentage: number;
   endTime: Date | null;
 }
 
 interface NakshatraInfo {
-  index: number;               // 0–26
+  index: number;               // 0-26
   name: string;
-  pada: number;                // 1–4
+  pada: number;                // 1-4
   degreesInNakshatra: number;
   completionPercentage: number;
   endTime: Date | null;
 }
 
 interface DailyTithiInfo extends TithiInfo {
-  startTime: Date | null;      // null when isActiveAtSunrise is true (element was already active at sunrise)
-  isActiveAtSunrise: boolean;  // true → this element was present at sunrise; false → it started mid-day (startTime is set)
+  startTime: Date | null;      // null when isActiveAtSunrise is true
+  isActiveAtSunrise: boolean;  // true = present at sunrise; false = started mid-day
 }
 
 // DailyNakshatraInfo, DailyYogaInfo, DailyKaranaInfo follow the same pattern
 
-// Note: endTime and startTime are null on ALL daily elements when computeEndTimes: false.
-// completionPercentage: 0 = just started, 100 = about to end (computed at sunrise moment).
+interface VaraInfo {
+  index: number;       // 0 = Sunday ... 6 = Saturday
+  name: string;        // e.g. "Ravivara" (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';
+}
 
-// ── Lunar calendar ───────────────────────────────────────────────────────────
+// Note: endTime and startTime are null when computeEndTimes: false.
+```
+</details>
 
+<details>
+<summary><strong>Lunar Calendar</strong> — ChandraMasaInfo, SamvatInfo, MasaInfo</summary>
+
+```typescript
 interface ChandraMasaInfo {
-  index: number;          // 0 = Chaitra … 11 = Phalguna (Amanta / South-Indian)
-  name: string;           // e.g. "Pausha" (Amanta name)
-  isAdhika: boolean;      // true = leap/intercalary month
-  purnimantaIndex: number; // Month index in Purnimanta (North-Indian) system
-  purnimantaName: string;  // Month name in Purnimanta system
+  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;      // month index in Amanta system
+  amantaName: string;       // month name in Amanta system
+  purnimantaIndex: number;  // month index in Purnimanta system
+  purnimantaName: string;   // month name in Purnimanta system
 }
 
 interface SamvatInfo {
@@ -372,101 +456,83 @@ interface SamvatInfo {
   shakaSamvat: number;   // e.g. 1946
 }
 
-// ── Zodiac & asterism ────────────────────────────────────────────────────────
-
-interface RashiInfo {
-  index: number;  // 0 = Mesha … 11 = Meena (for rashi); 0–26 for nakshatra
-  name: string;
-}
-
-// chandraRashi and suryaNakshatra both use RashiInfo
-
-interface VaraInfo {
-  index: number;       // 0 = Sunday … 6 = Saturday
-  name: string;        // e.g. "Ravivara" (localized full name)
-  shortName: string;   // e.g. "Ravi" (localized short form, Sanskrit by default)
-  englishName: string; // e.g. "Sunday" (always English, locale-independent)
-}
-
 interface MasaInfo {
-  index: number;  // 0 = Mesha … 11 = Meena (solar month)
-  name: string;   // e.g. "Dhanu"
+  index: number;  // 0 = Mesha ... 11 = Meena (solar month)
+  name: string;
 }
 
-interface KaranaInfo {
-  index: number;
+interface RashiInfo {
+  index: number;  // 0 = Mesha ... 11 = Meena
   name: string;
-  completionPercentage: number;
-  endTime: Date | null;
-  type: 'fixed' | 'movable';
 }
+```
+</details>
 
-// ── Choghadiya ───────────────────────────────────────────────────────────────
+<details>
+<summary><strong>Time Slots</strong> — Choghadiya, Gowri Panchangam, Hora</summary>
 
+```typescript
 type ChoghadiyaQuality = 'auspicious' | 'inauspicious' | 'neutral';
 
 interface ChoghadiyaSlot extends TimePeriod {
   index: number;
-  name: string;              // e.g. "Amrit", "Kaal", "Shubh" (localized)
-  quality: ChoghadiyaQuality; // programmatic key: 'auspicious' | 'inauspicious' | 'neutral'
-  qualityName: string;       // localized display name (e.g. "Auspicious", "शुभ", "शुभम्")
+  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)
+  day: ChoghadiyaSlot[];    // 8 slots (sunrise -> sunset)
+  night: ChoghadiyaSlot[];  // 8 slots (sunset -> next sunrise)
 }
 
-// ── Gowri Panchangam ─────────────────────────────────────────────────────────
-
 interface GowriSlot extends TimePeriod {
-  index: number;              // 0–7 within the 8-name cycle
-  name: string;               // e.g. "Amrit", "Kaal", "Shubh" (localized)
-  quality: ChoghadiyaQuality; // programmatic key: 'auspicious' | 'inauspicious' | 'neutral'
-  qualityName: string;        // localized display name (e.g. "Auspicious", "शुभ", "शुभम्")
+  index: number;              // 0-7 within the 8-name cycle
+  name: string;               // e.g. "Amrit", "Kaal" (localized)
+  quality: ChoghadiyaQuality;
+  qualityName: string;
 }
 
 interface GowriInfo {
-  day: GowriSlot[];    // 8 slots (sunrise → sunset)
-  night: GowriSlot[];  // 8 slots (sunset → next sunrise)
+  day: GowriSlot[];    // 8 slots (sunrise -> sunset)
+  night: GowriSlot[];  // 8 slots (sunset -> next sunrise)
 }
 
-// ── Hora ─────────────────────────────────────────────────────────────────────
-
 interface HoraSlot extends TimePeriod {
-  planet: string;       // Chaldean order: "Sun"(0), "Venus"(1), "Mercury"(2), "Moon"(3), "Saturn"(4), "Jupiter"(5), "Mars"(6)
-  planetIndex: number;  // 0–6 — index into the Chaldean sequence above
+  planet: string;       // e.g. "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)
+  day: HoraSlot[];    // 12 slots (sunrise -> sunset)
+  night: HoraSlot[];  // 12 slots (sunset -> next sunrise)
 }
+```
+</details>
 
-// ── Special Yogas ────────────────────────────────────────────────────────────
+<details>
+<summary><strong>Special Yogas & Festivals</strong></summary>
 
+```typescript
 interface SpecialYogaInfo {
   name: string;    // e.g. "Guru Pushya Yoga"
   type: 'amrit_siddhi' | 'sarvartha_siddhi' | 'ravi_pushya' | 'guru_pushya';
 }
 
-// ── Festivals ────────────────────────────────────────────────────────────────
-
 interface FestivalInfo {
   name: string;         // e.g. "Diwali", "Ekadashi"
   type: 'major' | 'minor' | 'ekadashi' | 'pradosha' | 'sankranti';
-  description?: string; // For sankranti: localized rashi name (e.g. "Makara", "मकर")
+  description?: string; // For sankranti: localized rashi name
 }
+```
+</details>
 
-// Detection rules:
-//   Ekadashi:  both Shukla (tithi 10) and Krishna (tithi 25) pakshas
-//   Pradosha:  Krishna Trayodashi only (tithi 27)
-//   Sankranti: Sun within 1° past a rashi boundary (degInRashi < 1.0)
-//   Fixed festivals (e.g. Diwali): matched by chandramasa index + tithi index; skipped during Adhika months
-
-// ── Jyotish (Vedic astrology) ────────────────────────────────────────────────
+<details>
+<summary><strong>Jyotish (Vedic Astrology)</strong> — Graha positions, Vimshottari Dasha</summary>
 
-type GrahaName = 'Sun' | 'Moon' | 'Mars' | 'Mercury' | 'Jupiter' | 'Venus' | 'Saturn' | 'Rahu' | 'Ketu';
+```typescript
+type GrahaName = 'Sun' | 'Moon' | 'Mars' | 'Mercury' | 'Jupiter'
+               | 'Venus' | 'Saturn' | 'Rahu' | 'Ketu';
 
 interface GrahaPosition {
   planet: GrahaName;
@@ -483,7 +549,8 @@ interface PlanetaryPositions {
   saturn: GrahaPosition; rahu: GrahaPosition; ketu: GrahaPosition;
 }
 
-type DashaLord = 'Ketu' | 'Venus' | 'Sun' | 'Moon' | 'Mars' | 'Rahu' | 'Jupiter' | 'Saturn' | 'Mercury';
+type DashaLord = 'Ketu' | 'Venus' | 'Sun' | 'Moon' | 'Mars'
+              | 'Rahu' | 'Jupiter' | 'Saturn' | 'Mercury';
 
 interface AntarDasha {
   lord: DashaLord;
@@ -495,21 +562,28 @@ interface MahaDasha {
   lord: DashaLord;
   startDate: Date;
   endDate: Date;
-  years: number;           // full duration in years (proportional for the first/partial dasha)
+  years: number;
   antarDashas: AntarDasha[];
 }
 
 interface VimshottariDashaResult {
-  currentMahaDashaLord: DashaLord;  // active Mahadasha as of today
-  currentIndex: number;              // index into mahaDashas
-  mahaDashas: MahaDasha[];           // 9-entry sequence starting from birth
+  currentMahaDashaLord: DashaLord;
+  currentIndex: number;
+  mahaDashas: MahaDasha[];  // 9-entry sequence starting from birth
 }
 
+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
+}
 ```
+</details>
 
 ---
 
-## React Native / Hermes Usage
+## 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
@@ -537,57 +611,53 @@ InteractionManager.runAfterInteractions(() => {
 
 ---
 
-## 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 |
-
-Measured with Vitest benchmarks on Node 22 and on a physical budget Android device
-via the dharmSetu React Native app.
-
----
-
 ## Accuracy
 
-Validated against [DrikPanchang.com](https://www.drikpanchang.com) for 19+ date/city combinations (Pune, Delhi, Chennai, Mumbai, Bangalore, New York).
-
-| Element | Accuracy |
-|---------|----------|
-| Sunrise / Sunset | ±2 minutes |
-| Moonrise / Moonset | ±2 minutes |
-| Tithi, Nakshatra, Yoga, Karana names | Exact match |
-| Element end-times | ±5 minutes |
-| Ayanamsa | ±0.005° vs Swiss Ephemeris |
-| Choghadiya / Hora / Gowri slots | Derived from sunrise/sunset — inherits ±2 min |
-
-### Validation test suite
-
-The test suite includes:
-- **242-day structural regression** (Pune, Sep 2025 – Apr 2026): verifies no crash, correct Vara, time-ordering invariants, element counts, and all fields (including Gowri Panchangam) for every day in the window
-- **19 precise-value tests** across 5 Indian cities + New York: exact Tithi name, Nakshatra name, sunrise/sunset HH:MM (±2 min tolerance), Chandra Masa name
-- **10 long-range regression tests** (2030–2050): structural correctness and ayanamsa bounds for future dates
-
-To generate fixture stubs for new date ranges (e.g. to populate against DrikPanchang):
-
-```bash
-npx tsx scripts/generate-fixtures.ts --start 2027-01-01 --end 2027-03-31 --city Delhi
-```
+4,864 tests passing, including Drik-verified fixtures against
+[DrikPanchang.com](https://www.drikpanchang.com) spanning 2025–2026 across
+Delhi, Chennai, and New York.
+
+| Element | Accuracy | Validation |
+|---------|----------|------------|
+| Sunrise / Sunset | **≤29 s observed vs Drik minute-midpoint** (±45 s tolerance) | 16 assertions |
+| Moonrise / Moonset | ±2 min vs Drik | Strict fixtures |
+| Tithi, Nakshatra, Yoga, Karana names | Exact match vs Drik | 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 Drik sidereal** | Drik fixtures |
+| Planetary positions (Rahu/Ketu, mean node) | ≤0.5° typical; ±2° tolerance to absorb mean-vs-true drift | Drik fixtures |
+| Rashi / Nakshatra / Retrograde flag | Exact match vs Drik | Drik fixtures |
+| Festival dates | 12 Drik-verified festivals (2025–2026) — see caveats below | Drik fixtures |
+| Choghadiya / Hora / Gowri slots | Derived from sunrise/sunset — inherits ±2 min | — |
+
+### Festival Detection — Documented Tradeoff
+
+Library uses **tithi-at-sunrise** to resolve a festival to a calendar day.
+DrikPanchang applies several other traditional rules depending on the
+festival; where those rules pick a different day, our output can drift
+±1 day vs Drik. This is a rule-choice tradeoff, not a computation bug —
+it is documented and deliberately surfaced rather than hidden.
+
+| Resolution rule Drik uses | Festivals affected |
+|---------------------------|--------------------|
+| 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 (Pratipad is Kshaya) |
+
+If exact Drik parity matters for your use case, cross-check the above
+festival set against the Drik site 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 Drik's canonical date across 2025 and 2026 fixtures.
 
 ---
 
-## Compatibility
+## Performance
 
-| Environment | Support |
-|-------------|---------|
-| Node.js 18+ | ✅ |
-| Node.js 20+ | ✅ |
-| Node.js 22+ | ✅ |
-| React Native (Hermes) | ✅ (pass `timezone` as number) |
-| Expo (managed + bare) | ✅ |
-| Browser (modern) | ✅ (ESM build) |
-| Browser (legacy / IE) | ✗ |
+| Mode | Node.js | Hermes (budget Android) |
+|------|---------|------------------------|
+| Names-only (`computeEndTimes: false`) | ~0.1 ms | <100 ms |
+| Full with end-times | ~0.5 ms | <500 ms |
 
 ---
 
@@ -606,21 +676,35 @@ try {
 }
 ```
 
-`PanchangErrorCode` values: `INVALID_DATE`, `INVALID_LATITUDE`, `INVALID_LONGITUDE`,
+Error codes: `INVALID_DATE`, `INVALID_LATITUDE`, `INVALID_LONGITUDE`,
 `INVALID_ELEVATION`, `INVALID_TIMEZONE`, `INVALID_AYANAMSA`, `TIMEZONE_RESOLUTION_FAILED`,
 `NO_SUNRISE`, `NO_SUNSET`, `SEARCH_DIVERGED`.
 
-Note: `getMoonrise` / `getMoonset` never throw — they return `null` when no rise/set
-occurs within the search window (this is normal for the Moon).
+`getMoonrise` / `getMoonset` return `null` instead of throwing when no rise/set
+occurs (normal for the Moon).
 
 ---
 
-## Acknowledgements
+## Compatibility
 
-- **[astronomy-engine](https://github.com/cosinekitty/astronomy)** by Don Cross — the sole runtime dependency. Provides the astronomical algorithms used for sunrise/sunset, moonrise/moonset, and planetary longitude calculations. MIT licensed.
+| Environment | Support |
+|-------------|---------|
+| Node.js 18+ | Supported |
+| React Native (Hermes) | Supported (pass `timezone` as number) |
+| Expo (managed + bare) | Supported |
+| Browser (modern) | Supported (ESM build) |
+| Browser (legacy / IE) | Not supported |
 
 ---
 
+## Used By
+
+- [dharmagya.app](https://dharmagya.app) — Daily Panchang and Hindu calendar
+
+## Acknowledgements
+
+[astronomy-engine](https://github.com/cosinekitty/astronomy) by Don Cross — the sole runtime dependency. MIT licensed.
+
 ## License
 
 MIT