panchang-ts 2.0.1 → 2.1.0

package/README.md

@@ -139,6 +139,37 @@ console.log(amanta.chandramasa.name);         // Amanta month name
 console.log(amanta.chandramasa.system);       // "amanta"
 ```
 
+### Regional Festival Filtering
+
+The `region` option scopes regional festival variants to one Indian state.
+Pan-Indian festivals (Diwali, Holi, Raksha Bandhan, the canonical
+`sankranti` event, …) 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 — no extra wiring required, just the region option:
+const lohri = getDailyPanchang(jan13, amritsar, { timezone: 330, region: 'punjab' });
+lohri.festivals.some(f => f.name === 'Lohri');  // true
+
+// Pre-v2.1 region values still work but log a one-shot deprecation warning:
+getDailyPanchang(date, loc, { timezone: 330, region: 'tamil' });
+// console.warn: [panchang-ts] FestivalRegion 'tamil' is deprecated;
+//               use 'tamil-nadu'. Legacy value will be removed in v3.
+```
+
+See [`FestivalRegion`](#types) for the full state-slug list (21 states + `'nepal'`).
+
 ---
 
 ## Features
@@ -158,12 +189,13 @@ Rahu Kalam, Gulika Kalam, Yamaganda, Panchaka detection, Bhadra Kala (Vishti kar
 ### Special Yogas & Festivals
 Amrit Siddhi, Sarvartha Siddhi, Ravi Pushya, Guru Pushya yoga detection.
 
-**60+ festivals** spanning pan-Indian, regional, and classical observances:
+**80+ festivals** spanning pan-Indian, regional, and classical observances:
 
 - **Ekadashi** — 26 named variants (Putrada, Shat Tila, Nirjala, Devshayani, etc.) with **Smarta / Vaishnava split** via Dashami-viddha rule; Smarta fast emits a `deferralDate` for Dwadashi.
 - **Pradosha** — 7 weekday-qualified variants (Som Pradosh, Bhauma Pradosh, Shani Pradosh, etc.) firing on both Shukla & Krishna paksha.
-- **Sankranti** — transit-based solar-month boundary detection plus regional variants (**Pongal**, **Vishu**, **Baisakhi**, **Magh Bihu**, **Ayyappa Makara Jyothi**) scoped by the `region` option.
+- **Sankranti** — transit-based solar-month boundary detection plus regional variants (**Pongal**, **Vishu**, **Baisakhi**, **Pohela Boishakh**, **Bohag Bihu**, **Magh Bihu**, **Kati Bihu**, **Uttarayan**, **Ayyappa Makara Jyothi**, **Raja Sankranti**, **Harela**, **Sair**, **Singh Sankranti**) scoped by the `region` option. **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, suppressed when Bhadra straddles Purnima), Karva Chauth (chandrodaya), Janmashtami, Dussehra, Navaratri, Ram Navami, Hanuman Jayanti, **Akshaya Tritiya & Parashurama Jayanti** (madhyahna-vyapini, co-emitted on Vaishakha Shukla Tritiya), Makar Sankranti.
+- **Regional festivals (v2.1)** — **Gudi Padwa** (Maharashtra/Goa), **Gangaur** (Rajasthan), **Karaga** (Karnataka), **Bonalu** (Telangana, recurring Sundays in Ashadha), **Varamahalakshmi** (last Friday of Shravana Shukla before Purnima, Karnataka/AP/Telangana/Tamil Nadu), **Bathukamma** (Telangana — Engili Pula + Saddula markers), **Hariyali / Kajari / Hartalika Teej**, **Govardhan Puja**, **Bhai Dooj**, **Phagli** (Himachal), **Jagannath Rath Yatra** (pan-Indian, Ashadha Shukla Dwitiya), **Raja Parba** 3-day arc (Odisha — Pahili / Sankranti / Basi) — all filtered by per-state allow-lists on the rule.
 - **Regional & seasonal** — Chhath (4-day sequence), Vat Savitri, Upakarma (3 shakha variants via nakshatra+chandraMasa), Onam (nakshatra+solarMasa).
 - **Monthly observances** — Masik Shivaratri, Vinayaka Chaturthi (suppressed in Maha-month), **Masik Karthigai** (any day Krittika nakshatra prevails — sampled at sunrise / midday / sunset / nishita), Pushya days, Shravan Somvar and other month+weekday patterns.
 - Adhika (leap) months auto-skipped for tithi-based rules; Purnimanta naming respected.
@@ -332,7 +364,7 @@ Both functions share the same core astronomy, but `getDailyPanchang` operates on
 | `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). |
-| `region` | `FestivalRegion` | `'all'` | Scopes regional festival variants (Pongal, Vishu, Baisakhi, Bihu, Ayyappa, etc.). See [`FestivalRegion`](#types) for supported values. The canonical pan-Indian `sankranti` event is always emitted regardless. |
+| `region` | `FestivalRegion` | `'all'` | Scopes regional festival variants (Pongal, Vishu, Gudi Padwa, Lohri, Govardhan Puja, Bonalu, …) to a specific Indian state. See [`FestivalRegion`](#types) for the full list. Pre-v2.1 values (`'tamil'`, `'bengal'`, `'north-india'`) are still accepted but emit a deprecation warning; removal in v3. Pan-Indian festivals and the canonical `sankranti` event emit regardless of this setting. |
 | `janmaRashi` | `number` | _(omitted)_ | Native's birth Moon rashi index (0 = Mesha … 11 = Meena). When provided, the result includes `chandraBalam`. |
 
 **`InstantPanchangOptions`** (optional for `getInstantPanchang`): same as above but without `timezone` (instant mode works in UTC).
@@ -582,17 +614,56 @@ interface FestivalInfo {
   deferralDate?: Date;
 }
 
+// State-slug scheme. A caller sets `region` to limit regional variants to
+// their state; pan-Indian festivals (Holi, Diwali, Sankranti itself, …)
+// emit regardless.
 type FestivalRegion =
-  | 'all'           // default — emits every regional variant
-  | 'north-india'
-  | 'tamil'
-  | 'kerala'
-  | 'bengal'
-  | 'punjab'
-  | 'gujarat'
-  | 'assam'
-  | 'maharashtra';
+  | 'all'             // default — emits every regional variant
+  // South
+  | '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 as input and mapped at call time; a
+// one-shot console warning fires per distinct legacy value. Removal in v3.
+//   'tamil'       → 'tamil-nadu'
+//   'bengal'      → 'west-bengal'
+//   'north-india' → 'all'       (Makar Sankranti is pan-Indian; use state
+//                                slugs for Lohri / Govardhan / Bhai Dooj)
+type LegacyFestivalRegion = 'tamil' | 'bengal' | 'north-india';
 ```
+
+**Region-scoped festivals** (non-exhaustive — see `src/core/festivals.ts`):
+
+| Region | Festival names (keys) |
+|---|---|
+| `tamil-nadu` | pongal, puthandu, varamahalakshmi |
+| `kerala` | vishu, ayyappa_makara_jyothi, onam *(solar-nakshatra)* |
+| `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>

package/dist/index.cjs

@@ -3756,28 +3756,47 @@ function computeDurMuhurta(sunrise, sunset, varaIndex) {
 var SANKRANTI_REGIONAL = {
   // Mesha (0) — solar new year across regions
   0: [
-    { key: "baisakhi", region: "punjab", type: "major" },
-    { key: "vishu", region: "kerala", type: "major" },
-    { key: "pohela_boishakh", region: "bengal", type: "major" },
-    { key: "puthandu", region: "tamil", type: "major" }
+    { key: "baisakhi", regions: ["punjab", "haryana"], type: "major" },
+    { key: "vishu", regions: ["kerala"], type: "major" },
+    { key: "pohela_boishakh", regions: ["west-bengal"], type: "major" },
+    { key: "puthandu", regions: ["tamil-nadu"], type: "major" },
+    { key: "bohag_bihu", regions: ["assam"], type: "major" }
   ],
   // Karka (3) — Dakshinayana (Sun's southward course begins)
   3: [
-    { key: "dakshinayana", region: "all", type: "minor" }
+    { key: "dakshinayana", regions: ["all"], type: "minor" },
+    // Raja Parba (Odisha) — 4-day monsoon festival; we emit a single-day
+    // marker on Karka Sankranti, the most widely cited anchor day.
+    { key: "raja_sankranti", regions: ["odisha"], type: "major" },
+    // Harela (Kumaon / Uttarakhand) — observed on Shravana solar-month start.
+    { key: "harela", regions: ["uttarakhand"], type: "major" }
   ],
-  // Simha (4)
+  // Simha (4) — Singh Sankranti is primarily observed in Odisha, Bihar,
+  // and Nepal (as Singhasankranti); not a pan-Indian observance despite
+  // the pre-v2.1 tagging.
   4: [
-    { key: "singh_sankranti", region: "all", type: "minor" }
+    { key: "singh_sankranti", regions: ["odisha", "bihar", "jharkhand", "nepal"], type: "minor" }
+  ],
+  // Kanya (5) — Sair (Himachal): first day of the Ashwin solar month.
+  5: [
+    { key: "sair", regions: ["himachal-pradesh"], type: "minor" }
+  ],
+  // Tula (6) — Kati Bihu (Assam): Kartika solar-month start.
+  6: [
+    { key: "kati_bihu", regions: ["assam"], type: "minor" }
   ],
   // Makara (9) — Uttarayana / harvest festivals
   9: [
-    { key: "makar_sankranti", region: "north-india", type: "major" },
-    { key: "pongal", region: "tamil", type: "major" },
-    { key: "uttarayan", region: "gujarat", type: "major" },
-    { key: "bihu", region: "assam", type: "major" },
-    { key: "ayyappa_makara_jyothi", region: "kerala", type: "major" }
+    // Makar Sankranti is pan-Indian (re-scoped from the pre-v2.1 'north-india').
+    { key: "makar_sankranti", regions: ["all"], type: "major" },
+    { key: "pongal", regions: ["tamil-nadu"], type: "major" },
+    { key: "uttarayan", regions: ["gujarat"], type: "major" },
+    { key: "magh_bihu", regions: ["assam"], type: "major" },
+    { key: "ayyappa_makara_jyothi", regions: ["kerala"], type: "major" }
   ]
 };
+var LOHRI_REGIONS = ["punjab", "haryana", "himachal-pradesh"];
+var RAJA_REGIONS = ["odisha"];
 var FESTIVAL_REGISTRY = [
   // Chaitra (0)
   { key: "ugadi", masa: 0, tithi: 0, type: "major" },
@@ -3851,7 +3870,144 @@ var FESTIVAL_REGISTRY = [
   // Rig Upakarma — Shravana nakshatra (21) in Shravana chandra masa (4).
   { key: "rig_upakarma", masa: 4, nakshatra: 21, type: "major" },
   // Sama Upakarma — Hasta nakshatra (12) in Bhadrapada chandra masa (5).
-  { key: "sama_upakarma", masa: 5, nakshatra: 12, type: "major" }
+  { key: "sama_upakarma", masa: 5, nakshatra: 12, type: "major" },
+  // ── Regional festivals (v2.1 expansion) ─────────────────────
+  // Chaitra (0) — Marathi/Konkani New Year; same tithi as Ugadi but
+  // emitted as a Maharashtra-specific variant name alongside Ugadi.
+  {
+    key: "gudi_padwa",
+    masa: 0,
+    tithi: 0,
+    type: "major",
+    regions: ["maharashtra", "goa"]
+  },
+  // Chaitra (0) Shukla Tritiya — Gangaur (18-day festival concludes here).
+  {
+    key: "gangaur",
+    masa: 0,
+    tithi: 2,
+    type: "major",
+    regions: ["rajasthan"]
+  },
+  // Chaitra (0) Purnima — Karaga festival of Bengaluru.
+  {
+    key: "karaga",
+    masa: 0,
+    tithi: 14,
+    type: "major",
+    regions: ["karnataka"]
+  },
+  // Ashadha (3) — Bonalu, Sundays at Mahakali temples across Telangana.
+  {
+    key: "bonalu",
+    masa: 3,
+    vara: 0,
+    type: "minor",
+    adhikaBehaviour: "observe-in-both",
+    regions: ["telangana"]
+  },
+  // Shravana (4) Shukla Tritiya — Hariyali Teej.
+  {
+    key: "hariyali_teej",
+    masa: 4,
+    tithi: 2,
+    type: "major",
+    regions: ["rajasthan", "uttar-pradesh", "bihar", "haryana", "madhya-pradesh"]
+  },
+  // Shravana (4) Krishna Tritiya — Kajari Teej (tithi 17 = Krishna Tritiya).
+  {
+    key: "kajari_teej",
+    masa: 4,
+    tithi: 17,
+    type: "major",
+    regions: ["rajasthan", "uttar-pradesh", "madhya-pradesh"]
+  },
+  // Bhadrapada (5) Shukla Tritiya — Hartalika Teej.
+  {
+    key: "hartalika_teej",
+    masa: 5,
+    tithi: 2,
+    type: "major",
+    regions: ["rajasthan", "uttar-pradesh", "bihar", "maharashtra", "madhya-pradesh"]
+  },
+  // Amanta Kartika (7) Shukla Pratipada — day after Diwali.
+  // In Purnimanta convention this is also "Kartika Shukla Pratipada" (naming
+  // system aligns), so a namingSystem tag isn't required here.
+  {
+    key: "govardhan_puja",
+    masa: 7,
+    tithi: 0,
+    type: "major",
+    regions: [
+      "uttar-pradesh",
+      "bihar",
+      "haryana",
+      "rajasthan",
+      "gujarat",
+      "madhya-pradesh",
+      "punjab",
+      "jharkhand"
+    ]
+  },
+  // Amanta Kartika (7) Shukla Dwitiya — Bhai Dooj.
+  {
+    key: "bhai_dooj",
+    masa: 7,
+    tithi: 1,
+    type: "major",
+    regions: [
+      "uttar-pradesh",
+      "bihar",
+      "haryana",
+      "maharashtra",
+      "gujarat",
+      "rajasthan",
+      "madhya-pradesh",
+      "west-bengal",
+      "jharkhand",
+      "nepal"
+    ]
+  },
+  // Phalguna (11) Purnima — Phagli (varies by valley; Purnima anchor).
+  {
+    key: "phagli",
+    masa: 11,
+    tithi: 14,
+    type: "minor",
+    regions: ["himachal-pradesh"]
+  },
+  // Ashadha (3) Shukla Dwitiya — Jagannath Rath Yatra (pan-Indian; cultural
+  // epicenter is Puri, Odisha but observed nationwide).
+  { key: "jagannath_rath_yatra", masa: 3, tithi: 1, type: "major" },
+  // Shravana (4) Shukla — Varamahalakshmi: last Friday in Shukla paksha
+  // before Purnima. The (masa+vara) match is gated by tithi ∈ [7,13] so
+  // only the second Friday of the paksha (the one closest to Purnima) fires.
+  {
+    key: "varamahalakshmi",
+    masa: 4,
+    vara: 5,
+    type: "major",
+    tithiRange: [7, 13],
+    regions: ["karnataka", "andhra-pradesh", "telangana", "tamil-nadu"]
+  },
+  // Bathukamma (Telangana) — 9-day floral festival from Bhadrapada
+  // Amavasya through Ashwin Shukla Navami. We emit start (Engili Pula
+  // Bathukamma, masa=5/tithi=29) and climax (Saddula Bathukamma, masa=6/
+  // tithi=8) markers; intermediate days carry no library-level emission.
+  {
+    key: "bathukamma_start",
+    masa: 5,
+    tithi: 29,
+    type: "major",
+    regions: ["telangana"]
+  },
+  {
+    key: "bathukamma_saddula",
+    masa: 6,
+    tithi: 8,
+    type: "major",
+    regions: ["telangana"]
+  }
 ];
 var EKADASHI_NAMES = [
   ["kamada", "papamochani"],
@@ -3928,7 +4084,14 @@ function computeFestivals(ctx, nameResolver, rashiNameResolver) {
       match = masaMatches && rule.nakshatra === ctx.nakshatraIndex;
     } else if (rule.vara !== void 0 && rule.masa !== void 0) {
       const masaMatches = rule.masa === ctx.chandraMasaIndex && (adhikaBehaviour !== "shift-to-nija" || !ctx.isAdhika);
-      match = masaMatches && rule.vara === ctx.varaIndex;
+      let inTithiRange = true;
+      if (rule.tithiRange !== void 0) {
+        const dateRule = rule.dateRule ?? "sunrise";
+        const tithi = tithiForRule(dateRule);
+        const [lo, hi2] = rule.tithiRange;
+        inTithiRange = tithi >= lo && tithi <= hi2;
+      }
+      match = masaMatches && rule.vara === ctx.varaIndex && inTithiRange;
     } else if (rule.masa !== void 0 && rule.tithi !== void 0) {
       const masaMatches = rule.masa === ctx.chandraMasaIndex && // `shift-to-nija`: only observe in Nija following an Adhika (but still OK if no prior Adhika,
       // since the normal year has no Adhika and the festival observes as usual).
@@ -3948,6 +4111,12 @@ function computeFestivals(ctx, nameResolver, rashiNameResolver) {
       }
     }
     if (!match) continue;
+    if (rule.regions !== void 0) {
+      const region2 = ctx.region ?? "all";
+      if (region2 !== "all" && !rule.regions.includes("all") && !rule.regions.includes(region2)) {
+        continue;
+      }
+    }
     const festival = { name: nameResolver(rule.key), type: rule.type };
     if (rule.namingSystem === "purnimanta" && ctx.purnimantaMasaName && ctx.amantaMasaName) {
       festival.description = `Purnimanta: ${ctx.purnimantaMasaName} Krishna Paksha`;
@@ -4052,6 +4221,7 @@ function computeFestivals(ctx, nameResolver, rashiNameResolver) {
       description: nameResolver(variantKey)
     });
   }
+  const region = ctx.region ?? "all";
   if (ctx.sankrantiRashi !== void 0 && ctx.sankrantiRashi !== null) {
     const rashiName = rashiNameResolver ? rashiNameResolver(ctx.sankrantiRashi) : `Rashi ${ctx.sankrantiRashi}`;
     results.push({
@@ -4059,11 +4229,10 @@ function computeFestivals(ctx, nameResolver, rashiNameResolver) {
       type: "sankranti",
       description: rashiName
     });
-    const region = ctx.region ?? "all";
     const regionalRules = SANKRANTI_REGIONAL[ctx.sankrantiRashi];
     if (regionalRules) {
       for (const r of regionalRules) {
-        if (region !== "all" && r.region !== "all" && r.region !== region) continue;
+        if (region !== "all" && !r.regions.includes("all") && !r.regions.includes(region)) continue;
         results.push({
           name: nameResolver(r.key),
           type: "sankranti",
@@ -4072,9 +4241,47 @@ function computeFestivals(ctx, nameResolver, rashiNameResolver) {
       }
     }
   }
+  if (ctx.nextDaySankrantiRashi === 9) {
+    if (region === "all" || LOHRI_REGIONS.includes(region)) {
+      results.push({ name: nameResolver("lohri"), type: "major" });
+    }
+  }
+  if (ctx.nextDaySankrantiRashi === 3) {
+    if (region === "all" || RAJA_REGIONS.includes(region)) {
+      results.push({ name: nameResolver("raja_pahili"), type: "major" });
+    }
+  }
+  if (ctx.prevDaySankrantiRashi === 3) {
+    if (region === "all" || RAJA_REGIONS.includes(region)) {
+      results.push({ name: nameResolver("raja_basi"), type: "major" });
+    }
+  }
   return results;
 }
 
+// src/core/regionAlias.ts
+var LEGACY_REGION_ALIASES = {
+  "tamil": "tamil-nadu",
+  "bengal": "west-bengal",
+  "north-india": "all"
+};
+var warned = /* @__PURE__ */ new Set();
+function resolveRegionAlias(region) {
+  if (region === void 0) return "all";
+  if (region in LEGACY_REGION_ALIASES) {
+    const legacy = region;
+    const canonical = LEGACY_REGION_ALIASES[legacy];
+    if (!warned.has(legacy)) {
+      warned.add(legacy);
+      console.warn(
+        `[panchang-ts] FestivalRegion '${legacy}' is deprecated; use '${canonical}'. Legacy value will be removed in v3.`
+      );
+    }
+    return canonical;
+  }
+  return region;
+}
+
 // src/core/bhadra.ts
 function isVishtiKarana(karanaIndex) {
   if (karanaIndex <= 0 || karanaIndex >= 57) return false;
@@ -4350,13 +4557,36 @@ var en = {
     vishu: "Vishu",
     pohela_boishakh: "Pohela Boishakh",
     puthandu: "Puthandu",
+    bohag_bihu: "Bohag Bihu",
     makar_sankranti: "Makar Sankranti",
     pongal: "Pongal",
     uttarayan: "Uttarayan",
-    bihu: "Magh Bihu",
+    magh_bihu: "Magh Bihu",
     ayyappa_makara_jyothi: "Ayyappa Makara Jyothi",
     dakshinayana: "Dakshinayana",
+    raja_sankranti: "Raja Sankranti",
+    raja_pahili: "Pahili Raja",
+    raja_basi: "Basi Raja",
+    harela: "Harela",
     singh_sankranti: "Singh Sankranti",
+    sair: "Sair",
+    kati_bihu: "Kati Bihu",
+    lohri: "Lohri",
+    // Regional festivals (v2.1 expansion)
+    gudi_padwa: "Gudi Padwa",
+    gangaur: "Gangaur",
+    karaga: "Karaga",
+    bonalu: "Bonalu",
+    hariyali_teej: "Hariyali Teej",
+    kajari_teej: "Kajari Teej",
+    hartalika_teej: "Hartalika Teej",
+    govardhan_puja: "Govardhan Puja",
+    bhai_dooj: "Bhai Dooj",
+    phagli: "Phagli",
+    jagannath_rath_yatra: "Jagannath Rath Yatra",
+    varamahalakshmi: "Varamahalakshmi Vratam",
+    bathukamma_start: "Bathukamma \u2014 Engili Pula",
+    bathukamma_saddula: "Bathukamma \u2014 Saddula",
     // Chhath Puja (4-day, Kartika Shukla Chaturthi→Saptami)
     chhath_nahay_khay: "Chhath \u2014 Nahay Khay",
     chhath_kharna: "Chhath \u2014 Kharna",
@@ -4592,13 +4822,36 @@ var hi = {
     vishu: "\u0935\u093F\u0937\u0941",
     pohela_boishakh: "\u092A\u094B\u0939\u0947\u0932\u093E \u092C\u094B\u0907\u0936\u093E\u0916",
     puthandu: "\u092A\u0941\u0925\u093E\u0902\u0921\u0941",
+    bohag_bihu: "\u092C\u094B\u0939\u093E\u0917 \u092C\u093F\u0939\u0942",
     makar_sankranti: "\u092E\u0915\u0930 \u0938\u0902\u0915\u094D\u0930\u093E\u0902\u0924\u093F",
     pongal: "\u092A\u094B\u0902\u0917\u0932",
     uttarayan: "\u0909\u0924\u094D\u0924\u0930\u093E\u092F\u0923",
-    bihu: "\u092E\u093E\u0918 \u092C\u093F\u0939\u0942",
+    magh_bihu: "\u092E\u093E\u0918 \u092C\u093F\u0939\u0942",
     ayyappa_makara_jyothi: "\u0905\u092F\u094D\u092F\u092A\u094D\u092A\u093E \u092E\u0915\u0930 \u091C\u094D\u092F\u094B\u0924\u093F",
     dakshinayana: "\u0926\u0915\u094D\u0937\u093F\u0923\u093E\u092F\u0928",
+    raja_sankranti: "\u0930\u093E\u091C\u093E \u0938\u0902\u0915\u094D\u0930\u093E\u0902\u0924\u093F",
+    raja_pahili: "\u092A\u0939\u093F\u0932\u0940 \u0930\u093E\u091C\u093E",
+    raja_basi: "\u092C\u093E\u0938\u0940 \u0930\u093E\u091C\u093E",
+    harela: "\u0939\u0930\u0947\u0932\u093E",
     singh_sankranti: "\u0938\u093F\u0902\u0939 \u0938\u0902\u0915\u094D\u0930\u093E\u0902\u0924\u093F",
+    sair: "\u0938\u0948\u0930",
+    kati_bihu: "\u0915\u093E\u0924\u0940 \u092C\u093F\u0939\u0942",
+    lohri: "\u0932\u094B\u0939\u0921\u093C\u0940",
+    // Regional festivals (v2.1 expansion)
+    gudi_padwa: "\u0917\u0941\u0921\u093C\u0940 \u092A\u0921\u093C\u0935\u093E",
+    gangaur: "\u0917\u0923\u0917\u094C\u0930",
+    karaga: "\u0915\u0930\u0917\u093E",
+    bonalu: "\u092C\u094B\u0928\u093E\u0932\u0941",
+    hariyali_teej: "\u0939\u0930\u093F\u092F\u093E\u0932\u0940 \u0924\u0940\u091C",
+    kajari_teej: "\u0915\u091C\u0930\u0940 \u0924\u0940\u091C",
+    hartalika_teej: "\u0939\u0930\u0924\u093E\u0932\u093F\u0915\u093E \u0924\u0940\u091C",
+    govardhan_puja: "\u0917\u094B\u0935\u0930\u094D\u0927\u0928 \u092A\u0942\u091C\u093E",
+    bhai_dooj: "\u092D\u093E\u0908 \u0926\u0942\u091C",
+    phagli: "\u092B\u093E\u0917\u094D\u0932\u0940",
+    jagannath_rath_yatra: "\u091C\u0917\u0928\u094D\u0928\u093E\u0925 \u0930\u0925 \u092F\u093E\u0924\u094D\u0930\u093E",
+    varamahalakshmi: "\u0935\u0930\u092E\u0939\u093E\u0932\u0915\u094D\u0937\u094D\u092E\u0940 \u0935\u094D\u0930\u0924",
+    bathukamma_start: "\u092C\u0924\u0941\u0915\u092E\u094D\u092E\u093E \u2014 \u090F\u0902\u0917\u093F\u0932\u0940 \u092A\u0941\u0932\u093E",
+    bathukamma_saddula: "\u092C\u0924\u0941\u0915\u092E\u094D\u092E\u093E \u2014 \u0938\u0926\u094D\u0926\u0941\u0932\u093E",
     // Chhath Puja
     chhath_nahay_khay: "\u091B\u0920 \u2014 \u0928\u0939\u093E\u092F \u0916\u093E\u092F",
     chhath_kharna: "\u091B\u0920 \u2014 \u0916\u0930\u0928\u093E",
@@ -4828,7 +5081,7 @@ function getInstantPanchang(date, location, options) {
       isAdhika: chandramasa.isAdhika,
       varaIndex: vara.index,
       solarMasaIndex: Math.floor(siderealSun / 30) % 12,
-      region: options?.region ?? "all"
+      region: resolveRegionAlias(options?.region)
     },
     (key) => t.festivalNames[key] ?? t.misc[key] ?? key,
     (idx) => resolveMasaName(idx, lang)
@@ -5013,6 +5266,21 @@ function getDailyPanchang(date, location, options) {
   const rashiAtSunrise = Math.floor(siderealSunAtSunrise / 30) % 12;
   const rashiAtNextSunrise = Math.floor(getSun(nextSunriseUtc) / 30) % 12;
   const sankrantiRashi = rashiAtSunrise !== rashiAtNextSunrise ? rashiAtNextSunrise : null;
+  let nextDaySankrantiRashi = null;
+  try {
+    const tomorrowSunsetUtc = computeSunset(nextSunriseUtc, location);
+    const dayAfterSunriseUtc = computeSunrise(tomorrowSunsetUtc, location);
+    const rashiAtDayAfterSunrise = Math.floor(getSun(dayAfterSunriseUtc) / 30) % 12;
+    if (rashiAtNextSunrise !== rashiAtDayAfterSunrise) {
+      nextDaySankrantiRashi = rashiAtDayAfterSunrise;
+    }
+  } catch (e) {
+    if (!(e instanceof PanchangError && (e.code === "NO_SUNRISE" || e.code === "NO_SUNSET"))) {
+      throw e;
+    }
+  }
+  const rashiAtYesterdaySunrise = Math.floor(getSun(yesterdaySunriseUtc) / 30) % 12;
+  const prevDaySankrantiRashi = rashiAtYesterdaySunrise !== rashiAtSunrise ? rashiAtSunrise : null;
   let ekadashiDashamiViddha = false;
   if (tithiAtSunrise.index === 10 || tithiAtSunrise.index === 25) {
     const tithiAtArunodaya = tithiAt(arunodayaUtc);
@@ -5062,6 +5330,8 @@ function getDailyPanchang(date, location, options) {
       priorDayTithiByRule,
       nakshatraIndicesInDay,
       sankrantiRashi,
+      nextDaySankrantiRashi,
+      prevDaySankrantiRashi,
       ekadashiDashamiViddha,
       smartaDwadashiToday,
       moonriseInDay: moonriseInDayUtc,
@@ -5070,7 +5340,7 @@ function getDailyPanchang(date, location, options) {
         end: utcToLocalDisplay(bhadraUtc.end, offsetMinutes)
       } : null,
       formatClock,
-      region: options.region ?? "all"
+      region: resolveRegionAlias(options.region)
     },
     (key) => t.festivalNames[key] ?? t.misc[key] ?? key,
     (idx) => resolveMasaName(idx, lang)

package/dist/index.d.cts

@@ -12,13 +12,31 @@ type Language = 'en' | 'hi';
 type Precision = 'standard' | 'high';
 type MasaSystem = 'purnimanta' | 'amanta';
 /**
- * Regional scope for region-specific festival variants (primarily regional
- * Sankranti names — Pongal, Vishu, Baisakhi, Bihu, Ayyappa Makara Jyothi,
- * etc.). Default `'all'` emits every regional variant; narrower values
- * filter the regional variants to that region. The canonical pan-Indian
+ * Regional scope for region-specific festival variants. Default `'all'` emits
+ * every regional variant; narrower values filter to festivals scoped to that
+ * region (or pan-Indian festivals, which always emit). The canonical
  * `sankranti` event is always emitted regardless of this setting.
+ *
+ * State-slug naming: each value corresponds to an Indian state (or `nepal`
+ * for Nepali panchang usage). The single pre-v2.1 direction-based value
+ * `'north-india'` and the ethno-linguistic slugs `'tamil'` and `'bengal'`
+ * are still accepted as inputs ({@link LegacyFestivalRegion}) and mapped
+ * to their canonical equivalents at entry-point resolution time.
+ */
+type FestivalRegion = 'all' | 'tamil-nadu' | 'kerala' | 'karnataka' | 'andhra-pradesh' | 'telangana' | 'west-bengal' | 'odisha' | 'assam' | 'bihar' | 'jharkhand' | 'gujarat' | 'maharashtra' | 'goa' | 'rajasthan' | 'punjab' | 'haryana' | 'himachal-pradesh' | 'uttarakhand' | 'uttar-pradesh' | 'madhya-pradesh' | 'nepal';
+/**
+ * Pre-v2.1 region identifiers accepted for back-compat. These are mapped
+ * to canonical {@link FestivalRegion} values by `resolveRegionAlias` before
+ * festival filtering. Slated for removal in v3.
+ *
+ * - `'tamil'`       → `'tamil-nadu'`
+ * - `'bengal'`      → `'west-bengal'`
+ * - `'north-india'` → `'all'` (Makar Sankranti is pan-Indian; use explicit
+ *                              state slugs for Lohri / Govardhan / Bhai Dooj)
+ *
+ * @deprecated Use the equivalent {@link FestivalRegion} value. Removal in v3.
  */
-type FestivalRegion = 'all' | 'north-india' | 'tamil' | 'kerala' | 'bengal' | 'punjab' | 'gujarat' | 'assam' | 'maharashtra';
+type LegacyFestivalRegion = 'tamil' | 'bengal' | 'north-india';
 interface PanchangOptions {
     timezone: number | string;
     ayanamsa?: AyanamsaType;
@@ -35,9 +53,10 @@ interface PanchangOptions {
     janmaRashi?: number;
     /**
      * Regional scope for region-specific festival variants. Default `'all'`.
-     * See {@link FestivalRegion} for supported regions.
+     * See {@link FestivalRegion} for supported regions; pre-v2.1 values
+     * ({@link LegacyFestivalRegion}) are accepted and mapped internally.
      */
-    region?: FestivalRegion;
+    region?: FestivalRegion | LegacyFestivalRegion;
 }
 interface InstantPanchangOptions {
     ayanamsa?: AyanamsaType;
@@ -54,9 +73,10 @@ interface InstantPanchangOptions {
     janmaRashi?: number;
     /**
      * Regional scope for region-specific festival variants. Default `'all'`.
-     * See {@link FestivalRegion} for supported regions.
+     * See {@link FestivalRegion} for supported regions; pre-v2.1 values
+     * ({@link LegacyFestivalRegion}) are accepted and mapped internally.
      */
-    region?: FestivalRegion;
+    region?: FestivalRegion | LegacyFestivalRegion;
 }
 
 interface TimePeriod {
@@ -964,4 +984,4 @@ declare class PanchangError extends Error {
     constructor(message: string, code: PanchangErrorCode);
 }
 
-export { type AntarDasha, type AyanamsaType, type BhadraInfo, type ChandraBalamInfo, type ChandraMasaInfo, type ChoghadiyaInfo, type ChoghadiyaQuality, type ChoghadiyaSlot, type DailyKaranaInfo, type DailyNakshatraInfo, type DailyPanchangResult, type DailyTithiInfo, type DailyYogaInfo, type DashaLord, type FestivalInfo, type FestivalRegion, GRAHA_ABBR, type GeoLocation, type GowriInfo, type GowriSlot, type GrahaName, type GrahaPosition, type HoraInfo, type HoraSlot, type InstantPanchangOptions, type InstantPanchangResult, type KaranaInfo, type Language, type MahaDasha, type MasaInfo, type MasaSystem, type NakshatraInfo, PanchangError, type PanchangErrorCode, type PanchangOptions, type PlanetaryPositions, type Precision, type RashiInfo, type SamvatInfo, type SpecialYogaInfo, type TimePeriod, type TithiInfo, type VaraInfo, type VimshottariDashaResult, type YogaInfo, computeAbhijitMuhurta, computeAmritKala, computeBrahmaMuhurta, computeChandraBalam, computeGodhuliMuhurta, computeGowriPanchangam, computeGulikaKalam, computeNishitaMuhurta, computePlanetaryPositions, computeRahuKalam, computeVijayaMuhurta, computeVimshottariDasha, computeVimshottariDashaFromBirth, computeYamaganda, computeAyanamsa as getAyanamsa, getDailyPanchang, getEclipseDuringDay, getInstantPanchang, getMoonrise, getMoonset, getSiderealMoonLongitude, getSiderealSunLongitude, computeSunrise as getSunrise, computeSunset as getSunset, getUpcomingLunarEclipse, getUpcomingSolarEclipse };
+export { type AntarDasha, type AyanamsaType, type BhadraInfo, type ChandraBalamInfo, type ChandraMasaInfo, type ChoghadiyaInfo, type ChoghadiyaQuality, type ChoghadiyaSlot, type DailyKaranaInfo, type DailyNakshatraInfo, type DailyPanchangResult, type DailyTithiInfo, type DailyYogaInfo, type DashaLord, type FestivalInfo, type FestivalRegion, GRAHA_ABBR, type GeoLocation, type GowriInfo, type GowriSlot, type GrahaName, type GrahaPosition, type HoraInfo, type HoraSlot, type InstantPanchangOptions, type InstantPanchangResult, type KaranaInfo, type Language, type LegacyFestivalRegion, type MahaDasha, type MasaInfo, type MasaSystem, type NakshatraInfo, PanchangError, type PanchangErrorCode, type PanchangOptions, type PlanetaryPositions, type Precision, type RashiInfo, type SamvatInfo, type SpecialYogaInfo, type TimePeriod, type TithiInfo, type VaraInfo, type VimshottariDashaResult, type YogaInfo, computeAbhijitMuhurta, computeAmritKala, computeBrahmaMuhurta, computeChandraBalam, computeGodhuliMuhurta, computeGowriPanchangam, computeGulikaKalam, computeNishitaMuhurta, computePlanetaryPositions, computeRahuKalam, computeVijayaMuhurta, computeVimshottariDasha, computeVimshottariDashaFromBirth, computeYamaganda, computeAyanamsa as getAyanamsa, getDailyPanchang, getEclipseDuringDay, getInstantPanchang, getMoonrise, getMoonset, getSiderealMoonLongitude, getSiderealSunLongitude, computeSunrise as getSunrise, computeSunset as getSunset, getUpcomingLunarEclipse, getUpcomingSolarEclipse };

package/dist/index.d.ts

@@ -12,13 +12,31 @@ type Language = 'en' | 'hi';
 type Precision = 'standard' | 'high';
 type MasaSystem = 'purnimanta' | 'amanta';
 /**
- * Regional scope for region-specific festival variants (primarily regional
- * Sankranti names — Pongal, Vishu, Baisakhi, Bihu, Ayyappa Makara Jyothi,
- * etc.). Default `'all'` emits every regional variant; narrower values
- * filter the regional variants to that region. The canonical pan-Indian
+ * Regional scope for region-specific festival variants. Default `'all'` emits
+ * every regional variant; narrower values filter to festivals scoped to that
+ * region (or pan-Indian festivals, which always emit). The canonical
  * `sankranti` event is always emitted regardless of this setting.
+ *
+ * State-slug naming: each value corresponds to an Indian state (or `nepal`
+ * for Nepali panchang usage). The single pre-v2.1 direction-based value
+ * `'north-india'` and the ethno-linguistic slugs `'tamil'` and `'bengal'`
+ * are still accepted as inputs ({@link LegacyFestivalRegion}) and mapped
+ * to their canonical equivalents at entry-point resolution time.
+ */
+type FestivalRegion = 'all' | 'tamil-nadu' | 'kerala' | 'karnataka' | 'andhra-pradesh' | 'telangana' | 'west-bengal' | 'odisha' | 'assam' | 'bihar' | 'jharkhand' | 'gujarat' | 'maharashtra' | 'goa' | 'rajasthan' | 'punjab' | 'haryana' | 'himachal-pradesh' | 'uttarakhand' | 'uttar-pradesh' | 'madhya-pradesh' | 'nepal';
+/**
+ * Pre-v2.1 region identifiers accepted for back-compat. These are mapped
+ * to canonical {@link FestivalRegion} values by `resolveRegionAlias` before
+ * festival filtering. Slated for removal in v3.
+ *
+ * - `'tamil'`       → `'tamil-nadu'`
+ * - `'bengal'`      → `'west-bengal'`
+ * - `'north-india'` → `'all'` (Makar Sankranti is pan-Indian; use explicit
+ *                              state slugs for Lohri / Govardhan / Bhai Dooj)
+ *
+ * @deprecated Use the equivalent {@link FestivalRegion} value. Removal in v3.
  */
-type FestivalRegion = 'all' | 'north-india' | 'tamil' | 'kerala' | 'bengal' | 'punjab' | 'gujarat' | 'assam' | 'maharashtra';
+type LegacyFestivalRegion = 'tamil' | 'bengal' | 'north-india';
 interface PanchangOptions {
     timezone: number | string;
     ayanamsa?: AyanamsaType;
@@ -35,9 +53,10 @@ interface PanchangOptions {
     janmaRashi?: number;
     /**
      * Regional scope for region-specific festival variants. Default `'all'`.
-     * See {@link FestivalRegion} for supported regions.
+     * See {@link FestivalRegion} for supported regions; pre-v2.1 values
+     * ({@link LegacyFestivalRegion}) are accepted and mapped internally.
      */
-    region?: FestivalRegion;
+    region?: FestivalRegion | LegacyFestivalRegion;
 }
 interface InstantPanchangOptions {
     ayanamsa?: AyanamsaType;
@@ -54,9 +73,10 @@ interface InstantPanchangOptions {
     janmaRashi?: number;
     /**
      * Regional scope for region-specific festival variants. Default `'all'`.
-     * See {@link FestivalRegion} for supported regions.
+     * See {@link FestivalRegion} for supported regions; pre-v2.1 values
+     * ({@link LegacyFestivalRegion}) are accepted and mapped internally.
      */
-    region?: FestivalRegion;
+    region?: FestivalRegion | LegacyFestivalRegion;
 }
 
 interface TimePeriod {
@@ -964,4 +984,4 @@ declare class PanchangError extends Error {
     constructor(message: string, code: PanchangErrorCode);
 }
 
-export { type AntarDasha, type AyanamsaType, type BhadraInfo, type ChandraBalamInfo, type ChandraMasaInfo, type ChoghadiyaInfo, type ChoghadiyaQuality, type ChoghadiyaSlot, type DailyKaranaInfo, type DailyNakshatraInfo, type DailyPanchangResult, type DailyTithiInfo, type DailyYogaInfo, type DashaLord, type FestivalInfo, type FestivalRegion, GRAHA_ABBR, type GeoLocation, type GowriInfo, type GowriSlot, type GrahaName, type GrahaPosition, type HoraInfo, type HoraSlot, type InstantPanchangOptions, type InstantPanchangResult, type KaranaInfo, type Language, type MahaDasha, type MasaInfo, type MasaSystem, type NakshatraInfo, PanchangError, type PanchangErrorCode, type PanchangOptions, type PlanetaryPositions, type Precision, type RashiInfo, type SamvatInfo, type SpecialYogaInfo, type TimePeriod, type TithiInfo, type VaraInfo, type VimshottariDashaResult, type YogaInfo, computeAbhijitMuhurta, computeAmritKala, computeBrahmaMuhurta, computeChandraBalam, computeGodhuliMuhurta, computeGowriPanchangam, computeGulikaKalam, computeNishitaMuhurta, computePlanetaryPositions, computeRahuKalam, computeVijayaMuhurta, computeVimshottariDasha, computeVimshottariDashaFromBirth, computeYamaganda, computeAyanamsa as getAyanamsa, getDailyPanchang, getEclipseDuringDay, getInstantPanchang, getMoonrise, getMoonset, getSiderealMoonLongitude, getSiderealSunLongitude, computeSunrise as getSunrise, computeSunset as getSunset, getUpcomingLunarEclipse, getUpcomingSolarEclipse };
+export { type AntarDasha, type AyanamsaType, type BhadraInfo, type ChandraBalamInfo, type ChandraMasaInfo, type ChoghadiyaInfo, type ChoghadiyaQuality, type ChoghadiyaSlot, type DailyKaranaInfo, type DailyNakshatraInfo, type DailyPanchangResult, type DailyTithiInfo, type DailyYogaInfo, type DashaLord, type FestivalInfo, type FestivalRegion, GRAHA_ABBR, type GeoLocation, type GowriInfo, type GowriSlot, type GrahaName, type GrahaPosition, type HoraInfo, type HoraSlot, type InstantPanchangOptions, type InstantPanchangResult, type KaranaInfo, type Language, type LegacyFestivalRegion, type MahaDasha, type MasaInfo, type MasaSystem, type NakshatraInfo, PanchangError, type PanchangErrorCode, type PanchangOptions, type PlanetaryPositions, type Precision, type RashiInfo, type SamvatInfo, type SpecialYogaInfo, type TimePeriod, type TithiInfo, type VaraInfo, type VimshottariDashaResult, type YogaInfo, computeAbhijitMuhurta, computeAmritKala, computeBrahmaMuhurta, computeChandraBalam, computeGodhuliMuhurta, computeGowriPanchangam, computeGulikaKalam, computeNishitaMuhurta, computePlanetaryPositions, computeRahuKalam, computeVijayaMuhurta, computeVimshottariDasha, computeVimshottariDashaFromBirth, computeYamaganda, computeAyanamsa as getAyanamsa, getDailyPanchang, getEclipseDuringDay, getInstantPanchang, getMoonrise, getMoonset, getSiderealMoonLongitude, getSiderealSunLongitude, computeSunrise as getSunrise, computeSunset as getSunset, getUpcomingLunarEclipse, getUpcomingSolarEclipse };

package/dist/index.js

@@ -3754,28 +3754,47 @@ function computeDurMuhurta(sunrise, sunset, varaIndex) {
 var SANKRANTI_REGIONAL = {
   // Mesha (0) — solar new year across regions
   0: [
-    { key: "baisakhi", region: "punjab", type: "major" },
-    { key: "vishu", region: "kerala", type: "major" },
-    { key: "pohela_boishakh", region: "bengal", type: "major" },
-    { key: "puthandu", region: "tamil", type: "major" }
+    { key: "baisakhi", regions: ["punjab", "haryana"], type: "major" },
+    { key: "vishu", regions: ["kerala"], type: "major" },
+    { key: "pohela_boishakh", regions: ["west-bengal"], type: "major" },
+    { key: "puthandu", regions: ["tamil-nadu"], type: "major" },
+    { key: "bohag_bihu", regions: ["assam"], type: "major" }
   ],
   // Karka (3) — Dakshinayana (Sun's southward course begins)
   3: [
-    { key: "dakshinayana", region: "all", type: "minor" }
+    { key: "dakshinayana", regions: ["all"], type: "minor" },
+    // Raja Parba (Odisha) — 4-day monsoon festival; we emit a single-day
+    // marker on Karka Sankranti, the most widely cited anchor day.
+    { key: "raja_sankranti", regions: ["odisha"], type: "major" },
+    // Harela (Kumaon / Uttarakhand) — observed on Shravana solar-month start.
+    { key: "harela", regions: ["uttarakhand"], type: "major" }
   ],
-  // Simha (4)
+  // Simha (4) — Singh Sankranti is primarily observed in Odisha, Bihar,
+  // and Nepal (as Singhasankranti); not a pan-Indian observance despite
+  // the pre-v2.1 tagging.
   4: [
-    { key: "singh_sankranti", region: "all", type: "minor" }
+    { key: "singh_sankranti", regions: ["odisha", "bihar", "jharkhand", "nepal"], type: "minor" }
+  ],
+  // Kanya (5) — Sair (Himachal): first day of the Ashwin solar month.
+  5: [
+    { key: "sair", regions: ["himachal-pradesh"], type: "minor" }
+  ],
+  // Tula (6) — Kati Bihu (Assam): Kartika solar-month start.
+  6: [
+    { key: "kati_bihu", regions: ["assam"], type: "minor" }
   ],
   // Makara (9) — Uttarayana / harvest festivals
   9: [
-    { key: "makar_sankranti", region: "north-india", type: "major" },
-    { key: "pongal", region: "tamil", type: "major" },
-    { key: "uttarayan", region: "gujarat", type: "major" },
-    { key: "bihu", region: "assam", type: "major" },
-    { key: "ayyappa_makara_jyothi", region: "kerala", type: "major" }
+    // Makar Sankranti is pan-Indian (re-scoped from the pre-v2.1 'north-india').
+    { key: "makar_sankranti", regions: ["all"], type: "major" },
+    { key: "pongal", regions: ["tamil-nadu"], type: "major" },
+    { key: "uttarayan", regions: ["gujarat"], type: "major" },
+    { key: "magh_bihu", regions: ["assam"], type: "major" },
+    { key: "ayyappa_makara_jyothi", regions: ["kerala"], type: "major" }
   ]
 };
+var LOHRI_REGIONS = ["punjab", "haryana", "himachal-pradesh"];
+var RAJA_REGIONS = ["odisha"];
 var FESTIVAL_REGISTRY = [
   // Chaitra (0)
   { key: "ugadi", masa: 0, tithi: 0, type: "major" },
@@ -3849,7 +3868,144 @@ var FESTIVAL_REGISTRY = [
   // Rig Upakarma — Shravana nakshatra (21) in Shravana chandra masa (4).
   { key: "rig_upakarma", masa: 4, nakshatra: 21, type: "major" },
   // Sama Upakarma — Hasta nakshatra (12) in Bhadrapada chandra masa (5).
-  { key: "sama_upakarma", masa: 5, nakshatra: 12, type: "major" }
+  { key: "sama_upakarma", masa: 5, nakshatra: 12, type: "major" },
+  // ── Regional festivals (v2.1 expansion) ─────────────────────
+  // Chaitra (0) — Marathi/Konkani New Year; same tithi as Ugadi but
+  // emitted as a Maharashtra-specific variant name alongside Ugadi.
+  {
+    key: "gudi_padwa",
+    masa: 0,
+    tithi: 0,
+    type: "major",
+    regions: ["maharashtra", "goa"]
+  },
+  // Chaitra (0) Shukla Tritiya — Gangaur (18-day festival concludes here).
+  {
+    key: "gangaur",
+    masa: 0,
+    tithi: 2,
+    type: "major",
+    regions: ["rajasthan"]
+  },
+  // Chaitra (0) Purnima — Karaga festival of Bengaluru.
+  {
+    key: "karaga",
+    masa: 0,
+    tithi: 14,
+    type: "major",
+    regions: ["karnataka"]
+  },
+  // Ashadha (3) — Bonalu, Sundays at Mahakali temples across Telangana.
+  {
+    key: "bonalu",
+    masa: 3,
+    vara: 0,
+    type: "minor",
+    adhikaBehaviour: "observe-in-both",
+    regions: ["telangana"]
+  },
+  // Shravana (4) Shukla Tritiya — Hariyali Teej.
+  {
+    key: "hariyali_teej",
+    masa: 4,
+    tithi: 2,
+    type: "major",
+    regions: ["rajasthan", "uttar-pradesh", "bihar", "haryana", "madhya-pradesh"]
+  },
+  // Shravana (4) Krishna Tritiya — Kajari Teej (tithi 17 = Krishna Tritiya).
+  {
+    key: "kajari_teej",
+    masa: 4,
+    tithi: 17,
+    type: "major",
+    regions: ["rajasthan", "uttar-pradesh", "madhya-pradesh"]
+  },
+  // Bhadrapada (5) Shukla Tritiya — Hartalika Teej.
+  {
+    key: "hartalika_teej",
+    masa: 5,
+    tithi: 2,
+    type: "major",
+    regions: ["rajasthan", "uttar-pradesh", "bihar", "maharashtra", "madhya-pradesh"]
+  },
+  // Amanta Kartika (7) Shukla Pratipada — day after Diwali.
+  // In Purnimanta convention this is also "Kartika Shukla Pratipada" (naming
+  // system aligns), so a namingSystem tag isn't required here.
+  {
+    key: "govardhan_puja",
+    masa: 7,
+    tithi: 0,
+    type: "major",
+    regions: [
+      "uttar-pradesh",
+      "bihar",
+      "haryana",
+      "rajasthan",
+      "gujarat",
+      "madhya-pradesh",
+      "punjab",
+      "jharkhand"
+    ]
+  },
+  // Amanta Kartika (7) Shukla Dwitiya — Bhai Dooj.
+  {
+    key: "bhai_dooj",
+    masa: 7,
+    tithi: 1,
+    type: "major",
+    regions: [
+      "uttar-pradesh",
+      "bihar",
+      "haryana",
+      "maharashtra",
+      "gujarat",
+      "rajasthan",
+      "madhya-pradesh",
+      "west-bengal",
+      "jharkhand",
+      "nepal"
+    ]
+  },
+  // Phalguna (11) Purnima — Phagli (varies by valley; Purnima anchor).
+  {
+    key: "phagli",
+    masa: 11,
+    tithi: 14,
+    type: "minor",
+    regions: ["himachal-pradesh"]
+  },
+  // Ashadha (3) Shukla Dwitiya — Jagannath Rath Yatra (pan-Indian; cultural
+  // epicenter is Puri, Odisha but observed nationwide).
+  { key: "jagannath_rath_yatra", masa: 3, tithi: 1, type: "major" },
+  // Shravana (4) Shukla — Varamahalakshmi: last Friday in Shukla paksha
+  // before Purnima. The (masa+vara) match is gated by tithi ∈ [7,13] so
+  // only the second Friday of the paksha (the one closest to Purnima) fires.
+  {
+    key: "varamahalakshmi",
+    masa: 4,
+    vara: 5,
+    type: "major",
+    tithiRange: [7, 13],
+    regions: ["karnataka", "andhra-pradesh", "telangana", "tamil-nadu"]
+  },
+  // Bathukamma (Telangana) — 9-day floral festival from Bhadrapada
+  // Amavasya through Ashwin Shukla Navami. We emit start (Engili Pula
+  // Bathukamma, masa=5/tithi=29) and climax (Saddula Bathukamma, masa=6/
+  // tithi=8) markers; intermediate days carry no library-level emission.
+  {
+    key: "bathukamma_start",
+    masa: 5,
+    tithi: 29,
+    type: "major",
+    regions: ["telangana"]
+  },
+  {
+    key: "bathukamma_saddula",
+    masa: 6,
+    tithi: 8,
+    type: "major",
+    regions: ["telangana"]
+  }
 ];
 var EKADASHI_NAMES = [
   ["kamada", "papamochani"],
@@ -3926,7 +4082,14 @@ function computeFestivals(ctx, nameResolver, rashiNameResolver) {
       match = masaMatches && rule.nakshatra === ctx.nakshatraIndex;
     } else if (rule.vara !== void 0 && rule.masa !== void 0) {
       const masaMatches = rule.masa === ctx.chandraMasaIndex && (adhikaBehaviour !== "shift-to-nija" || !ctx.isAdhika);
-      match = masaMatches && rule.vara === ctx.varaIndex;
+      let inTithiRange = true;
+      if (rule.tithiRange !== void 0) {
+        const dateRule = rule.dateRule ?? "sunrise";
+        const tithi = tithiForRule(dateRule);
+        const [lo, hi2] = rule.tithiRange;
+        inTithiRange = tithi >= lo && tithi <= hi2;
+      }
+      match = masaMatches && rule.vara === ctx.varaIndex && inTithiRange;
     } else if (rule.masa !== void 0 && rule.tithi !== void 0) {
       const masaMatches = rule.masa === ctx.chandraMasaIndex && // `shift-to-nija`: only observe in Nija following an Adhika (but still OK if no prior Adhika,
       // since the normal year has no Adhika and the festival observes as usual).
@@ -3946,6 +4109,12 @@ function computeFestivals(ctx, nameResolver, rashiNameResolver) {
       }
     }
     if (!match) continue;
+    if (rule.regions !== void 0) {
+      const region2 = ctx.region ?? "all";
+      if (region2 !== "all" && !rule.regions.includes("all") && !rule.regions.includes(region2)) {
+        continue;
+      }
+    }
     const festival = { name: nameResolver(rule.key), type: rule.type };
     if (rule.namingSystem === "purnimanta" && ctx.purnimantaMasaName && ctx.amantaMasaName) {
       festival.description = `Purnimanta: ${ctx.purnimantaMasaName} Krishna Paksha`;
@@ -4050,6 +4219,7 @@ function computeFestivals(ctx, nameResolver, rashiNameResolver) {
       description: nameResolver(variantKey)
     });
   }
+  const region = ctx.region ?? "all";
   if (ctx.sankrantiRashi !== void 0 && ctx.sankrantiRashi !== null) {
     const rashiName = rashiNameResolver ? rashiNameResolver(ctx.sankrantiRashi) : `Rashi ${ctx.sankrantiRashi}`;
     results.push({
@@ -4057,11 +4227,10 @@ function computeFestivals(ctx, nameResolver, rashiNameResolver) {
       type: "sankranti",
       description: rashiName
     });
-    const region = ctx.region ?? "all";
     const regionalRules = SANKRANTI_REGIONAL[ctx.sankrantiRashi];
     if (regionalRules) {
       for (const r of regionalRules) {
-        if (region !== "all" && r.region !== "all" && r.region !== region) continue;
+        if (region !== "all" && !r.regions.includes("all") && !r.regions.includes(region)) continue;
         results.push({
           name: nameResolver(r.key),
           type: "sankranti",
@@ -4070,9 +4239,47 @@ function computeFestivals(ctx, nameResolver, rashiNameResolver) {
       }
     }
   }
+  if (ctx.nextDaySankrantiRashi === 9) {
+    if (region === "all" || LOHRI_REGIONS.includes(region)) {
+      results.push({ name: nameResolver("lohri"), type: "major" });
+    }
+  }
+  if (ctx.nextDaySankrantiRashi === 3) {
+    if (region === "all" || RAJA_REGIONS.includes(region)) {
+      results.push({ name: nameResolver("raja_pahili"), type: "major" });
+    }
+  }
+  if (ctx.prevDaySankrantiRashi === 3) {
+    if (region === "all" || RAJA_REGIONS.includes(region)) {
+      results.push({ name: nameResolver("raja_basi"), type: "major" });
+    }
+  }
   return results;
 }
 
+// src/core/regionAlias.ts
+var LEGACY_REGION_ALIASES = {
+  "tamil": "tamil-nadu",
+  "bengal": "west-bengal",
+  "north-india": "all"
+};
+var warned = /* @__PURE__ */ new Set();
+function resolveRegionAlias(region) {
+  if (region === void 0) return "all";
+  if (region in LEGACY_REGION_ALIASES) {
+    const legacy = region;
+    const canonical = LEGACY_REGION_ALIASES[legacy];
+    if (!warned.has(legacy)) {
+      warned.add(legacy);
+      console.warn(
+        `[panchang-ts] FestivalRegion '${legacy}' is deprecated; use '${canonical}'. Legacy value will be removed in v3.`
+      );
+    }
+    return canonical;
+  }
+  return region;
+}
+
 // src/core/bhadra.ts
 function isVishtiKarana(karanaIndex) {
   if (karanaIndex <= 0 || karanaIndex >= 57) return false;
@@ -4348,13 +4555,36 @@ var en = {
     vishu: "Vishu",
     pohela_boishakh: "Pohela Boishakh",
     puthandu: "Puthandu",
+    bohag_bihu: "Bohag Bihu",
     makar_sankranti: "Makar Sankranti",
     pongal: "Pongal",
     uttarayan: "Uttarayan",
-    bihu: "Magh Bihu",
+    magh_bihu: "Magh Bihu",
     ayyappa_makara_jyothi: "Ayyappa Makara Jyothi",
     dakshinayana: "Dakshinayana",
+    raja_sankranti: "Raja Sankranti",
+    raja_pahili: "Pahili Raja",
+    raja_basi: "Basi Raja",
+    harela: "Harela",
     singh_sankranti: "Singh Sankranti",
+    sair: "Sair",
+    kati_bihu: "Kati Bihu",
+    lohri: "Lohri",
+    // Regional festivals (v2.1 expansion)
+    gudi_padwa: "Gudi Padwa",
+    gangaur: "Gangaur",
+    karaga: "Karaga",
+    bonalu: "Bonalu",
+    hariyali_teej: "Hariyali Teej",
+    kajari_teej: "Kajari Teej",
+    hartalika_teej: "Hartalika Teej",
+    govardhan_puja: "Govardhan Puja",
+    bhai_dooj: "Bhai Dooj",
+    phagli: "Phagli",
+    jagannath_rath_yatra: "Jagannath Rath Yatra",
+    varamahalakshmi: "Varamahalakshmi Vratam",
+    bathukamma_start: "Bathukamma \u2014 Engili Pula",
+    bathukamma_saddula: "Bathukamma \u2014 Saddula",
     // Chhath Puja (4-day, Kartika Shukla Chaturthi→Saptami)
     chhath_nahay_khay: "Chhath \u2014 Nahay Khay",
     chhath_kharna: "Chhath \u2014 Kharna",
@@ -4590,13 +4820,36 @@ var hi = {
     vishu: "\u0935\u093F\u0937\u0941",
     pohela_boishakh: "\u092A\u094B\u0939\u0947\u0932\u093E \u092C\u094B\u0907\u0936\u093E\u0916",
     puthandu: "\u092A\u0941\u0925\u093E\u0902\u0921\u0941",
+    bohag_bihu: "\u092C\u094B\u0939\u093E\u0917 \u092C\u093F\u0939\u0942",
     makar_sankranti: "\u092E\u0915\u0930 \u0938\u0902\u0915\u094D\u0930\u093E\u0902\u0924\u093F",
     pongal: "\u092A\u094B\u0902\u0917\u0932",
     uttarayan: "\u0909\u0924\u094D\u0924\u0930\u093E\u092F\u0923",
-    bihu: "\u092E\u093E\u0918 \u092C\u093F\u0939\u0942",
+    magh_bihu: "\u092E\u093E\u0918 \u092C\u093F\u0939\u0942",
     ayyappa_makara_jyothi: "\u0905\u092F\u094D\u092F\u092A\u094D\u092A\u093E \u092E\u0915\u0930 \u091C\u094D\u092F\u094B\u0924\u093F",
     dakshinayana: "\u0926\u0915\u094D\u0937\u093F\u0923\u093E\u092F\u0928",
+    raja_sankranti: "\u0930\u093E\u091C\u093E \u0938\u0902\u0915\u094D\u0930\u093E\u0902\u0924\u093F",
+    raja_pahili: "\u092A\u0939\u093F\u0932\u0940 \u0930\u093E\u091C\u093E",
+    raja_basi: "\u092C\u093E\u0938\u0940 \u0930\u093E\u091C\u093E",
+    harela: "\u0939\u0930\u0947\u0932\u093E",
     singh_sankranti: "\u0938\u093F\u0902\u0939 \u0938\u0902\u0915\u094D\u0930\u093E\u0902\u0924\u093F",
+    sair: "\u0938\u0948\u0930",
+    kati_bihu: "\u0915\u093E\u0924\u0940 \u092C\u093F\u0939\u0942",
+    lohri: "\u0932\u094B\u0939\u0921\u093C\u0940",
+    // Regional festivals (v2.1 expansion)
+    gudi_padwa: "\u0917\u0941\u0921\u093C\u0940 \u092A\u0921\u093C\u0935\u093E",
+    gangaur: "\u0917\u0923\u0917\u094C\u0930",
+    karaga: "\u0915\u0930\u0917\u093E",
+    bonalu: "\u092C\u094B\u0928\u093E\u0932\u0941",
+    hariyali_teej: "\u0939\u0930\u093F\u092F\u093E\u0932\u0940 \u0924\u0940\u091C",
+    kajari_teej: "\u0915\u091C\u0930\u0940 \u0924\u0940\u091C",
+    hartalika_teej: "\u0939\u0930\u0924\u093E\u0932\u093F\u0915\u093E \u0924\u0940\u091C",
+    govardhan_puja: "\u0917\u094B\u0935\u0930\u094D\u0927\u0928 \u092A\u0942\u091C\u093E",
+    bhai_dooj: "\u092D\u093E\u0908 \u0926\u0942\u091C",
+    phagli: "\u092B\u093E\u0917\u094D\u0932\u0940",
+    jagannath_rath_yatra: "\u091C\u0917\u0928\u094D\u0928\u093E\u0925 \u0930\u0925 \u092F\u093E\u0924\u094D\u0930\u093E",
+    varamahalakshmi: "\u0935\u0930\u092E\u0939\u093E\u0932\u0915\u094D\u0937\u094D\u092E\u0940 \u0935\u094D\u0930\u0924",
+    bathukamma_start: "\u092C\u0924\u0941\u0915\u092E\u094D\u092E\u093E \u2014 \u090F\u0902\u0917\u093F\u0932\u0940 \u092A\u0941\u0932\u093E",
+    bathukamma_saddula: "\u092C\u0924\u0941\u0915\u092E\u094D\u092E\u093E \u2014 \u0938\u0926\u094D\u0926\u0941\u0932\u093E",
     // Chhath Puja
     chhath_nahay_khay: "\u091B\u0920 \u2014 \u0928\u0939\u093E\u092F \u0916\u093E\u092F",
     chhath_kharna: "\u091B\u0920 \u2014 \u0916\u0930\u0928\u093E",
@@ -4826,7 +5079,7 @@ function getInstantPanchang(date, location, options) {
       isAdhika: chandramasa.isAdhika,
       varaIndex: vara.index,
       solarMasaIndex: Math.floor(siderealSun / 30) % 12,
-      region: options?.region ?? "all"
+      region: resolveRegionAlias(options?.region)
     },
     (key) => t.festivalNames[key] ?? t.misc[key] ?? key,
     (idx) => resolveMasaName(idx, lang)
@@ -5011,6 +5264,21 @@ function getDailyPanchang(date, location, options) {
   const rashiAtSunrise = Math.floor(siderealSunAtSunrise / 30) % 12;
   const rashiAtNextSunrise = Math.floor(getSun(nextSunriseUtc) / 30) % 12;
   const sankrantiRashi = rashiAtSunrise !== rashiAtNextSunrise ? rashiAtNextSunrise : null;
+  let nextDaySankrantiRashi = null;
+  try {
+    const tomorrowSunsetUtc = computeSunset(nextSunriseUtc, location);
+    const dayAfterSunriseUtc = computeSunrise(tomorrowSunsetUtc, location);
+    const rashiAtDayAfterSunrise = Math.floor(getSun(dayAfterSunriseUtc) / 30) % 12;
+    if (rashiAtNextSunrise !== rashiAtDayAfterSunrise) {
+      nextDaySankrantiRashi = rashiAtDayAfterSunrise;
+    }
+  } catch (e) {
+    if (!(e instanceof PanchangError && (e.code === "NO_SUNRISE" || e.code === "NO_SUNSET"))) {
+      throw e;
+    }
+  }
+  const rashiAtYesterdaySunrise = Math.floor(getSun(yesterdaySunriseUtc) / 30) % 12;
+  const prevDaySankrantiRashi = rashiAtYesterdaySunrise !== rashiAtSunrise ? rashiAtSunrise : null;
   let ekadashiDashamiViddha = false;
   if (tithiAtSunrise.index === 10 || tithiAtSunrise.index === 25) {
     const tithiAtArunodaya = tithiAt(arunodayaUtc);
@@ -5060,6 +5328,8 @@ function getDailyPanchang(date, location, options) {
       priorDayTithiByRule,
       nakshatraIndicesInDay,
       sankrantiRashi,
+      nextDaySankrantiRashi,
+      prevDaySankrantiRashi,
       ekadashiDashamiViddha,
       smartaDwadashiToday,
       moonriseInDay: moonriseInDayUtc,
@@ -5068,7 +5338,7 @@ function getDailyPanchang(date, location, options) {
         end: utcToLocalDisplay(bhadraUtc.end, offsetMinutes)
       } : null,
       formatClock,
-      region: options.region ?? "all"
+      region: resolveRegionAlias(options.region)
     },
     (key) => t.festivalNames[key] ?? t.misc[key] ?? key,
     (idx) => resolveMasaName(idx, lang)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "panchang-ts",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Pure TypeScript Hindu Panchang calculations. Tithi, Nakshatra, Yoga, Karana, Vara, and more. Offline-first, React Native compatible.",
   "author": "Ishank",
   "license": "MIT",