panchang-ts 4.3.1 → 5.0.1

package/README.md

@@ -1,11 +1,17 @@
 # panchang-ts
 
 [![npm version](https://img.shields.io/npm/v/panchang-ts)](https://www.npmjs.com/package/panchang-ts)
+[![license](https://img.shields.io/npm/l/panchang-ts)](./LICENSE)
 
 Pure TypeScript Hindu Panchang (almanac), Jyotish, and Birth Chart calculations.
-Zero native dependencies. Works offline in React Native (Hermes), Node.js, and browsers.
+Zero runtime dependencies. Works offline in React Native (Hermes), Node.js, and browsers.
 
-**Fast** (~0.1 ms names-only, ~0.5 ms full) · **Typed** (full TypeScript) · **Offline** (pure JS math) · **8,164 tests across 100 files**
+**Fast** (~0.25 ms trimmed, ~0.41 ms full) · **Typed** (full TypeScript) · **Offline** (pure JS math) · **8,368 tests across 121 files**
+
+> 📖 **Full documentation: [dharmagya.app/docs/panchang-ts](https://dharmagya.app/docs/panchang-ts)**
+> This README covers install, quick start, and the 4.x → 5 migration in full, plus a per-feature
+> quick reference. The complete reference — every option, result field, table format, accuracy
+> bound and performance note — lives on the docs site.
 
 ---
 
@@ -31,26 +37,84 @@ const result = getDailyPanchang(
 // → 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
+console.log(result!.angas.tithis[0].name);          // "Krishna Chaturdashi"
+console.log(result!.angas.nakshatras[0].name);      // "Mrigashira"
+console.log(result!.angas.vara.name);               // "Mangalawara"
+console.log(result!.calendar.chandramasa.name);        // "Magha"
+console.log(result!.calendar.samvat.vikramSamvat);     // 2081
 ```
 
 ### Reading Output Times
 
-All `Date` objects are **offset-adjusted** to the requested timezone. Read time
-components via `getUTC*` — `.getHours()` would use your system zone:
+Every `Date` in a result is a **real instant** — `.getTime()` is the correct
+epoch millisecond. Every instant has a `*Local` companion: an offset-carrying
+ISO 8601 string, which is what you want for display.
+
+```typescript
+result!.sun.rise;            // Date — 2025-01-14T01:39:44.172Z (the actual moment)
+result!.sun.riseLocal;       // "2025-01-14T07:09:44.172+05:30"
+result!.inauspicious.rahuKalam.start;    // Date
+result!.inauspicious.rahuKalam.startLocal;
+
+// Just the wall clock:
+result!.sun.riseLocal.slice(11, 16);   // "07:09"
+
+// Anything else works too, because the Date is genuinely correct:
+new Intl.DateTimeFormat('en-IN', { timeZone: 'Asia/Kolkata', timeStyle: 'short' })
+  .format(result!.sun.rise);           // "7:09 am"
+Temporal.Instant.from(result!.sun.riseLocal);
+```
+
+For an instant you derive yourself, `formatInZone` renders it the same way:
 
 ```typescript
-const sunrise = result!.sunrise;
-const h = sunrise.getUTCHours();    // 7
-const m = sunrise.getUTCMinutes();  // 4 → 07:04 local time
+import { formatInZone } from 'panchang-ts';
+const noon = new Date((result!.sun.rise.getTime() + result!.sun.set.getTime()) / 2);
+formatInZone(noon, result!.timezone.offsetMinutes);  // "2025-01-14T12:27:31.086+05:30"
 ```
 
-`moonrise` / `moonset` can be `null` — the Moon occasionally does not rise or
-set on a given calendar day, which is normal.
+> **Changed in v5 — this is the breaking change most likely to affect you.**
+> Through 4.x every published `Date` was the true instant *shifted* by the UTC
+> offset, and the README told you to read it back with `getUTC*`. That worked
+> only as long as you did nothing else with the value: `JSON.stringify` emitted
+> a wrong instant labelled `Z`, `Intl` with a `timeZone` rendered 12:39 pm for
+> an 07:09 am sunrise, and any comparison, diff, database write, date-fns or
+> Temporal call was off by the offset.
+>
+> Migration is mechanical: `x.getUTCHours()` → read `xLocal`, or format the
+> instant. See [Upgrading from 4.x](#upgrading-from-4x).
+
+`moon.rise` / `moon.set` can be `null` — the Moon occasionally does not rise or
+set on a given calendar day, which is normal. `moon.riseLocal` / `moon.setLocal`
+are `null` exactly when they are.
+
+### The result is grouped
+
+`DailyPanchangResult` has seven groups plus a handful of top-level fields.
+Through 4.x it was ~50 flat fields; the groups are what tell you where to look.
+
+| Group | Holds |
+|---|---|
+| `sun` | `rise` / `set` / `nextRise` (+ `*Local`), day and night lengths, the Sun's `siderealLongitude` and `nakshatra` |
+| `moon` | `rise` / `set` (+ `*Local`), the Moon's `siderealLongitude` and `rashi` |
+| `angas` | the five limbs — `tithis`, `nakshatras`, `yogas`, `karanas`, `vara` |
+| `calendar` | `masa` (solar), `chandramasa` (lunar), `samvat` |
+| `muhurtas` | `abhijit`, `brahma`, `vijaya`, `godhuli`, `nishita`, `amritKala`, `madhyahna`, `pratahSandhya`, `sayahnaSandhya`, `doGhati` |
+| `inauspicious` | `rahuKalam`, `gulikaKalam`, `yamaganda`, `durMuhurta`, `varjyam`, `bhadra`, `gandaMula`, `panchaka`, `panchakaInfo`, `panchakaRahita` |
+| `periods` | `choghadiya`, `hora`, `gowri` |
+
+Top level: `date`, `location`, `timezone`, `ayanamsa`, `specialYogas`,
+`anandadiYoga`, `festivals`, `eclipse`, `chandraBalam`, `tarabala`.
+
+**Nothing is optional.** Every field is always present. A value that does not
+apply is `null`; a collection that does not apply is `[]`. That holds whether
+the reason is the domain (no Bhadra window today) or your options (you did not
+pass `janmaRashi`, so `chandraBalam` is `null`) — the result *shape* never
+depends on what you passed.
+
+`getInstantPanchang` uses the same group names for the subset an instant can
+answer: `sun`, `moon`, `angas`, `calendar`, `inauspicious`. There is no
+`muhurtas` or `periods`, because those are properties of a Hindu *day*.
 
 ### `getDailyPanchang` vs `getInstantPanchang`
 
@@ -66,6 +130,327 @@ Ekadashi split. For reliable festival dating, use `getDailyPanchang`.
 
 ---
 
+## Upgrading from 4.x
+
+Three changes move numbers that 4.x produced, and one option is gone.
+
+### Lahiri ayanamsa corrected by +38″
+
+The library's Lahiri constant sat 38 arcseconds behind DrikPanchang's — it used
+`23.853211°` at J2000 (the widely-repeated 23° 51′ 11.6″ figure) where Drik
+computes `23.863801°`. The replacement was solved from Drik's own published
+values across 1950–2050, which agree on it to within 0.01″ — a century-wide
+baseline, so the precession polynomial is pinned too, not just the epoch
+constant. Every sidereal output moves with it:
+
+| Output | Effect |
+|---|---|
+| Nakshatra end-times | ~69 s later than 4.x (carries the ayanamsa once) |
+| Yoga end-times | ~129 s later than 4.x (carries it twice) |
+| Planetary longitudes, rashi, pada, lagna, divisionals, dashas | shifted +0.0106° |
+| Tithi / karana end-times | unchanged — Moon − Sun cancels the ayanamsa |
+| Raman / KP / True Chitra / Thirukanitham | moved by the same +38″; their offsets from Lahiri are preserved |
+
+Worst-case end-time drift vs Drik dropped from 131 s to 60 s, and the sign split
+by ayanamsa exposure — nakshatra and yoga early, tithi and karana late — is gone.
+If you have snapshot tests or cached charts from 4.x, expect them to need
+re-pinning.
+
+### ΔT now uses measurement, so every published time moves ~6 s
+
+4.x took ΔT (TT − UT) entirely from Espenak–Meeus. Its post-2005 branches are an
+extrapolation published in 2006, and Earth's rotation did not follow it — by
+2026 the model reads about **5.9 s high**, drifting a further ~0.6 s each year.
+Because this library reports *times*, that lands directly on published values.
+
+v5 takes ΔT from the leap-second chain (`32.184 + (TAI − UTC)`, exact, and
+within the 0.9 s band leap seconds maintain) wherever ΔT has actually been
+measured, and resumes Espenak–Meeus beyond it carrying the offset it had
+accrued. Against JPL Horizons the measured era now agrees to **0.005 s** at
+every decade from 1980, where 4.x was seconds out.
+
+| Output | Effect |
+|---|---|
+| Tithi / nakshatra / yoga / karana end-times | ~5.7 s later for 2025 dates, growing with the model's drift |
+| Sankranti and other transit instants | same shift — it is one uniform correction, not per-element |
+| Sunrise / sunset / moonrise / moonset | barely moved — the error scales against the 15°/hr sky rotation |
+| Dates a panchang element is *filed under* | unchanged except where a transit sits within seconds of sunrise |
+
+That last row is the one to know about. `computeSankrantisForYear` publishes a
+date, and the date is decided by whether the transit precedes sunrise. The 2025
+Tula Sankranti at Reykjavik is such a case: it still falls on Oct 16, but its
+margin narrowed from 7.1 s to 1.4 s. Locations at high latitude with a transit
+near sunrise are where a day could flip.
+
+### Instant-mode vara was wrong after ~19:00
+
+`getInstantPanchang` located sunrise by searching forward from `date − 12 h`.
+For an evening instant that start point is already past the morning's sunrise,
+so it found *tomorrow's* and rolled the weekday back a day. Any query after
+roughly 7 pm returned the previous vara — and with it the wrong Rahu Kalam,
+Gulika Kalam, Yamaganda, Choghadiya, Hora, Anandadi yoga and special yogas.
+`getDailyPanchang` was never affected. If you cached instant-mode results from
+4.x for evening timestamps, discard them.
+
+### `precision` removed
+
+`precision: 'standard' | 'high'` and the `Precision` type no longer exist.
+Element transitions are now solved by secant iteration, which converges to the
+root rather than stopping at a fixed tolerance, so there is nothing left for the
+option to select — and the tighter setting no longer buys anything. Removing it
+from your options object is the whole migration; leaving it in is a type error,
+not a silent no-op.
+
+### Sunrise is single-valued per location-day
+
+Solar rise/set is computed from a canonical anchor and cached per location-day,
+so it no longer depends on which instant the caller happened to start searching
+from. Values shift by ≤108 ms vs 4.x, and two calls for the same day now agree
+exactly instead of differing by up to 109 ms. Windows derived proportionally
+from the day length — Varjyam, Bhadra, the slot systems — move by a little more
+than that. This removes an inconsistency rather than introducing an
+approximation: 4.x returned a different sunrise depending on which caller asked.
+
+### Moonrise and moonset are single-valued per location-day
+
+The same treatment sunrise received, now applied to the Moon. `getMoonrise` /
+`getMoonset` resolve through a canonical per-UTC-day cache, so an event has one
+timestamp no matter which caller asks or from which instant they searched.
+Published `moon.rise` / `moon.set` shift by **≤182 ms** vs 4.x. Nothing else in the
+result moves — verified over 11,520 daily results across six locations and three
+centuries: zero changes to any index, name, boolean, festival date or other
+timestamp.
+
+### `read*` for tables, `compute*` for the engine
+
+`getFestivalsForYear` read a pre-built table; `getFestivalsInRange` ran the
+engine. Two near-identical names, completely different inputs and semantics. v5
+settles one convention across all four families — festivals, eclipses, moon
+phases and muhurta:
+
+| 4.x | v5 | what it does |
+|---|---|---|
+| `getFestivalsForYear` | `readFestivalsForYear` | reads a table |
+| `getFestivalsForDate` | `readFestivalsForDate` | reads a table |
+| `getFestivalsYearRange` | `readFestivalsYearRange` | reads a table |
+| `getEclipsesForYear` / `ForDate` / `YearRange` | `readEclipsesForYear` / … | reads a table |
+| `getMoonPhasesForYear` / `ForDate` / `YearRange` | `readMoonPhasesForYear` / … | reads a table |
+| — | `readMuhurtaForYear` / `ForDate` / `YearRange` | **new** — reads a table |
+| — | `readBestMuhurtaDays` | **new** — top-scoring days |
+| `getFestivalsInRange` | `computeFestivalsInRange` | runs the engine |
+| `getEclipsesInRange` | `computeEclipsesInRange` | runs the engine |
+| `getMoonPhasesInRange` | `computeMoonPhasesInRange` | runs the engine |
+| `findAuspiciousDates` | `computeAuspiciousDatesInRange` | runs the engine |
+| `getEkadashiDatesForYear` | `computeEkadashiDatesForYear` | runs the engine |
+| `getSankrantisForYear` | `computeSankrantisForYear` | runs the engine |
+
+**Every 4.x name still works** — they are deprecated aliases pointing at the same
+functions, kept through v5. Nothing breaks today; the old names will go in v6.
+
+New single-year entry points, the shape most callers reach for first:
+
+```ts
+computeFestivalsForYear(2027, location, { timezone: 330 });
+computeEclipsesForYear(2027, location, { timezone: 330 });
+computeMoonPhasesForYear(2027, { timezone: 330 });
+computeAuspiciousDatesForYear(2027, vivahRule, location, { timezone: 330 });
+```
+
+### `buildMuhurtaTable` + the `panchang-ts/muhurta` subpath
+
+Festivals, eclipses and moon phases each had a builder and an engine-free
+reader; muhurta had neither, so finding auspicious dates meant running the full
+engine on device for every query. v5 completes the family:
+
+```ts
+// build once (build time, or first launch), then persist the JSON
+import { buildMuhurtaTable, vivahRule } from 'panchang-ts';
+const table = buildMuhurtaTable({
+  rule: vivahRule, location: DELHI, timezoneOffsetMinutes: 330,
+  startYear: 2026, endYear: 2031,
+});
+
+// read it back with no astronomy code in the bundle (~1.7 KB)
+import { readBestMuhurtaDays } from 'panchang-ts/muhurta';
+readBestMuhurtaDays(table, 5);   // top 5 days, highest score first
+```
+
+Only days that pass the rule are stored unless you pass `includeFailures: true`.
+
+### Built tables are dictionary-encoded and carry `key`
+
+`build*Table` now emits a `_dict` of unique entries with each day holding
+indices, rather than repeating every localized string at every occurrence. A
+10-year festival table goes from 315 KB to **89.9 KB (28.5%)**; a 10-year
+moon-phase table from 106 KB to **29.7 KB (28.0%)**. Resolved output is
+identical — verified across every year and both locales.
+
+Gzip already hid most of this on the wire, so the win is **parse time and
+resident memory**, which is the constraint that actually bites on Hermes.
+
+Festival table entries also gained the stable `key` the engine has been
+returning since 4.x, so a table is no longer both larger *and* less useful than
+engine output.
+
+**Tables you already cached still read.** The reader detects the format, so a v1
+table built with 4.x keeps working; only `key` is unavailable from it, and comes
+back as `''`.
+
+### Published `Date`s are real instants — the flagship change
+
+```diff
+- result.sunrise.getTime()      // NOT when sunrise happened (off by the UTC offset)
+- result.sunrise.getUTCHours()  // the documented 4.x idiom
++ result.sun.rise.getTime()     // correct epoch ms
++ result.sun.riseLocal          // "2025-01-14T07:09:44.172+05:30"
+```
+
+Applies to **every** `Date` in `DailyPanchangResult` and to every `TimePeriod` —
+`sun.rise`, `sun.set`, `sun.nextRise`, `moon.rise`, `moon.set`, all the muhurtas
+and inauspicious periods, all four slot systems, the element
+`startTime`/`endTime` arrays, the eclipse contacts and sutak window. Each gains
+a `*Local` companion: `sun.riseLocal`, `inauspicious.rahuKalam.startLocal`,
+`angas.tithis[0].endTimeLocal`, and so on.
+
+| you had | you now write |
+|---|---|
+| `r.sun.rise.getUTCHours()` | `r.sun.riseLocal.slice(11, 13)` |
+| `` `${h}:${m}` `` from `getUTC*` | `r.sun.riseLocal.slice(11, 16)` |
+| `r.inauspicious.rahuKalam.start.getUTCHours()` | `r.inauspicious.rahuKalam.startLocal.slice(11, 13)` |
+| `r.angas.tithis[0].endTime` for display | `r.angas.tithis[0].endTimeLocal` |
+| a `Date` you derived yourself | `formatInZone(d, r.timezone.offsetMinutes)` |
+
+`getInstantPanchang` results carry **no** `*Local` fields: that call takes no
+timezone, so there is no zone to render a wall clock in.
+
+**Cost:** rendering the strings adds ~0.04 ms per daily panchang — invisible on
+a cold call and ~20% of a fully cached warm one. The release warms to
+**0.17 ms**, against published 4.3.1's **6.20 ms**.
+
+### `result.timezone` is now an object
+
+```diff
+- result.timezone            // 330
++ result.timezone            // { offsetMinutes: 330, zone: 'Asia/Kolkata' }
++ result.timezone.offsetMinutes
+```
+
+`options.timezone` has always accepted `number | string`, but the result carried
+only a number — so passing `'America/New_York'` produced a result that could not
+say which zone produced it. `zone` is present only when you passed a zone name.
+
+**The DST limit, now stated explicitly.** The offset is resolved **once per
+call** from a reference date, so a Hindu day containing a DST transition is
+computed at a single offset throughout. Correct for almost every day; on the one
+or two transition days a year, times after the jump are shifted by its size.
+4.x documented this as a blanket "DST resolves automatically", which was not the
+whole truth.
+
+### The result object is grouped
+
+`DailyPanchangResult` had ~50 flat top-level fields mixing five categories.
+v5 sorts them into seven groups — see [The result is grouped](#the-result-is-grouped)
+for the full table. This is a large break, and it lands in the same release as
+the `Date` change on purpose: migrating both at once is one pass over your read
+sites, not two.
+
+Every rename, in full:
+
+| 4.x | v5 |
+|---|---|
+| `sunrise` / `sunset` / `nextSunrise` | `sun.rise` / `sun.set` / `sun.nextRise` |
+| `sunriseLocal` / `sunsetLocal` / `nextSunriseLocal` | `sun.riseLocal` / `sun.setLocal` / `sun.nextRiseLocal` |
+| `dayDurationMinutes` / `nightDurationMinutes` | `sun.dayDurationMinutes` / `sun.nightDurationMinutes` |
+| `dinamanaMinutes` / `ratrimanaMinutes` | `sun.dinamanaMinutes` / `sun.ratrimanaMinutes` |
+| `siderealSunAtSunrise` | `sun.siderealLongitude` |
+| `suryaNakshatra` | `sun.nakshatra` |
+| `moonrise` / `moonset` | `moon.rise` / `moon.set` |
+| `moonriseLocal` / `moonsetLocal` | `moon.riseLocal` / `moon.setLocal` |
+| `siderealMoonAtSunrise` | `moon.siderealLongitude` |
+| `chandraRashi` | `moon.rashi` |
+| `tithis` / `nakshatras` / `yogas` / `karanas` / `vara` | `angas.*` (same names) |
+| `masa` / `chandramasa` / `samvat` | `calendar.*` (same names) |
+| `abhijitMuhurta` / `brahmaMuhurta` / `vijayaMuhurta` | `muhurtas.abhijit` / `muhurtas.brahma` / `muhurtas.vijaya` |
+| `godhuliMuhurta` / `nishitaMuhurta` | `muhurtas.godhuli` / `muhurtas.nishita` |
+| `amritKala` / `madhyahna` / `pratahSandhya` / `sayahnaSandhya` | `muhurtas.*` (same names) |
+| `doGhatiMuhurta` | `muhurtas.doGhati` |
+| `rahuKalam` / `gulikaKalam` / `yamaganda` / `durMuhurta` | `inauspicious.*` (same names) |
+| `varjyam` / `bhadra` / `gandaMula` / `panchaka` / `panchakaRahita` | `inauspicious.*` (same names) |
+| `choghadiya` / `hora` | `periods.choghadiya` / `periods.hora` |
+| `gowriPanchangam` | `periods.gowri` |
+| `eclipse.magnitude` (disc *area*) | `eclipse.obscuration` — same value; the new `eclipse.magnitude` is the *diameter* fraction catalogues publish, and is negative for a penumbral lunar eclipse |
+
+Unmoved: `date`, `location`, `timezone`, `ayanamsa`, `specialYogas`,
+`anandadiYoga`, `festivals`, `eclipse`, `chandraBalam`, `tarabala`.
+
+For `getInstantPanchang`: `tithi` / `nakshatra` / `yoga` / `karana` / `vara` →
+`angas.*`; `siderealSun` → `sun.siderealLongitude`; `siderealMoon` →
+`moon.siderealLongitude`; `suryaNakshatra` → `sun.nakshatra`; `chandraRashi` →
+`moon.rashi`; `chandramasa` / `samvat` → `calendar.*`; `panchaka` / `gandaMula`
+→ `inauspicious.*`.
+
+### One rule for "not applicable": always present, `null` or `[]`
+
+4.x used three conventions and you could not predict which you would get —
+`| null` for `bhadra` / `varjyam` / `eclipse`, `?`-optional for `chandraBalam` /
+`tarabala`, and an empty array for `panchakaRahita` / `festivals`. v5 has one
+rule: **every field is always present**, a value that does not apply is `null`,
+and a collection that does not apply is `[]`.
+
+```diff
+- if ('chandraBalam' in r) …        // 4.x: field absent without janmaRashi
+- r.chandraBalam!.house             // and the `!` was mandatory
++ if (r.chandraBalam !== null) …    // v5: always present, null when unasked
++ r.chandraBalam?.house
+```
+
+Only `chandraBalam` and `tarabala` changed behaviour; everything else already
+followed the rule. `toBeUndefined()`-style checks against them become
+`toBeNull()`.
+
+### `suryaNakshatra` is typed as a nakshatra, not a rashi
+
+Now published as `sun.nakshatra`. Its `index` has always been 0..26 (Ashwini …
+Revati). Its *type* said `RashiInfo`, documented "0 = Mesha … 11 = Meena", so
+anyone indexing a 12-element rashi array by it got silent garbage for two thirds
+of the year. The runtime value is unchanged; the type is now
+`NakshatraIndexInfo` and TypeScript will point at the misuse.
+
+### `_debug` removed
+
+`DailyPanchangResult._debug` was declared in the published type and written
+nowhere in the library. It never carried data. If you referenced it, it was
+always `undefined`.
+
+### Alias fields documented rather than removed
+
+`sun.dinamanaMinutes` / `sun.dayDurationMinutes` and `sun.ratrimanaMinutes` /
+`sun.nightDurationMinutes` are the same numbers under classical and English
+names. Both pairs stay — consumers use both vocabularies — and the types now say
+plainly that they are aliases, never independently computed.
+
+`calendar.chandramasa` keeps its casing beside `moon.rashi` and `sun.nakshatra`.
+Renaming it would break every consumer for a casing preference. The type now
+documents that `calendar.masa` is the **solar** month and `calendar.chandramasa`
+the **lunar** one, which was previously left to guesswork.
+
+### Additive, but worth knowing
+
+- `EclipseInfo` / `EclipseSubtype` are now exported. 4.x shipped
+  `getUpcomingLunarEclipse` and friends without the type they return.
+- `festivals[].key` — stable, language-independent festival id. Match on this,
+  never on `name`.
+- `bhadra.locationName` — localized display name; `bhadra.location` stays the
+  machine-readable key.
+- `MuhurtaScore.factors` — structured scoring inputs alongside English `reasons`.
+- `BirthChart.byPlanet` — the nine placements keyed by graha.
+- `eclipse.description` is now localized. Under `language: 'hi'` it was
+  previously emitted in English, including inside `festivals[].description`.
+- `sections` on `getDailyPanchang` — opt into a narrower, cheaper call. See
+  [Performance](#performance).
+
+---
+
 ## Features at a Glance
 
 | Category | Features |
@@ -104,991 +489,221 @@ Ekadashi split. For reliable festival dating, use `getDailyPanchang`.
 
 # Feature Reference
 
-Each daily field is also returned from `getDailyPanchang` if you prefer one call
-over per-feature helpers.
+A quick tour with runnable snippets. **Each section links to its full page on
+the docs site** — every option, field, and caveat lives there.
+
+## Pancha Anga & the daily result
 
-## Pancha Anga
+📖 [Daily Panchang →](https://dharmagya.app/docs/panchang-ts/daily-panchang)
 
 ```typescript
 const r = getDailyPanchang(date, location, { timezone: 330 })!;
 
-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"
+r.angas.tithis.forEach(t => console.log(t.name, t.paksha, t.endTime));
+r.angas.vara.name;                     // "Mangalawara"
+r.calendar.chandramasa.isAdhika;       // true during leap months
+r.muhurtas.brahma;                     // TimePeriod | null — and 9 more muhurtas
+r.inauspicious.rahuKalam;              // { start, end } — and 9 more windows
+r.periods.choghadiya.day[0].name;      // 16 Choghadiya + Gowri + 24 Hora slots
+r.anandadiYoga.name; r.specialYogas;   // Anandadi + Amrit/Sarvartha Siddhi, …
 
 // 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);
-```
-
-## Lunar & Solar Calendar
-
-```typescript
-const r = getDailyPanchang(date, loc, { timezone: 330, masaSystem: 'purnimanta' })!;
-
-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
-
-r.masa.name;                  // current solar month (Mesha … Meena)
-r.suryaNakshatra.name;        // Sun's nakshatra
-r.chandraRashi.name;          // Moon sign
-```
-
-## Sun, Moon & Muhurta
-
-```typescript
-import { getSunrise, getSunset, getMoonrise, getMoonset } from 'panchang-ts';
-
-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 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; 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.amritKala;         // nakshatra-specific window (null when nakshatra has none)
-```
-
-`pratahSandhya` / `sayahnaSandhya` width = `nightDuration / 10` (~62–81 min).
-
-## Inauspicious Periods
-
-```typescript
-const r = getDailyPanchang(date, loc, { timezone: 330 })!;
-
-r.rahuKalam;       // { start, end }
-r.gulikaKalam;
-r.yamaganda;
-r.durMuhurta;      // two ~48-min windows
-r.varjyam;         // { start, end } | 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
-```
-
-## Time-Slot Systems
-
-```typescript
-const r = getDailyPanchang(date, loc, { timezone: 330 })!;
-
-// 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));
-
-// 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)
-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 it pervades)
-r.panchakaRahita.forEach(slice => console.log(slice.start, slice.end));
-```
-
-## Special Yogas
-
-```typescript
-const r = getDailyPanchang(date, loc, { timezone: 330 })!;
-
-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);
-});
+console.log(i.angas.tithi.name, i.angas.nakshatra.name);
 ```
 
 ## Festivals (80+)
 
-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);
-});
-```
-
-### Regional scoping
-
-`region` scopes regional variants to one Indian state. Pan-Indian festivals
-emit regardless.
+📖 [Festivals →](https://dharmagya.app/docs/panchang-ts/festivals)
 
 ```typescript
-// 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). The
-legacy slugs `'tamil'`, `'bengal'`, `'north-india'` are still accepted and
-mapped internally.
-
-### Pre-computed table (bundled, India / IST)
+r.festivals.forEach(f => console.log(f.key, f.name, f.type, f.deferralDate));
+// `name` is localized, so match on `key` — never on `name`:
+const hasDiwali = r.festivals.some(f => f.key === 'diwali');
 
-If you want festival *dates* without running the engine, import the static
-table at `panchang-ts/festivals`. It bundles a rolling **2-years-past /
-5-years-future** window pre-computed against Varanasi (IST). Within India
-these dates are essentially universal.
+// Scope regional variants: 21 state slugs + 'nepal' + 'all' (default)
+getDailyPanchang(jan14, chennai, { timezone: 330, region: 'tamil-nadu' });
 
-```typescript
-import {
-  getFestivalsForYear,
-  getFestivalsForDate,
-  FESTIVALS_META,
-  FESTIVALS_YEAR_RANGE,
-} from 'panchang-ts/festivals';
-
-const yr = FESTIVALS_YEAR_RANGE.start;          // e.g. { start: 2024, end: 2031 }
-getFestivalsForYear(yr)!.length;                // ~150 festival days
-const diwali = getFestivalsForYear(yr)!
-  .find(d => d.festivals.some(f => f.name === 'Diwali'))!.date;
-getFestivalsForDate(diwali);                    // [Narak Chaturdashi, Diwali]
-getFestivalsForDate(diwali, 'hi');              // [नरक चतुर्दशी, दिवाली]
-FESTIVALS_META.referenceLocation;               // "Varanasi"
-FESTIVALS_META.languages;                       // ["en", "hi"]
-```
-
-This entry point is engine-free — it ships only the JSON + accessors, so
-importing it won't pull the calculation engine into your bundle. Both `en`
-and `hi` are bundled (names *and* descriptions); pass the locale as the
-second argument. Eclipses are excluded here (visibility is location-dependent)
-— they ship as their own bundled table at `panchang-ts/eclipses` (see
-[Eclipses](#eclipses)).
-
-### Festivals outside India — build a location table and cache it
-
-The bundled table is **IST-only**. Elsewhere (Europe, North America, rest
-of world) festival dates can shift by ±1 day, because canonical times
-(nishita / pradosha / chandrodaya …) are observer-dependent — and the shift
-tracks the timezone offset, not the "region", so a single per-continent
-table would mis-date boundary-day festivals.
-
-For an offline app serving users worldwide, the right pattern is
-**compute-once-then-cache for the user's actual location**. Build a
-location-specific table with `buildFestivalsTable` (from the main entry —
-it uses the engine), persist the returned JSON, then read it back through
-the same accessors via their `source` argument:
-
-```typescript
+// Pre-computed table: build once, cache the JSON, read engine-free.
 import { buildFestivalsTable } from 'panchang-ts';
-import { getFestivalsForYear, getFestivalsForDate } from 'panchang-ts/festivals';
-
-// On first use at the user's location (a few seconds on-device — run it in
-// the background / chunk by year), then cache `table` to disk/MMKV.
-const table = buildFestivalsTable({
-  location: { latitude: 40.7128, longitude: -74.006 },
-  timezoneOffsetMinutes: -300,   // US Eastern (EST); 0 = UK, 330 = IST
-  startYear: 2024,
-  endYear: 2031,
-  languages: ['en'],             // omit hi to halve the size
-});
-
-// Later reads are instant lookups against the cached table:
-getFestivalsForYear(2026, 'en', table);
-getFestivalsForDate('2026-11-08', 'en', table);  // key is in the table's tz
+import { readFestivalsForYear, readFestivalsForDate } from 'panchang-ts/festivals';
 ```
 
-`buildFestivalsTable` returns the same `FestivalsFile` shape as the bundled
-data, so a cached table and the bundled India table are interchangeable as
-the `source` argument. India-majority apps can lean on the bundled table for
-zero first-load latency and only compute-and-cache for non-IST users.
+No table ships with the package — festival dates are observer-dependent, so you
+build one for your users' location and years (`npm run festivals:gen` is a
+worked example).
 
-**Other notes:** Karva Chauth / Dhanteras / Diwali emit with Purnimanta
-paksha naming. To regenerate the bundled India table after a registry
-change, run `npm run festivals:gen` (rolling window, no constants to edit).
+## Eclipses & Moon Phases
 
-## Eclipses
+📖 [Eclipses & Moon Phases →](https://dharmagya.app/docs/panchang-ts/eclipses-moon-phases)
 
 ```typescript
-const r = getDailyPanchang(date, loc, { timezone: 330 })!;
 if (r.eclipse) {
-  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.kind; r.eclipse.subtype;       // 'solar'|'lunar', 'partial'|'total'|…
+  r.eclipse.obscuration;                   // disc AREA covered, 0..1
+  r.eclipse.magnitude;                     // catalogue DIAMETER fraction
   r.eclipse.sutakStart; r.eclipse.sutakEnd;
-  // Sutak: 12 h (4 prahara) before solar, 9 h (3 prahara) before lunar
 }
 
-import { getUpcomingSolarEclipse, getUpcomingLunarEclipse } from 'panchang-ts';
-const next = getUpcomingSolarEclipse(new Date(), loc, 365 /* days */);
-```
-
-### Pre-computed table (bundled, India / IST)
-
-Like the festivals table, eclipse data ships as a static, engine-free entry
-at `panchang-ts/eclipses` — a rolling **2-years-past / 5-years-future** window
-pre-computed against Varanasi (IST). It lists every eclipse **visible from
-there during any phase** (so an eclipse already in progress at moon/sunrise or
-moon/sunset is included); the `visibleAtPeak` flag tells you whether greatest
-eclipse itself is observable. Within India visibility is essentially uniform.
+import { getUpcomingSolarEclipse, computeMoonPhasesInRange } from 'panchang-ts';
+getUpcomingSolarEclipse(new Date(), loc, 365);
+computeMoonPhasesInRange(start, end);      // precise new/quarter/full instants
 
-```typescript
-import {
-  getEclipsesForYear,
-  getEclipsesForDate,
-  ECLIPSES_META,
-  ECLIPSES_YEAR_RANGE,
-} from 'panchang-ts/eclipses';
-
-const e = getEclipsesForYear(2025)![0].eclipses[0];
-e.kind;                 // 'lunar'
-e.subtype;              // 'total'
-e.start; e.peak; e.end; // ISO UTC strings
-e.magnitude;            // 0..1 obscuration at peak
-e.visibleFromLocation;  // visible during any phase? (always true in bundled table)
-e.visibleAtPeak;        // is greatest eclipse itself above the horizon?
-e.sutak;                // { start, end } — see note below
-getEclipsesForDate('2025-09-07', 'hi');  // [पूर्ण चंद्र ग्रहण]
-ECLIPSES_META.referenceLocation;         // "Varanasi"
-```
-
-Each entry carries `en` + `hi` text. Solar eclipses report the subtype seen
-**locally** (a globally-total eclipse may read `partial` from Varanasi). The
-`sutak` window is present only where it applies — all visible solar eclipses
-and visible **umbral** (partial/total) lunar eclipses; **penumbral** lunar
-eclipses carry no `sutak` and are not religiously observed (drik / pandit
-consensus). For full astronomical detail (e.g. eclipses *not* visible in
-India), use `getUpcomingEclipses` / `getEclipsesInRange` from the main entry.
-
-**Outside India:** which eclipses are visible — and thus carry `sutak` —
-differs by location. Build and cache a location-specific table with
-`buildEclipsesTable` (main entry, uses the engine), then read it back via the
-same accessors' `source` argument — the same compute-once-then-cache pattern
-as festivals:
-
-```typescript
-import { buildEclipsesTable } from 'panchang-ts';
-import { getEclipsesForYear } from 'panchang-ts/eclipses';
-
-const table = buildEclipsesTable({
-  location: { latitude: 51.5074, longitude: -0.1278 },
-  timezoneOffsetMinutes: 0,        // UK / GMT
-  startYear: 2024,
-  endYear: 2031,
-  // visibleOnly: false → also include eclipses below the horizon (no sutak)
-});
-getEclipsesForYear(2025, 'en', table);
+// Engine-free tables: panchang-ts/eclipses and panchang-ts/moon-phases
 ```
 
-To regenerate the bundled India table, run `npm run eclipses:gen` (rolling
-window, no constants to edit).
-
-## Moon Phases
+## Muhurta Engine
 
-The four principal lunar phases — **new** (Amavasya), **first quarter**,
-**full** (Purnima), **last quarter** — as precise instants. (These are the
-astronomical quarter moments, distinct from the same-named *tithis*, which are
-~24h windows.)
+📖 [Muhurta Engine →](https://dharmagya.app/docs/panchang-ts/muhurta)
 
 ```typescript
-import { getMoonPhasesInRange } from 'panchang-ts';
-const phases = getMoonPhasesInRange(new Date('2026-01-01'), new Date('2026-12-31'));
-phases.forEach(p => console.log(p.phase, p.time.toISOString()));  // ~49 / year
-```
+import { scoreMuhurta, computeAuspiciousDatesInRange, vivahRule } from 'panchang-ts';
 
-### Pre-computed table (bundled, India / IST)
+const s = scoreMuhurta(new Date('2026-05-12'), DELHI, vivahRule, { timezone: 330 });
+s.score;            // 0..100; passes when ≥ 50
+s.factors;          // structured, stable codes — localize/filter on these
+s.reasons;          // diagnostic English
 
-Same engine-free pattern as festivals and eclipses, at `panchang-ts/moon-phases`
-— a rolling **2-years-past / 5-years-future** window. Phases are global
-instants; the bundled table maps each onto its **IST** calendar date (so a new
-moon at 19:52 UTC on Jan 18 is listed under Jan 19 in India).
-
-```typescript
-import {
-  getMoonPhasesForYear,
-  getMoonPhasesForDate,
-  MOON_PHASES_META,
-  MOON_PHASES_YEAR_RANGE,
-} from 'panchang-ts/moon-phases';
-
-getMoonPhasesForYear(2026)!.length;            // ~49 phase days
-getMoonPhasesForDate('2026-01-03');            // [{ phase: 'full', name: 'Full Moon', ... }]
-getMoonPhasesForDate('2026-01-03', 'hi');      // [{ phase: 'full', name: 'पूर्णिमा', ... }]
+computeAuspiciousDatesInRange(vivahRule, start, end, DELHI, { timezone: 330 });
 ```
 
-Each entry carries `phase`, the phase `time` (ISO UTC), and `en` + `hi` text.
-For another timezone, build and cache a table with `buildMoonPhasesTable` (main
-entry) and pass it as the accessors' `source` argument — it takes only a
-`timezoneOffsetMinutes` (no coordinates, since phases are location-independent):
+13 stock rules (vivah, griha pravesh, namakarana, …) or your own pure-data
+`MuhurtaRule`. Vara × Tithi yogas (Siddha, Amrita, Dagdha, …) are scored
+jointly. Pre-compute a table with `buildMuhurtaTable` and read it back through
+`panchang-ts/muhurta` (~1.7 KB, no astronomy code).
 
-```typescript
-import { buildMoonPhasesTable } from 'panchang-ts';
-import { getMoonPhasesForYear } from 'panchang-ts/moon-phases';
-
-const table = buildMoonPhasesTable({
-  timezoneOffsetMinutes: -300,   // US Eastern
-  startYear: 2024, endYear: 2031,
-});
-getMoonPhasesForYear(2026, 'en', table);
-```
+## Planetary Positions & Birth Charts
 
-Regenerate the bundled India table with `npm run moon-phases:gen`.
-
-## Planetary Positions
+📖 [Birth Charts →](https://dharmagya.app/docs/panchang-ts/birth-chart)
 
 ```typescript
-import { computePlanetaryPositions, GRAHA_ABBR } from 'panchang-ts';
+import {
+  computePlanetaryPositions, computeLagna, computeBhava,
+  computeRashiChart, computeNavamsa, computeDivisionalChart, computeDignity,
+} from 'panchang-ts';
 
 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 (sharper Rahu/Ketu via Meeus periodic correction)
-const gT = computePlanetaryPositions(new Date(), 'lahiri', undefined, 'true');
+g.jupiter.rashi.name; g.jupiter.nakshatra.pada; g.saturn.isRetrograde;
+
+const d1 = computeRashiChart(birth, loc);       // houseSystem: whole-sign | equal | placidus-kp
+d1.byPlanet.Mars.house;                          // keyed lookup, no linear scan
+const d9 = computeNavamsa(birth, loc);           // + D2/D3/D7/D10/D12/D30
+computeDignity('Mars', 9);                       // 'exalted'
 ```
 
-## Dashas
+## Dashas & Personal Transits
 
-Five classical systems:
+📖 [Dashas & Transits →](https://dharmagya.app/docs/panchang-ts/dashas)
 
 ```typescript
 import {
   computeVimshottariDashaFromBirth, computeVimshottariPratyantar,
-  computeAshtottariDasha, computeYoginiDasha, computeCharaDasha, computeNarayanDasha,
+  computeAshtottariDasha, computeYoginiDasha, computeCharaDasha,
+  computeNarayanDasha, computeSadeSati,
 } from 'panchang-ts';
 
-// 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]!);
-
-// 2. Ashtottari — 108-year, 8-lord cycle (no Ketu).
-const ash = computeAshtottariDasha(birth, moonLon);
-
-// 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'
-
-// 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)
+const vim = computeVimshottariDashaFromBirth(birth, 'lahiri');   // 3-level
+computeSadeSati(natalMoonRashiIndex, new Date());
+// Daily transits: pass janmaRashi / janmaNakshatra to getDailyPanchang
+// and read r.chandraBalam / r.tarabala.
 ```
 
-## Personal Transits
+## Strength, Yogas & Karakas
 
-```typescript
-const r = getDailyPanchang(date, loc, {
-  timezone: 330,
-  janmaRashi: 3,        // 0 = Mesha … 11 = Meena
-  janmaNakshatra: 0,    // 0 = Ashwini … 26 = Revati
-})!;
-r.chandraBalam!;  // { house, quality: 'strong'|'weak', name, englishName }
-r.tarabala!;      // { taraIndex, name, englishName, quality }
-
-import { computeSadeSati } from 'panchang-ts';
-const ss = computeSadeSati(natalMoonRashiIndex, new Date());
-// → { active, phase: 1|2|3|null, currentArcStart, currentArcEnd, nextArcStart }
-```
-
-## Birth Chart
-
-Sidereal Lagna, Bhava under three house systems, D1 + six classical divisional
-charts (D2/D3/D7/D9/D10/D12/D30), and Planetary Dignity.
+📖 [Strength, Yogas & Karakas →](https://dharmagya.app/docs/panchang-ts/strength-yogas)
 
 ```typescript
 import {
-  computeLagna, computeBhava, computeRashiChart, computeNavamsa,
-  computeDivisionalChart, computeDignity,
+  computeAspects, computeShadbala, computeBhavaBala,
+  computeAshtakavarga, computeYogas, computeJaiminiKarakas,
 } from 'panchang-ts';
 
-const birth = new Date('1995-08-15T05:30:00Z');
-const loc   = { latitude: 28.6139, longitude: 77.2090 };
-
-const lagna = computeLagna(birth, loc, 'lahiri', 'en');
-
-// Bhava — 'whole-sign' (default) | 'equal' | 'placidus-kp'.
-// Placidus-KP throws PanchangError('CIRCUMPOLAR') beyond ±66.5°.
-const houses = computeBhava(birth, loc, { houseSystem: 'whole-sign' });
-
-// 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;
-d1.planets.find(p => p.planet === 'Saturn')?.isRetrograde;
-
-// 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');
-
-// Planetary dignity (BPHS Ch.3-4).
-computeDignity('Mars', 0);   // 'moolatrikona' (Aries)
-computeDignity('Mars', 9);   // 'exalted' (Capricorn)
-computeDignity('Sun',  6);   // 'debilitated' (Libra)
+computeShadbala(birth, loc);                        // 6-fold, in Virupas
+computeAshtakavarga(d1, { reductions: true });      // Bhinna + Sarva + Sodhana
+computeYogas(d1);                                   // ~25 named, with bhanga
+computeJaiminiKarakas(d1, { variant: '8-jaimini' });
 ```
 
-Birth-chart helpers accept the full ayanamsa set including `'true-chitra'` and
-`'thirukanitham'`.
-
 ## Compatibility & Doshas
 
+📖 [Matching & Doshas →](https://dharmagya.app/docs/panchang-ts/matching-doshas)
+
 ```typescript
 import {
   computeAshtakoot, computePathuPorutham,
-  computeMangalDosha, computeKaalSarp, computePitruDosha,
+  computeMangalDosha, computeMangalCompatibility, computeKaalSarp, computePitruDosha,
 } from 'panchang-ts';
 
-// 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 },
-  { rashi: 0, nakshatra: 1 },
-);
+computeAshtakoot({ rashi: 4, nakshatra: 9 }, { rashi: 0, nakshatra: 1 });
 // → { totalScore: 0..36, koots: KootScore[8], cancellations: string[] }
 
-// 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);
-//   Pandit-consensus 4-trigger set (rules cited by ≥3 of 6 surveyed
-//   pandit sources): Sun+Rahu conjunction (any house), Sun+Saturn
-//   conjunction (any house), Rahu in 9th house, 9th-lord conjunct Rahu.
-//   Drik panchang publishes no Pitru calculator; minority/expansive
-//   rules (Sun in 9th alone, Ketu in 4th, 9th lord in dusthana, etc.)
-//   are intentionally excluded.
+computeMangalCompatibility(boyChart, girlChart);   // Manglik is a PAIRWISE verdict
+computeKaalSarp(d1);                               // 12 subtypes by Rahu's house
 ```
 
-**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.
+## Annual Charts, Sensitive Points, KP & Prashna
 
-## Strength & Aspects
-
-```typescript
-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);
-
-// 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;
-```
-
-Rahu and Ketu are not Ashtakavarga receivers or contributors (classical
-Parashara scheme).
-
-## Yogas & Karakas
-
-```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
+📖 [Annual Charts →](https://dharmagya.app/docs/panchang-ts/annual-charts) ·
+[KP & Prashna →](https://dharmagya.app/docs/panchang-ts/kp-prashna)
 
 ```typescript
 import {
   computeVarshaphala, computeTithiPravesha, computeArudhas,
   computeHoraLagna, computeGhatiLagna, computeBhavaLagna, computeSripatiLagna,
   computeUpagrahas, computeArgala,
-} from 'panchang-ts';
-
-// 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;
-```
-
-## KP & Prashna
-
-```typescript
-import {
   computeKpSubLord, computeKpCuspalSubLords, computeKpSignificators,
   computePrashnaChart,
 } from 'panchang-ts';
 
-// 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
-```
-
-Same return shape as a natal `BirthChart`. Pass `{ houseSystem: 'whole-sign' }`
-to `computePrashnaChart` for traditional Vedic Prashna.
-
-## Muhurta Engine
-
-```typescript
-import { scoreMuhurta, findAuspiciousDates, vivahRule } from 'panchang-ts';
-
-const r = scoreMuhurta(new Date('2026-05-12'), DELHI, vivahRule, { timezone: 330 });
-// → { date, score: 0..100, passes: boolean, reasons: string[] }
-
-const dates = findAuspiciousDates(
-  vivahRule,
-  new Date('2026-05-01'),
-  new Date('2026-05-31'),
-  DELHI,
-  { timezone: 330 },
-);   // MuhurtaDay[] sorted by score desc; full panchang attached
-
-// Custom rule (pure data, no engine code needed)
-const myRule: MuhurtaRule = {
-  occasion: 'launch_party',
-  auspiciousVaras: [3, 4, 5],
-  auspiciousNakshatras: [11, 12, 21],
-  excludeBhadra: true,
-  excludeEkadashi: true,
-  excludeAdhikaMasa: true,
-};
+const v = computeVarshaphala(birth, 30, loc);      // Tajik + Muntha + 27 Sahams
+computeTithiPravesha(birth, 30, loc);              // preserves natal tithi exactly
+computeKpSubLord(45.5).subLord;                    // 243 sub-divisions
+computePrashnaChart(questionTime, querentLoc);     // horary, Placidus-KP default
 ```
 
-13 stock rules: vivah, griha pravesh, namakarana, vidyarambh, vahan kharidi,
-annaprashan, mundan, upanayanam, karnavedha, aksharabhyasam, seemantham, shop
-opening, travel start.
-
-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.
-
 ## Calendar Conversion
 
+📖 [Calendar Conversion →](https://dharmagya.app/docs/panchang-ts/calendar-conversion)
+
 ```typescript
 import {
   convertGregorianToHindu, convertHinduToGregorian,
   getKaliYugaYear, getHinduNewYear,
-  getEkadashiDatesForYear, getSankrantisForYear,
-  getFestivalsInRange, getUpcomingEclipses, getEclipsesInRange,
+  computeEkadashiDatesForYear, computeSankrantisForYear,
 } from 'panchang-ts';
 
-// Gregorian → Hindu coords at sunrise
-const h = convertGregorianToHindu(new Date('2026-04-15'), DELHI, { timezone: 330 });
-
-// Hindu → Gregorian
-const dates = convertHinduToGregorian(
+convertHinduToGregorian(
   { vikramSamvat: 2083, masaIndex: 0, paksha: 'shukla', pakshaTithi: 9 },
   DELHI, { timezone: 330 },
-);   // → Rama Navami in VS 2083
-
-getKaliYugaYear(new Date('2026-04-01'));                       // 5127
-getHinduNewYear(2026, 'tamil-nadu', DELHI, { timezone: 330 }); // Puthandu
-
-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);
+);                                                  // → Date[] (Rama Navami VS 2083)
+getHinduNewYear(2026, 'tamil-nadu', DELHI, { timezone: 330 });  // region-aware
 ```
 
-`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.
-
 ## 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
-
-// All options:
-const r = getDailyPanchang(date, loc, {
-  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)
-  janmaRashi: undefined,                  // pass to add r.chandraBalam
-  janmaNakshatra: undefined,              // pass to add r.tarabala
-});
-```
-
-**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, Pancha Anga, Festivals</strong></summary>
-
-```typescript
-interface GeoLocation { latitude: number; longitude: number; elevation?: number; }
-interface TimePeriod  { start: Date; end: Date; }
-
-interface TithiInfo {
-  index: number;               // 0-29
-  name: string;
-  paksha: string;              // "Shukla"/"Krishna" (en), "शुक्ल"/"कृष्ण" (hi)
-  number: number;              // 1-15 within the paksha
-  completionPercentage: number;
-  endTime: Date | null;
-}
-// NakshatraInfo, YogaInfo, KaranaInfo follow the same pattern.
-// DailyTithiInfo extends with startTime + isActiveAtSunrise.
-
-interface VaraInfo {
-  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';
-  description?: string;
-  deferralDate?: Date;  // Smarta Ekadashi → Dwadashi fast date
-}
-
-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';
-
-// Legacy slugs accepted (mapped internally): 'tamil' → 'tamil-nadu',
-// 'bengal' → 'west-bengal', 'north-india' → 'all'.
-```
-
-</details>
-
-<details>
-<summary><strong>Eclipses & Bhadra</strong></summary>
+📖 [Options & Localization →](https://dharmagya.app/docs/panchang-ts/localization)
 
 ```typescript
-interface EclipseInfo {
-  kind: 'solar' | 'lunar';
-  subtype: 'partial' | 'total' | 'annular' | 'penumbral';
-  start: Date; peak: Date; end: Date;
-  visibleFromLocation: boolean;
-  magnitude: number;        // [0, 1] at peak
-  sutakStart: Date;         // 12 h pre-solar / 9 h pre-lunar
-  sutakEnd: Date;
-  description: string;
-}
-
-interface BhadraInfo {
-  start: Date; end: Date;
-  location: 'earth' | 'heaven' | 'paatal';   // 'earth' = malefic for all work
-  isActive: boolean;
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Jyotish</strong></summary>
-
-```typescript
-type GrahaName = 'Sun' | 'Moon' | 'Mars' | 'Mercury' | 'Jupiter'
-               | 'Venus' | 'Saturn' | 'Rahu' | 'Ketu';
-
-interface GrahaPosition {
-  planet: GrahaName;
-  siderealLongitude: number;
-  rashi: RashiInfo;
-  degreeInRashi: number;
-  nakshatra: NakshatraInfo;
-  isRetrograde: boolean;     // always false for Sun/Moon; always true for Rahu/Ketu
-}
-
-type DashaLord = 'Ketu' | 'Venus' | 'Sun' | 'Moon' | 'Mars'
-              | 'Rahu' | 'Jupiter' | 'Saturn' | 'Mercury';
-
-interface MahaDasha   { lord: DashaLord; startDate: Date; endDate: Date;
-                        years: number; antarDashas: AntarDasha[]; }
-interface VimshottariDashaResult {
-  currentMahaDashaLord: DashaLord;
-  currentIndex: number;
-  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;
-}
+const hi = getDailyPanchang(date, loc, { timezone: 330, language: 'hi' })!;
+hi.angas.tithis[0].name;       // "कृष्ण चतुर्दशी"
+hi.angas.vara.englishName;     // "Tuesday" — englishName always English
 
-interface TarabalaInfo {
-  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';
-}
+// All options: timezone (number | IANA string), ayanamsa (5), language (en|hi),
+// masaSystem (purnimanta|amanta), region, computeEndTimes, sections,
+// janmaRashi, janmaNakshatra.
 ```
 
-</details>
-
-<details>
-<summary><strong>Full export list</strong></summary>
+Machine-readable keys never change with language: match on `festival.key`,
+`bhadra.location`, `eclipse.kind`, `factors[].code` — render `name` /
+`locationName` / `description` / `reasons`.
 
-```typescript
-// Primary entry points
-getDailyPanchang, getInstantPanchang
-
-// Astronomy
-getSunrise, getSunset, getMoonrise, getMoonset
-getSiderealSunLongitude, getSiderealMoonLongitude, getAyanamsa
-
-// Inauspicious / Muhurta
-computeRahuKalam, computeGulikaKalam, computeYamaganda
-computeVarjyam, computeGandaMula, computeAnandadiYoga
-computePanchakaRahita, computeDoGhati, computeGowriPanchangam
-computeAbhijitMuhurta, computeBrahmaMuhurta, computeVijayaMuhurta
-computeGodhuliMuhurta, computeNishitaMuhurta, computeAmritKala
-computeMadhyahna, computePratahSandhya, computeSayahnaSandhya
-
-// Eclipses
-getUpcomingSolarEclipse, getUpcomingLunarEclipse, getEclipseDuringDay
-isEclipseVisibleAnyPhase
-
-// Moon phases (new / quarters / full as precise instants)
-getMoonPhasesInRange
-
-// Jyotish — planets, dashas, transits
-computePlanetaryPositions, GRAHA_ABBR
-computeVimshottariDasha, computeVimshottariDashaFromBirth, computeVimshottariPratyantar
-computeAshtottariDasha, computeYoginiDasha, computeCharaDasha, computeNarayanDasha
-computeChandraBalam, computeTarabala, computeSadeSati
-
-// Jyotish — chart
-computeLagna, computeBhava, computeRashiChart, computeNavamsa, computeDivisionalChart
-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
-vivahRule, grihaPraveshRule, namakaranaRule, vidyarambhRule, vahanKharidiRule
-annaprashanRule, mundanRule, upanayanamRule, karnavedhaRule
-aksharabhyasamRule, seemanthamRule, shopOpeningRule, travelStartRule
-
-// Calendar conversion + yearly listings
-convertGregorianToHindu, convertHinduToGregorian
-getKaliYugaYear, getHinduNewYear, computeSamvat
-getEkadashiDatesForYear, getSankrantisForYear, getFestivalsInRange
-getUpcomingEclipses, getEclipsesInRange
-
-// Static data tables (engine-using runtime builders; bundled JSON at
-// panchang-ts/festivals, panchang-ts/eclipses, panchang-ts/moon-phases)
-buildFestivalsTable, buildEclipsesTable, buildMoonPhasesTable
-
-// Errors
-PanchangError
-```
+## Types & Exports
 
-</details>
+📖 [Types & Exports →](https://dharmagya.app/docs/panchang-ts/types) — the key
+interfaces (`TithiInfo`, `FestivalInfo`, `EclipseInfo`, `GrahaPosition`, …) and
+the complete export list of the main entry and the four engine-free subpaths
+(`panchang-ts/festivals`, `/eclipses`, `/moon-phases`, `/muhurta`).
 
 ---
 
@@ -1103,14 +718,15 @@ Two-pass rendering pattern for smooth UI:
 import { getDailyPanchang } from 'panchang-ts';
 import { InteractionManager } from 'react-native';
 
-// Pass 1 — instant, names only (~0.1 ms Node, <100 ms Hermes)
+// Pass 1 — cheapest useful result: elements, slots, muhurtas (~0.25 ms).
 const fast = getDailyPanchang(date, location, {
   timezone: 330,
+  sections: [],
   computeEndTimes: false,
 });
 setState(fast);
 
-// Pass 2 — background, full with end-times (~0.5 ms Node, <500 ms Hermes)
+// Pass 2 — background, everything (~0.41 ms).
 InteractionManager.runAfterInteractions(() => {
   setState(getDailyPanchang(date, location, { timezone: 330 }));
 });
@@ -1120,7 +736,9 @@ InteractionManager.runAfterInteractions(() => {
 
 ## Accuracy
 
-8,164 tests across 100 files, including fixtures cross-verified against reference
+📖 [Full accuracy notes →](https://dharmagya.app/docs/panchang-ts/accuracy)
+
+8,368 tests across 121 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`).
@@ -1130,54 +748,68 @@ London, Sydney, Dubai, Singapore (diaspora fixtures cover DST on
 | 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 |
+| Tithi / Nakshatra / Yoga / Karana end-times | ≤60 s vs Drik across all 20 audited comparisons |
+| Ayanamsa (Lahiri) | Reproduces DrikPanchang's published value to ~0.01″ across 1950–2050 |
 | Planetary positions (Sun–Saturn) | ±0.02° sidereal |
-| Planetary positions (Rahu/Ketu, mean node) | ≤0.5° typical; ±2° tolerance |
-| Planetary positions (Rahu/Ketu, true node) | ≤0.6° typical (Meeus periodic correction) |
+| Planetary positions (Rahu/Ketu) | ≤0.5° mean node, ≤0.6° true node (typical) |
 | Lagna sidereal longitude | Cross-checked against Jagannath Hora reference charts |
 | D1 / D9 house placement | Exact match vs reference for 9-graha placement |
 | Ashtakoot total | ±1 point per pair across 30+ matched pairs |
 | 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 dating** uses tithi-at-sunrise; a few festivals have authorities on
+other rules (tithi-at-midnight for Janmashtami / Shivaratri / Diwali,
+madhyahna-vyapini for Ganesh Chaturthi edge years) where output can drift
+±1 day — the exact list is
+[documented](https://dharmagya.app/docs/panchang-ts/accuracy#festival-tradeoff).
 
-### Festival Detection — Documented Tradeoff
+**Detection conventions:** Aadal / Vidaal follow the classical Moon-from-Sun
+nakshatra-distance rule, not the Tamil-Vakya weekday rule. Varjyam emits the
+sunrise-anchored nakshatra's window only. Do Ghati does not rotate by weekday.
 
-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 rule | Affects |
-|---|---|
-| Tithi-at-midnight | Krishna Janmashtami, Maha Shivaratri, Diwali / Lakshmi Puja |
-| Madhyahna-vyapini | Ganesh Chaturthi (edge years), Akshaya Tritiya 2026 |
-| Kshaya-tithi handling | Ugadi 2026-03-19 (Pratipada is Kshaya) |
+## Performance
 
-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.
+📖 [Full performance notes →](https://dharmagya.app/docs/panchang-ts/performance)
 
----
+Measured at Pune, Apple M-series, Node — median of 11 processes. **Distinct
+days** is the calendar-scan cost; **same day repeated** is what a UI
+re-rendering one date sees. Last column is published 4.3.1, benchmarked beside
+this release.
 
-## Performance
+| `getDailyPanchang` call | Distinct days | Same day repeated | 4.3.1 (distinct) |
+|---|---|---|---|
+| Default (all sections + end-times) | **~0.41 ms** | **~0.17 ms** | ~6.06 ms |
+| `sections: []` + `computeEndTimes: false` | ~0.25 ms | ~0.14 ms | n/a |
+| `getInstantPanchang` | ~0.21 ms | ~0.10 ms | ~0.43 ms |
 
-| Mode | Node.js | Hermes (budget Android) |
-|---|---|---|
-| Names-only (`computeEndTimes: false`) | ~0.1 ms | <100 ms |
-| Full with end-times | ~0.5 ms | <500 ms |
+**A default day is ~15× cheaper than 4.3.1**, a repeated day ~37×. The levers:
+
+- **`sections`** — skip the optional ephemeris-backed blocks (`'festivals'`,
+  `'eclipse'`, `'moonTimes'`, `'lunarWindows'`). Narrowing is exactly
+  output-neutral: every field a narrowed call computes is identical to the full
+  call's; omitted sections sit at their documented `null` / `[]`.
+- **`computeEndTimes: false`** — drops the `endTime` transition searches;
+  ~5–10% — use it to drop fields you don't want, not to go faster.
 
-Birth-chart helpers are independent — calling them does not add work to
-`getDailyPanchang`.
+Range helpers narrow internally: `computeEkadashiDatesForYear` **~18 ms/year**
+(4.3.1: ~2,360), `computeFestivalsInRange` **~131 ms/year** (~2,180),
+`computeSankrantisForYear` **~3.3 ms/year** (~154). Solar rise/set events are
+cached process-wide (bounded, 20k entries), which also makes them
+single-valued.
+
+One deliberate regression: raw chart primitives (`computeRashiChart`,
+`computeNavamsa`) cost ~0.32 ms vs ~0.10 in 4.3.1 — the price of an
+order-of-magnitude accuracy gain against JPL DE441. `computeShadbala` /
+`computeBhavaBala` went the other way, ~2× faster.
 
 ---
 
 ## Error Handling
 
+📖 [Errors & Compatibility →](https://dharmagya.app/docs/panchang-ts/errors)
+
 ```typescript
 import { PanchangError } from 'panchang-ts';
 
@@ -1192,7 +824,7 @@ try {
 ```
 
 Error codes: `INVALID_DATE`, `INVALID_LATITUDE`, `INVALID_LONGITUDE`,
-`INVALID_ELEVATION`, `INVALID_TIMEZONE`, `INVALID_AYANAMSA`,
+`INVALID_ELEVATION`, `INVALID_TIMEZONE`, `INVALID_AYANAMSA`, `INVALID_INPUT`,
 `TIMEZONE_RESOLUTION_FAILED`, `NO_SUNRISE`, `NO_SUNSET`, `SEARCH_DIVERGED`,
 `CIRCUMPOLAR` (Placidus-KP houses above ±66.5°).
 
@@ -1209,18 +841,25 @@ for the Moon).
 
 | Environment | Support |
 |---|---|
-| Node.js 18+ | Supported |
+| Node.js ≥ 22 (per the package `engines` field) | Supported |
 | React Native (Hermes) | Supported (pass `timezone` as number) |
 | Expo (managed + bare) | Supported |
 | Browser (modern, ESM) | Supported |
 | Browser (legacy / IE) | Not supported |
 
+The build targets ES2020 (ESM + CJS, full `.d.ts`), has **zero runtime
+dependencies**, and is `sideEffects: false`.
+
 ---
 
 ## Acknowledgements
 
-[astronomy-engine](https://github.com/cosinekitty/astronomy) by Don Cross — the
-sole runtime dependency. MIT licensed.
+As of v5 the package has **no runtime dependencies** — the ephemeris, ΔT model
+and event searches are the library's own. Two projects still deserve credit:
+[astronomy-engine](https://github.com/cosinekitty/astronomy) by Don Cross (MIT),
+the runtime engine through 4.x and now the dev-time baseline the own ephemeris
+is tested against, and the algorithms of Jean Meeus's *Astronomical Algorithms*,
+which underpin the rise/set and node models.
 
 ## License