@typescriptify/sweph 1.0.0

package/src/SwissEph/UseCases/MeridianTransit.md

@@ -0,0 +1,279 @@
+# Meridian Transit
+
+A **meridian transit** (also called **culmination**) is the moment when a celestial body crosses the observer's **meridian** -- the imaginary north-south line passing through the zenith (the point directly overhead). At this moment, the body reaches its highest point in the sky for that day. This is called the **upper transit** or **upper culmination**.
+
+There is also a **lower transit** (or **lower culmination**), when the body crosses the meridian below the pole -- its lowest point. For most observers, this happens below the horizon and is not visible. But for circumpolar objects (objects that never set), the lower transit is visible and represents the object's closest approach to the horizon.
+
+Meridian transits are important in several contexts:
+
+- **Solar noon**: The Sun's upper transit defines **local apparent noon** -- the moment when the Sun is highest in the sky and shadows point due north (in the Northern Hemisphere) or due south (in the Southern Hemisphere). This is the basis of sundial time.
+- **Timekeeping**: Before atomic clocks, astronomical time was determined by observing the meridian transit of stars with a transit telescope.
+- **Observation planning**: Objects are best observed near their transit, when they are highest above the horizon and atmospheric effects (seeing, extinction) are minimized.
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN } from '../../constants';
+
+const swe = new SwissEph();
+
+// Find solar noon in New York on June 21, 2024
+const jd = SwissEph.julianDay(2024, 6, 21, 0);
+const nyc = { longitude: -74.006, latitude: 40.713 };
+
+const noon = swe.transit(jd, SE_SUN, nyc);
+
+const date = SwissEph.fromJulianDay(noon.jd);
+const h = Math.floor(date.hour);
+const m = Math.floor((date.hour - h) * 60);
+const s = Math.round(((date.hour - h) * 60 - m) * 60);
+console.log(`Solar noon: ${h}:${String(m).padStart(2,'0')}:${String(s).padStart(2,'0')} UT`);
+// New York is UTC-4 in summer (EDT), so add -4 to convert to local time
+
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### Solar noon vs clock noon
+
+Solar noon almost never occurs at exactly 12:00 clock time, even after accounting for time zones. The difference arises from two effects: your position within your time zone, and the equation of time.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN } from '../../constants';
+
+const swe = new SwissEph();
+
+const fmt = (jd: number, tzOffset: number) => {
+  const d = SwissEph.fromJulianDay(jd);
+  let hours = d.hour + tzOffset;
+  if (hours < 0) hours += 24;
+  if (hours >= 24) hours -= 24;
+  const h = Math.floor(hours);
+  const m = Math.floor((hours - h) * 60);
+  const s = Math.round(((hours - h) * 60 - m) * 60);
+  return `${h}:${String(m).padStart(2,'0')}:${String(s).padStart(2,'0')}`;
+};
+
+// Compare solar noon at different dates in New York (UTC-5 in winter, UTC-4 in summer)
+const nyc = { longitude: -74.006, latitude: 40.713 };
+
+const dates = [
+  { y: 2024, m: 2, d: 12, tz: -5, label: 'Feb 12 (EST)' }, // equation of time ~ -14 min
+  { y: 2024, m: 5, d: 14, tz: -4, label: 'May 14 (EDT)' }, // equation of time ~ +4 min
+  { y: 2024, m: 7, d: 26, tz: -4, label: 'Jul 26 (EDT)' }, // equation of time ~ -6 min
+  { y: 2024, m: 11, d: 3, tz: -5, label: 'Nov 3 (EST)'  }, // equation of time ~ +16 min
+];
+
+console.log('Solar noon in New York at different times of year:');
+for (const d of dates) {
+  const jd = SwissEph.julianDay(d.y, d.m, d.d, 0);
+  const noon = swe.transit(jd, SE_SUN, nyc);
+  console.log(`  ${d.label}: ${fmt(noon.jd, d.tz)} local time`);
+}
+// Solar noon varies by over 30 minutes across the year!
+
+swe.close();
+```
+
+### Lower transit (anti-transit)
+
+The lower transit is when the body crosses the meridian at its lowest point. For the Sun, this is approximately midnight (but not exactly, for the same reasons solar noon is not exactly 12:00).
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN } from '../../constants';
+
+const swe = new SwissEph();
+
+const jd = SwissEph.julianDay(2024, 6, 21, 0);
+const london = { longitude: -0.128, latitude: 51.507 };
+
+const upperTransit = swe.transit(jd, SE_SUN, london);
+const lowerTransit = swe.antiTransit(jd, SE_SUN, london);
+
+const fmt = (jd: number) => {
+  const d = SwissEph.fromJulianDay(jd);
+  const h = Math.floor(d.hour);
+  const m = Math.floor((d.hour - h) * 60);
+  return `${h}:${String(m).padStart(2,'0')} UT`;
+};
+
+console.log(`Sun upper transit (solar noon):     ${fmt(upperTransit.jd)}`);
+console.log(`Sun lower transit (solar midnight): ${fmt(lowerTransit.jd)}`);
+
+swe.close();
+```
+
+### Planet meridian transits
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_JUPITER, SE_SATURN, SE_MARS } from '../../constants';
+
+const swe = new SwissEph();
+
+const jd = SwissEph.julianDay(2024, 4, 15, 0);
+const geo = { longitude: -118.243, latitude: 34.052 }; // Los Angeles
+
+const fmt = (jd: number) => {
+  const d = SwissEph.fromJulianDay(jd);
+  const h = Math.floor(d.hour);
+  const m = Math.floor((d.hour - h) * 60);
+  return `${h}:${String(m).padStart(2,'0')} UT`;
+};
+
+const planets = [
+  { id: SE_JUPITER, name: 'Jupiter' },
+  { id: SE_SATURN,  name: 'Saturn' },
+  { id: SE_MARS,    name: 'Mars' },
+];
+
+console.log('Next planet meridian transits from Los Angeles:');
+for (const p of planets) {
+  const tr = swe.transit(jd, p.id, geo);
+  const date = SwissEph.fromJulianDay(tr.jd);
+  console.log(`  ${p.name.padEnd(8)} ${date.year}-${String(date.month).padStart(2,'0')}-${String(date.day).padStart(2,'0')} ${fmt(tr.jd)}`);
+}
+
+swe.close();
+```
+
+### Solar noon over a year (tracking the equation of time)
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN } from '../../constants';
+
+const swe = new SwissEph();
+
+// Observer at the center of the UTC+0 timezone (longitude 0)
+// Here, the deviation of solar noon from 12:00 UT is purely the equation of time
+const greenwich = { longitude: 0, latitude: 51.477 };
+
+console.log('Solar noon at Greenwich, 2024 (deviation from 12:00 UT):');
+for (let month = 1; month <= 12; month++) {
+  const jd = SwissEph.julianDay(2024, month, 15, 0);
+  const noon = swe.transit(jd, SE_SUN, greenwich);
+
+  const d = SwissEph.fromJulianDay(noon.jd);
+  const deviationMinutes = (d.hour - 12) * 60;
+
+  const sign = deviationMinutes >= 0 ? '+' : '-';
+  const abs = Math.abs(deviationMinutes);
+  const dm = Math.floor(abs);
+  const ds = Math.round((abs - dm) * 60);
+
+  const monthNames = ['','Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];
+  console.log(
+    `  ${monthNames[month]} 15: noon at ${Math.floor(d.hour)}:${String(Math.floor((d.hour % 1) * 60)).padStart(2,'0')} UT` +
+    `  (${sign}${dm}m ${ds}s from 12:00)`
+  );
+}
+// The deviation ranges from about -14 minutes (Feb) to +16 minutes (Nov)
+
+swe.close();
+```
+
+### Combining transit with azalt to find maximum altitude
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN } from '../../constants';
+
+const swe = new SwissEph();
+
+const jd = SwissEph.julianDay(2024, 6, 21, 0); // Summer solstice
+const geo = { longitude: -0.128, latitude: 51.507 }; // London
+
+// Find solar noon
+const noon = swe.transit(jd, SE_SUN, geo);
+
+// Get the Sun's position at transit
+const sun = swe.calc(noon.jd, SE_SUN);
+
+// Convert to azimuth/altitude
+const hor = swe.azalt(noon.jd, geo, sun.longitude, sun.latitude, sun.distance);
+
+console.log(`Sun at solar noon (London, summer solstice):`);
+console.log(`  Altitude: ${hor.trueAltitude.toFixed(2)} degrees`);
+console.log(`  Azimuth:  ${hor.azimuth.toFixed(2)} degrees`);
+// The Sun reaches about 62 degrees altitude at London on the summer solstice
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### The meridian
+
+The **celestial meridian** is the great circle on the celestial sphere that passes through the celestial poles and the observer's zenith. It divides the sky into an eastern half and a western half.
+
+When a body crosses the meridian going from east to west (the normal direction due to Earth's rotation), it is at its highest point. This is the **upper transit**. About 12 hours later (for the Sun; for stars it is the sidereal day), it crosses the meridian again at its lowest point -- the **lower transit**. For bodies that are circumpolar (always above the horizon), both transits are observable.
+
+### Local apparent noon vs clock noon
+
+**Local apparent noon** is the moment when the Sun crosses the observer's meridian. It differs from 12:00 clock time for two reasons:
+
+1. **Longitude within time zone**: Time zones are typically 15 degrees wide (1 hour). If you are at the eastern edge of your time zone, the Sun reaches your meridian earlier than for someone at the western edge. For example, within the US Eastern time zone, Detroit (lon -83.0) sees solar noon about 25 minutes later than New York (lon -74.0).
+
+2. **The equation of time**: Even at the center of a time zone, solar noon drifts back and forth throughout the year by up to 16 minutes. This is called the **equation of time**.
+
+### The equation of time
+
+The equation of time is the difference between **apparent solar time** (based on the actual Sun's position) and **mean solar time** (based on a fictitious Sun that moves at a constant rate). It arises from two physical effects:
+
+1. **Orbital eccentricity**: Earth's orbit is slightly elliptical (eccentricity ~0.017). According to Kepler's second law, Earth moves faster when closer to the Sun (perihelion, around January 3) and slower when farther (aphelion, around July 4). This means the angular speed of the Sun along the ecliptic varies.
+
+2. **Obliquity of the ecliptic**: The Earth's rotational axis is tilted 23.4 degrees from the orbital plane. Even if the Sun moved at a constant speed along the ecliptic, its projection onto the celestial equator (which determines the time between successive meridian crossings) would vary because the ecliptic and equator make an angle.
+
+The two effects combine to produce the equation of time, which follows an approximately sinusoidal curve:
+
+| Time of year | Equation of time | Solar noon compared to 12:00 |
+|-------------|-----------------|------------------------------|
+| Early February | about -14 minutes | Sun is slow; noon is at ~12:14 |
+| Mid-April | 0 (crossing) | Noon at ~12:00 |
+| Mid-May | about +4 minutes | Sun is fast; noon at ~11:56 |
+| Mid-June | 0 (crossing) | Noon at ~12:00 |
+| Late July | about -6 minutes | Sun is slow; noon at ~12:06 |
+| Early September | 0 (crossing) | Noon at ~12:00 |
+| Early November | about +16 minutes | Sun is fast; noon at ~11:44 |
+| Late December | 0 (crossing) | Noon at ~12:00 |
+
+The Swiss Ephemeris also provides `swe.timeEquation(jd)`, which returns the equation of time in days (multiply by 24 * 60 to get minutes).
+
+### Circumpolar transits
+
+At high latitudes, some celestial bodies are **circumpolar** -- they never set below the horizon. For these objects:
+
+- The **upper transit** is when the body is at its maximum altitude (crossing the meridian above the pole).
+- The **lower transit** is when the body is at its minimum altitude (crossing the meridian below the pole but still above the horizon).
+
+For example, Polaris (the North Star) is circumpolar from most of the Northern Hemisphere. Its lower transit passes very close to the celestial north pole.
+
+In the Arctic during summer, the Sun itself becomes circumpolar. Its upper transit (solar noon) still occurs at the highest altitude, but the lower transit (around midnight) also occurs above the horizon -- the midnight sun.
+
+### Transit vs rise/set
+
+| Property | Transit | Rise/Set |
+|----------|---------|----------|
+| **Definition** | Body crosses the meridian | Body crosses the horizon |
+| **Altitude** | Maximum (upper) or minimum (lower) | ~0 degrees (with refraction) |
+| **Always occurs?** | Yes (for all visible objects) | No (circumpolar objects never set; some objects never rise) |
+| **Affected by refraction?** | No (meridian crossing is a direction, not an altitude) | Yes (significantly) |
+| **Atmospheric pressure/temperature** | Not applicable | Affects the result through refraction |
+
+### Tips
+
+- The `transit()` and `antiTransit()` methods do not accept `pressure`, `temperature`, or `flags` like rise/set does, because meridian transit is a purely geometric event not affected by atmospheric refraction. However, they do accept the `options` parameter for API consistency.
+- To find "solar noon" for a given date, start from midnight UT of that date (hour = 0) and call `swe.transit()`. The result will be the Sun's meridian passage on that day.
+- The time between successive solar noons varies slightly throughout the year (from about 23h 59m 39s to 24h 0m 30s) due to the equation of time. The mean interval is exactly 24 hours.
+- For stars, the time between successive meridian transits is one sidereal day (23h 56m 4.1s), which is why stars appear to shift about 4 minutes earlier each night.

package/src/SwissEph/UseCases/MoonCrossings.md

@@ -0,0 +1,373 @@
+# Moon Crossings
+
+**Moon crossings** let you find the exact moment the Moon reaches a specific ecliptic longitude or crosses the ecliptic plane (a node crossing). The Moon moves much faster than the Sun -- about 13 degrees per day -- so it crosses any given longitude roughly once every 27.3 days (one sidereal month).
+
+This library provides two related functions:
+- **`moonCrossing(longitude, jd)`** -- finds when the Moon next reaches a specific ecliptic longitude
+- **`moonNodeCrossing(jd)`** -- finds when the Moon next crosses through the ecliptic plane (ascending or descending node)
+
+These are useful for:
+- Finding exact New Moon and Full Moon times
+- Tracking lunar transits to natal chart positions
+- Finding when the Moon enters each zodiac sign
+- Computing eclipse timing (eclipses occur near node crossings)
+- Understanding the lunar node cycle (important in both Western and Vedic astrology)
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN } from '../../constants';
+
+const swe = new SwissEph();
+const startJd = SwissEph.julianDay(2025, 3, 1, 0);
+
+// A Full Moon occurs when the Moon is opposite the Sun (Sun's longitude + 180°).
+// Step 1: Get the Sun's longitude
+const sun = swe.calc(startJd, SE_SUN);
+
+// Step 2: Find when the Moon reaches the opposite point
+const fullMoonLon = (sun.longitude + 180) % 360;
+const result = swe.moonCrossing(fullMoonLon, startJd);
+
+const d = SwissEph.fromJulianDay(result.jd);
+console.log(`Next Full Moon after Mar 1, 2025: JD ${result.jd.toFixed(6)}`);
+console.log(`Date: ${d.year}-${String(d.month).padStart(2,'0')}-${String(Math.floor(d.day)).padStart(2,'0')}`);
+
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### Finding the next New Moon and Full Moon
+
+A **New Moon** occurs when the Moon has the same ecliptic longitude as the Sun (conjunction). A **Full Moon** occurs when the Moon is at the Sun's longitude + 180 degrees (opposition).
+
+Note: For precise New/Full Moon timing, you should iteratively refine, because the Sun also moves during the time it takes the Moon to reach the target. Here is a simple approach:
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN } from '../../constants';
+
+const swe = new SwissEph();
+const startJd = SwissEph.julianDay(2025, 6, 1, 0);
+
+// --- Find the next New Moon ---
+// Iterative refinement: get Sun position, find Moon crossing, repeat
+let jd = startJd;
+for (let i = 0; i < 3; i++) {
+  const sun = swe.calc(jd, SE_SUN);
+  const result = swe.moonCrossing(sun.longitude, jd);
+  jd = result.jd;
+}
+const newMoon = SwissEph.fromJulianDay(jd);
+const nmHours = (newMoon.day % 1) * 24;
+console.log(
+  `New Moon: ${newMoon.year}-${String(newMoon.month).padStart(2,'0')}-` +
+  `${String(Math.floor(newMoon.day)).padStart(2,'0')} ` +
+  `${String(Math.floor(nmHours)).padStart(2,'0')}:${String(Math.floor((nmHours % 1) * 60)).padStart(2,'0')} UT`
+);
+
+// --- Find the next Full Moon ---
+jd = startJd;
+for (let i = 0; i < 3; i++) {
+  const sun = swe.calc(jd, SE_SUN);
+  const result = swe.moonCrossing((sun.longitude + 180) % 360, jd);
+  jd = result.jd;
+}
+const fullMoon = SwissEph.fromJulianDay(jd);
+const fmHours = (fullMoon.day % 1) * 24;
+console.log(
+  `Full Moon: ${fullMoon.year}-${String(fullMoon.month).padStart(2,'0')}-` +
+  `${String(Math.floor(fullMoon.day)).padStart(2,'0')} ` +
+  `${String(Math.floor(fmHours)).padStart(2,'0')}:${String(Math.floor((fmHours % 1) * 60)).padStart(2,'0')} UT`
+);
+
+swe.close();
+```
+
+### Finding when the Moon enters each zodiac sign
+
+The Moon changes signs roughly every 2.3 days. Here is how to find each sign ingress during a month:
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+let jd = SwissEph.julianDay(2025, 4, 1, 0);
+const endJd = SwissEph.julianDay(2025, 5, 1, 0);
+
+const signs = [
+  'Aries', 'Taurus', 'Gemini', 'Cancer',
+  'Leo', 'Virgo', 'Libra', 'Scorpio',
+  'Sagittarius', 'Capricorn', 'Aquarius', 'Pisces',
+];
+
+console.log('Moon sign ingresses for April 2025:');
+
+while (jd < endJd) {
+  // Find the Moon's current sign
+  const moon = swe.calc(jd, 1); // SE_MOON = 1
+  const currentSign = Math.floor(moon.longitude / 30);
+
+  // The next sign boundary
+  const nextSignLon = ((currentSign + 1) % 12) * 30;
+
+  const result = swe.moonCrossing(nextSignLon, jd);
+  if (result.jd >= endJd) break;
+
+  const d = SwissEph.fromJulianDay(result.jd);
+  const hours = (d.day % 1) * 24;
+  const h = Math.floor(hours);
+  const m = Math.floor((hours - h) * 60);
+  const signIndex = nextSignLon / 30;
+
+  console.log(
+    `  Moon enters ${signs[signIndex].padEnd(12)} ` +
+    `${d.year}-${String(d.month).padStart(2,'0')}-${String(Math.floor(d.day)).padStart(2,'0')} ` +
+    `${String(h).padStart(2,'0')}:${String(m).padStart(2,'0')} UT`
+  );
+
+  jd = result.jd + 0.1; // advance a bit past the crossing
+}
+
+swe.close();
+```
+
+### Finding lunar node crossings
+
+The Moon's orbit is tilted about 5.1 degrees relative to the ecliptic. It crosses the ecliptic plane twice per orbit -- once going north (ascending node) and once going south (descending node).
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+let jd = SwissEph.julianDay(2025, 1, 1, 0);
+const endJd = SwissEph.julianDay(2026, 1, 1, 0);
+
+console.log('Moon node crossings in 2025:');
+console.log('Date                Node         Longitude  Latitude');
+console.log('------------------  -----------  ---------  --------');
+
+let count = 0;
+while (jd < endJd && count < 30) {
+  const result = swe.moonNodeCrossing(jd);
+  if (result.jd >= endJd) break;
+
+  const d = SwissEph.fromJulianDay(result.jd);
+  const hours = (d.day % 1) * 24;
+  const h = Math.floor(hours);
+  const m = Math.floor((hours - h) * 60);
+
+  // Latitude near zero at node; sign tells us which node
+  // Ascending node: Moon crosses from south to north (latitude was negative, becomes positive)
+  // We can check by computing the Moon slightly after the crossing
+  const moonAfter = swe.calc(result.jd + 0.01, 1);
+  const nodeType = moonAfter.latitude > 0 ? 'Ascending ' : 'Descending';
+
+  console.log(
+    `${d.year}-${String(d.month).padStart(2,'0')}-${String(Math.floor(d.day)).padStart(2,'0')} ` +
+    `${String(h).padStart(2,'0')}:${String(m).padStart(2,'0')} UT  ` +
+    `${nodeType}  ` +
+    `${result.longitude.toFixed(3).padStart(8)}°  ` +
+    `${result.latitude.toFixed(5).padStart(8)}°`
+  );
+
+  jd = result.jd + 10; // Nodes are about 13.6 days apart
+  count++;
+}
+
+swe.close();
+```
+
+### Identifying potential eclipse seasons
+
+Eclipses occur when a New Moon or Full Moon happens close to a lunar node. By combining `moonCrossing()` and `moonNodeCrossing()`, you can identify these windows:
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN, SE_MOON, SE_TRUE_NODE } from '../../constants';
+
+const swe = new SwissEph();
+let jd = SwissEph.julianDay(2025, 1, 1, 0);
+const endJd = SwissEph.julianDay(2026, 1, 1, 0);
+
+console.log('Potential eclipse windows in 2025:');
+console.log('(New/Full Moons within 18° of a node)\n');
+
+// Find each New and Full Moon in the year
+while (jd < endJd) {
+  const sun = swe.calc(jd, SE_SUN);
+
+  // Find next New Moon (Moon at Sun's longitude)
+  const nm = swe.moonCrossing(sun.longitude, jd);
+  if (nm.jd >= endJd) break;
+
+  // Check distance from the True Node
+  const node = swe.calc(nm.jd, SE_TRUE_NODE);
+  const moon = swe.calc(nm.jd, SE_MOON);
+
+  // Angular distance from Moon to node (normalize to -180..180)
+  let distToNode = moon.longitude - node.longitude;
+  if (distToNode > 180) distToNode -= 360;
+  if (distToNode < -180) distToNode += 360;
+
+  if (Math.abs(distToNode) < 18) {
+    const d = SwissEph.fromJulianDay(nm.jd);
+    console.log(
+      `  NEW MOON ${d.year}-${String(d.month).padStart(2,'0')}-${String(Math.floor(d.day)).padStart(2,'0')}  ` +
+      `Moon ${moon.longitude.toFixed(1)}°  Node ${node.longitude.toFixed(1)}°  ` +
+      `dist ${Math.abs(distToNode).toFixed(1)}° → possible SOLAR eclipse`
+    );
+  }
+
+  // Check opposite point for Full Moon
+  const fm = swe.moonCrossing((sun.longitude + 180) % 360, nm.jd + 1);
+  if (fm.jd < endJd) {
+    const nodeFm = swe.calc(fm.jd, SE_TRUE_NODE);
+    const moonFm = swe.calc(fm.jd, SE_MOON);
+
+    let distFm = moonFm.longitude - nodeFm.longitude;
+    if (distFm > 180) distFm -= 360;
+    if (distFm < -180) distFm += 360;
+
+    if (Math.abs(distFm) < 18) {
+      const d2 = SwissEph.fromJulianDay(fm.jd);
+      console.log(
+        `  FULL MOON ${d2.year}-${String(d2.month).padStart(2,'0')}-${String(Math.floor(d2.day)).padStart(2,'0')}  ` +
+        `Moon ${moonFm.longitude.toFixed(1)}°  Node ${nodeFm.longitude.toFixed(1)}°  ` +
+        `dist ${Math.abs(distFm).toFixed(1)}° → possible LUNAR eclipse`
+      );
+    }
+  }
+
+  jd = nm.jd + 20; // advance past this lunation
+}
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### The Moon's Motion
+
+The Moon is the fastest-moving body in geocentric astronomy:
+- **Sidereal period** (one complete orbit relative to the stars): ~27.32 days
+- **Synodic period** (one New Moon to the next): ~29.53 days (longer because the Sun also moves)
+- **Average daily motion**: ~13.18 degrees per day (ranges from about 11.8 to 15.4)
+- **Sign change**: every ~2.3 days
+
+Because the Moon moves so fast, its crossings happen frequently. The Moon crosses every degree of the ecliptic roughly once a month.
+
+### New Moon and Full Moon Geometry
+
+```
+  New Moon (conjunction):
+
+    Sun ---- Moon ---- Earth
+    (Moon between Sun and Earth; same longitude)
+
+
+  Full Moon (opposition):
+
+    Sun ---- Earth ---- Moon
+    (Earth between Sun and Moon; longitude differs by 180°)
+```
+
+The Moon's synodic period (29.53 days) is the time between successive New Moons. This is the basis of lunar calendars used throughout history (Islamic, Hebrew, Chinese, Hindu).
+
+### Lunar Nodes
+
+The Moon's orbit is tilted about **5.145 degrees** relative to the ecliptic plane. The two points where the Moon's orbit intersects the ecliptic are called **nodes**:
+
+```
+                    Ecliptic plane
+    =====================================
+              /         \
+           Moon's      Moon's
+           orbit       orbit
+          (below)     (above)
+              \         /
+    =====================================
+         Descending   Ascending
+           Node        Node
+```
+
+- **Ascending Node** (North Node): where the Moon crosses from south to north of the ecliptic. Called **Rahu** in Vedic astrology, or the "Dragon's Head" in Western tradition.
+- **Descending Node** (South Node): where the Moon crosses from north to south. Called **Ketu** in Vedic astrology, or the "Dragon's Tail."
+
+The `moonNodeCrossing()` method finds the actual physical moment when the Moon passes through the ecliptic plane. It returns:
+- `jd`: the exact time
+- `longitude`: the ecliptic longitude where the crossing occurs
+- `latitude`: the Moon's latitude at the crossing (very close to 0, by definition)
+
+### The Nodal Cycle
+
+The lunar nodes are not fixed -- they move slowly **retrograde** (backward through the zodiac) at about 19.3 degrees per year, completing a full cycle in approximately **18.613 years** (the "Metonic-related" nodal period, or more precisely the **nodal regression period**).
+
+This 18.6-year cycle is important in:
+- **Eclipse prediction**: Eclipses repeat in patterns related to the nodal cycle (the Saros cycle of ~18 years, 11 days)
+- **Vedic astrology**: The nodes (Rahu/Ketu) are treated as shadow planets and are key factors in chart interpretation
+- **Western astrology**: The nodes indicate karmic direction (North Node = future growth, South Node = past patterns)
+
+### Eclipse Connection
+
+Eclipses occur when a New Moon (solar eclipse) or Full Moon (lunar eclipse) happens while the Moon is near a node:
+
+- **Solar eclipse**: New Moon within ~18 degrees of a node (the Sun and Moon are both near the node, so the Moon can block the Sun)
+- **Lunar eclipse**: Full Moon within ~12 degrees of a node (the Moon passes through Earth's shadow)
+
+There are two "eclipse seasons" per year, each about 34 days long, when the Sun is near enough to a node for eclipses to be possible. The eclipse seasons shift backward through the year by about 19 days per year due to the retrograde motion of the nodes.
+
+### Ascending vs. Descending Node
+
+To determine which type of node crossing occurred, check the Moon's latitude shortly after the crossing:
+- If latitude becomes **positive** (Moon moving north), it was an **ascending node** crossing
+- If latitude becomes **negative** (Moon moving south), it was a **descending node** crossing
+
+The `moonNodeCrossing()` method finds the **next** node crossing of either type. To find specifically the next ascending or descending node, compute the Moon's latitude slightly after the crossing as shown in the examples above.
+
+### Return Types
+
+```typescript
+// moonCrossing
+interface CrossingResult {
+  jd: number;  // Julian Day when the Moon reaches the target longitude
+}
+
+// moonNodeCrossing
+interface MoonNodeCrossingResult {
+  jd: number;        // Julian Day of the node crossing
+  longitude: number; // Ecliptic longitude at the crossing point (degrees)
+  latitude: number;  // Moon's latitude at crossing (very close to 0)
+}
+```
+
+### API Details
+
+**`moonCrossing(longitude, jd, flags?)`**
+- `longitude`: Target ecliptic longitude in degrees (0-360)
+- `jd`: Starting Julian Day (search forward from here)
+- `flags` (optional): Calculation flags
+
+The function finds the next time the Moon reaches the specified longitude after `jd`. Since the Moon completes a full cycle in ~27.3 days, you will always get a result within about a month.
+
+**`moonNodeCrossing(jd, flags?)`**
+- `jd`: Starting Julian Day (search forward from here)
+- `flags` (optional): Calculation flags
+
+The function finds the next time the Moon crosses the ecliptic plane (latitude = 0). Node crossings happen about every 13.6 days (half the sidereal month), alternating between ascending and descending.
+
+### Rahu and Ketu in Vedic Astrology
+
+In Vedic (Hindu) astrology, the lunar nodes are given planetary status:
+- **Rahu** (ascending node): associated with ambition, materialism, worldly desires, and obsession. Considered a malefic that amplifies whatever it touches.
+- **Ketu** (descending node): associated with spirituality, detachment, past-life karma, and liberation. Considered a malefic that strips away worldly attachments.
+
+The node positions used in Vedic astrology are typically the **mean nodes** (computed from `SE_MEAN_NODE = 10`), not the true/osculating nodes. The mean nodes move smoothly backward; the true nodes (from `SE_TRUE_NODE = 11`) wobble due to solar and planetary perturbations. Both can be computed with `swe.calc()`.