@typescriptify/sweph 1.0.0

package/src/SwissEph/UseCases/Phenomena.md

@@ -0,0 +1,328 @@
+# Planetary Phenomena
+
+Planetary phenomena are the observable characteristics of a planet as seen from Earth at a given moment. When you look at a planet in the night sky, you might wonder: How bright is it? How far from the Sun does it appear? How much of its surface is illuminated? The `phenomena()` method answers all these questions at once, returning five key measurements:
+
+- **Phase angle**: the angle Sun-Planet-Earth, which determines how much of the planet's illuminated side faces us
+- **Phase (illuminated fraction)**: a number from 0.0 to 1.0 representing what proportion of the visible disk is lit
+- **Elongation**: the angular separation between the planet and the Sun as seen from Earth
+- **Apparent diameter**: how large the planet appears, measured in arcseconds
+- **Apparent magnitude**: how bright the planet appears on the astronomical magnitude scale
+
+These quantities are useful for observation planning (can I see this planet tonight?), astrophotography, and understanding the geometric relationship between the Sun, a planet, and the Earth.
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_VENUS } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 3, 15, 20); // 2025 Mar 15, 20:00 UT
+
+const p = swe.phenomena(jd, SE_VENUS);
+
+console.log(`Phase angle:         ${p.phaseAngle.toFixed(2)} deg`);
+console.log(`Phase (illuminated): ${(p.phase * 100).toFixed(1)}%`);
+console.log(`Elongation from Sun: ${p.elongation.toFixed(2)} deg`);
+console.log(`Apparent diameter:   ${p.apparentDiameter.toFixed(2)} arcsec`);
+console.log(`Apparent magnitude:  ${p.apparentMagnitude.toFixed(2)}`);
+
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### Phenomena for all visible planets
+
+```typescript
+import { SwissEph } from '../index';
+import {
+  SE_MERCURY, SE_VENUS, SE_MARS,
+  SE_JUPITER, SE_SATURN,
+} from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 6, 1, 0);
+
+const planets = [
+  { id: SE_MERCURY, name: 'Mercury' },
+  { id: SE_VENUS,   name: 'Venus' },
+  { id: SE_MARS,    name: 'Mars' },
+  { id: SE_JUPITER, name: 'Jupiter' },
+  { id: SE_SATURN,  name: 'Saturn' },
+];
+
+console.log('Planet     Elong   Phase%   Mag    Diam"');
+console.log('---------- ------  ------  -----  -----');
+
+for (const pl of planets) {
+  const p = swe.phenomena(jd, pl.id);
+  console.log(
+    `${pl.name.padEnd(10)} ` +
+    `${p.elongation.toFixed(1).padStart(5)}°  ` +
+    `${(p.phase * 100).toFixed(1).padStart(5)}%  ` +
+    `${p.apparentMagnitude.toFixed(1).padStart(5)}  ` +
+    `${p.apparentDiameter.toFixed(2).padStart(5)}`
+  );
+}
+
+swe.close();
+```
+
+### Checking if a planet is visible
+
+A planet is generally visible to the naked eye when:
+1. Its elongation from the Sun is greater than about 15 degrees (so the sky is dark enough where it appears)
+2. Its apparent magnitude is less than about 6.0 (the naked-eye limit)
+
+```typescript
+import { SwissEph } from '../index';
+import {
+  SE_MERCURY, SE_VENUS, SE_MARS,
+  SE_JUPITER, SE_SATURN,
+} from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 4, 10, 20);
+
+const planets = [
+  { id: SE_MERCURY, name: 'Mercury' },
+  { id: SE_VENUS,   name: 'Venus' },
+  { id: SE_MARS,    name: 'Mars' },
+  { id: SE_JUPITER, name: 'Jupiter' },
+  { id: SE_SATURN,  name: 'Saturn' },
+];
+
+for (const pl of planets) {
+  const p = swe.phenomena(jd, pl.id);
+
+  const farEnoughFromSun = p.elongation > 15;
+  const brightEnough = p.apparentMagnitude < 6.0;
+  const visible = farEnoughFromSun && brightEnough;
+
+  console.log(
+    `${pl.name.padEnd(10)} elong=${p.elongation.toFixed(1).padStart(5)}° ` +
+    `mag=${p.apparentMagnitude.toFixed(1).padStart(5)} ` +
+    `→ ${visible ? 'VISIBLE' : 'not visible'}`
+  );
+}
+
+swe.close();
+```
+
+Note: This is a simplified check. True visibility also depends on whether the planet is above the horizon at your location and the time of night. For a complete analysis, combine with `swe.riseSet()` and `swe.azalt()`.
+
+### Tracking Venus phases over a synodic cycle
+
+Venus goes through phases like the Moon. As an inferior planet (orbiting closer to the Sun than Earth), Venus shows a full range of phases depending on its position relative to the Sun and Earth.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_VENUS } from '../../constants';
+
+const swe = new SwissEph();
+
+// Track Venus phenomena monthly over ~19 months (Venus synodic period ≈ 584 days)
+const startJd = SwissEph.julianDay(2025, 1, 1, 0);
+
+console.log('Date        Phase%   Elong   PhaseAngle   Mag    Diam"');
+
+for (let month = 0; month < 20; month++) {
+  const jd = startJd + month * 30.44; // ~1 month intervals
+  const p = swe.phenomena(jd, SE_VENUS);
+  const d = SwissEph.fromJulianDay(jd);
+
+  console.log(
+    `${d.year}-${String(d.month).padStart(2,'0')}-${String(Math.floor(d.day)).padStart(2,'0')}  ` +
+    `${(p.phase * 100).toFixed(1).padStart(5)}%  ` +
+    `${p.elongation.toFixed(1).padStart(5)}°  ` +
+    `${p.phaseAngle.toFixed(1).padStart(9)}°  ` +
+    `${p.apparentMagnitude.toFixed(1).padStart(5)}  ` +
+    `${p.apparentDiameter.toFixed(1).padStart(5)}`
+  );
+}
+
+swe.close();
+```
+
+When Venus is on the far side of the Sun (superior conjunction), it appears nearly full but small and faint. When it is closest to Earth (inferior conjunction), it appears as a thin crescent but very large and actually at its brightest just before/after, when the combination of size and illumination peaks.
+
+### Moon phase as illuminated fraction
+
+The `phenomena()` method works for the Moon too, giving you the illuminated fraction directly.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MOON } from '../../constants';
+
+const swe = new SwissEph();
+
+// Check Moon phase nightly for a month
+const startJd = SwissEph.julianDay(2025, 3, 1, 0);
+
+for (let day = 0; day < 30; day++) {
+  const jd = startJd + day;
+  const p = swe.phenomena(jd, SE_MOON);
+  const d = SwissEph.fromJulianDay(jd);
+
+  // Simple phase name based on illuminated fraction and phase angle
+  const pct = p.phase * 100;
+  let phaseName: string;
+  if (pct < 2) phaseName = 'New Moon';
+  else if (pct < 40) phaseName = p.elongation < 180 ? 'Waxing Crescent' : 'Waning Crescent';
+  else if (pct < 60) phaseName = p.elongation < 180 ? 'First Quarter' : 'Last Quarter';
+  else if (pct < 98) phaseName = p.elongation < 180 ? 'Waxing Gibbous' : 'Waning Gibbous';
+  else phaseName = 'Full Moon';
+
+  const bar = '#'.repeat(Math.round(pct / 5)).padEnd(20);
+  console.log(
+    `Mar ${String(day + 1).padStart(2)}  ${pct.toFixed(1).padStart(5)}%  [${bar}]  ${phaseName}`
+  );
+}
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### Phase Angle
+
+The phase angle is the angle formed at the planet between the directions to the Sun and to the Earth. Imagine standing on the planet's surface: the phase angle is the angle between the Sun and Earth in your sky.
+
+```
+        Sun
+       /
+      / phase angle
+Planet ---------- Earth
+```
+
+- **0 degrees**: The Sun is directly behind Earth (from the planet's perspective). This is **opposition** for superior planets -- the planet's fully lit face points toward Earth. For the Moon, this is a Full Moon.
+- **90 degrees**: Half the visible disk is illuminated (like a quarter Moon, or Mercury/Venus at greatest elongation).
+- **180 degrees**: The planet is between Earth and the Sun (**conjunction**). The lit side faces away from Earth. For the Moon, this is a New Moon.
+
+### Phase (Illuminated Fraction)
+
+The phase is a value from 0.0 to 1.0 representing the fraction of the planet's visible disk that is illuminated by the Sun. It is related to the phase angle by:
+
+```
+phase = (1 + cos(phaseAngle)) / 2
+```
+
+- 1.0 = fully illuminated (opposition/full)
+- 0.5 = half illuminated (quarter)
+- 0.0 = unilluminated (conjunction/new)
+
+For the Moon, this is the familiar "percent illumination" often shown in weather apps and calendars.
+
+### Elongation
+
+Elongation is the angular distance between the planet and the Sun as seen from Earth. It determines whether and when you can observe the planet:
+
+- **0 degrees**: conjunction -- the planet is in the same direction as the Sun and invisible in the glare
+- **~15 degrees**: the minimum elongation for a planet to be glimpsed in twilight
+- **90 degrees**: quadrature -- the planet is a quarter of the sky away from the Sun
+- **180 degrees**: opposition -- the planet is opposite the Sun, rising at sunset and visible all night
+
+For **inferior planets** (Mercury and Venus, which orbit closer to the Sun than Earth), elongation has a maximum value:
+- Mercury: ~18-28 degrees (varies due to orbital eccentricity)
+- Venus: ~45-47 degrees
+
+This is why Mercury and Venus are always seen near the Sun, as "morning stars" or "evening stars." They can never appear at opposition.
+
+For **superior planets** (Mars through Pluto), elongation can range from 0 to 180 degrees.
+
+### Apparent Diameter
+
+The apparent diameter is how large the planet appears in the sky, measured in **arcseconds** (1/3600 of a degree). For reference:
+- The Sun and Moon are each about 1800 arcseconds (30 arcminutes, or half a degree)
+- Jupiter at opposition: ~45 arcseconds
+- Saturn (disk only): ~18 arcseconds
+- Mars at opposition: ~14-25 arcseconds (varies greatly)
+- Venus at closest approach: ~60 arcseconds (larger than Jupiter!)
+
+The apparent diameter changes as the planet's distance from Earth changes. It is inversely proportional to distance.
+
+### Apparent Magnitude
+
+The **magnitude scale** is the astronomer's measure of brightness. It was invented by the ancient Greek astronomer **Hipparchus** (~150 BC), who classified stars into six groups: the brightest stars were "first magnitude" and the faintest visible stars were "sixth magnitude."
+
+The modern scale is logarithmic and extends in both directions:
+- **Lower numbers = brighter**. Negative magnitudes are very bright.
+- Each step of 1 magnitude corresponds to a brightness factor of about 2.512
+- A difference of 5 magnitudes = exactly 100x brightness difference
+
+Typical planet magnitudes:
+| Object | Typical Magnitude |
+|--------|------------------|
+| Sun | -26.7 |
+| Full Moon | -12.7 |
+| Venus (brightest) | -4.6 |
+| Jupiter (opposition) | -2.5 |
+| Mars (opposition) | -2.0 to -2.9 |
+| Saturn | +0.5 to +1.5 |
+| Mercury | -0.5 to +3 |
+| Uranus | +5.7 |
+| Neptune | +7.8 (invisible to naked eye) |
+| Naked eye limit | ~+6.0 |
+
+### Geometry of Opposition and Conjunction
+
+For a **superior planet** (orbiting farther from the Sun than Earth):
+
+```
+          Sun
+           |
+     Earth-+--------Planet    ← Opposition (phase angle ≈ 0°, elongation = 180°)
+```
+
+At opposition, the planet is closest to Earth, appears brightest, shows its full disk, and is visible all night. This is the best time to observe it.
+
+```
+          Sun
+           |
+    Planet-+-Earth             ← Conjunction (phase angle ≈ 180°, elongation ≈ 0°)
+```
+
+At conjunction, the planet is behind the Sun and invisible.
+
+For an **inferior planet** (Mercury or Venus):
+
+```
+          Sun
+           |
+     Earth-+    Venus          ← Greatest Eastern Elongation (evening star)
+                                  seen after sunset in the west
+```
+
+```
+          Sun
+           |
+   Venus   +-Earth             ← Greatest Western Elongation (morning star)
+                                  seen before sunrise in the east
+```
+
+### Return Type
+
+```typescript
+interface PhenoResult {
+  phaseAngle: number;        // degrees, 0-180
+  phase: number;             // illuminated fraction, 0.0-1.0
+  elongation: number;        // degrees from Sun, 0-180
+  apparentDiameter: number;  // arcseconds
+  apparentMagnitude: number; // magnitude (lower = brighter)
+}
+```
+
+### Applicable Bodies
+
+The `phenomena()` method works for all planets (Mercury through Pluto), the Moon, asteroids, and fixed stars. For the Sun itself, most values are not meaningful (the Sun's elongation from itself is always 0).
+
+### Flags
+
+The optional `flags` parameter controls the calculation method. Normally you can omit it and accept the defaults. Possible flags include sidereal mode flags, but for phenomena calculations the default tropical geocentric computation is standard.

package/src/SwissEph/UseCases/PlanetPositions.md

@@ -0,0 +1,366 @@
+# Planet Positions
+
+Calculating the position of a planet is the most fundamental operation in astrology and astronomical computing. Given a moment in time (expressed as a Julian Day number), the Swiss Ephemeris computes where each planet appears in the sky. The result includes the planet's **longitude** (its position along the ecliptic, 0-360 degrees), **latitude** (how far above or below the ecliptic plane), and **distance** (how far away it is, in AU). You also get the **speed** of each value -- how fast the planet is moving per day.
+
+This is the building block for natal charts, transits, progressions, synastry, and virtually every astrological technique.
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN, SE_MOON, SE_MARS } from '../../constants';
+
+const swe = new SwissEph();
+
+// J2000.0 epoch (January 1, 2000 at 12:00 UT)
+const jd = SwissEph.julianDay(2000, 1, 1, 12);
+
+const sun = swe.calc(jd, SE_SUN);
+console.log(`Sun longitude: ${sun.longitude.toFixed(4)}deg`);
+// Sun longitude: 280.3706deg
+
+const moon = swe.calc(jd, SE_MOON);
+console.log(`Moon longitude: ${moon.longitude.toFixed(4)}deg`);
+
+const mars = swe.calc(jd, SE_MARS);
+console.log(`Mars longitude: ${mars.longitude.toFixed(4)}deg`);
+console.log(`Mars speed: ${mars.longitudeSpeed.toFixed(4)} deg/day`);
+
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### All classical planets at a given date
+
+```typescript
+import { SwissEph } from '../index';
+import {
+  SE_SUN, SE_MOON, SE_MERCURY, SE_VENUS, SE_MARS,
+  SE_JUPITER, SE_SATURN, SE_URANUS, SE_NEPTUNE, SE_PLUTO,
+} from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 4, 8, 18.28); // 2024 Apr 8, ~18:17 UT
+
+const planets = [
+  { id: SE_SUN,     name: 'Sun' },
+  { id: SE_MOON,    name: 'Moon' },
+  { id: SE_MERCURY, name: 'Mercury' },
+  { id: SE_VENUS,   name: 'Venus' },
+  { id: SE_MARS,    name: 'Mars' },
+  { id: SE_JUPITER, name: 'Jupiter' },
+  { id: SE_SATURN,  name: 'Saturn' },
+  { id: SE_URANUS,  name: 'Uranus' },
+  { id: SE_NEPTUNE, name: 'Neptune' },
+  { id: SE_PLUTO,   name: 'Pluto' },
+];
+
+for (const p of planets) {
+  const pos = swe.calc(jd, p.id);
+
+  // Convert longitude to zodiac sign
+  const signs = ['Ari','Tau','Gem','Can','Leo','Vir','Lib','Sco','Sag','Cap','Aqu','Pis'];
+  const signIndex = Math.floor(pos.longitude / 30);
+  const degInSign = pos.longitude - signIndex * 30;
+
+  console.log(
+    `${p.name.padEnd(9)} ${degInSign.toFixed(2).padStart(6)}deg ${signs[signIndex]}` +
+    `  speed: ${pos.longitudeSpeed.toFixed(4)} deg/day`
+  );
+}
+
+swe.close();
+```
+
+### Equatorial coordinates (Right Ascension and Declination)
+
+Astronomers typically use equatorial coordinates rather than ecliptic. Pass `SEFLG_EQUATORIAL` to get Right Ascension (in degrees, 0-360) and Declination (in degrees, -90 to +90) instead of ecliptic longitude and latitude.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN, SEFLG_EQUATORIAL } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 6, 21, 12);
+
+const sun = swe.calc(jd, SE_SUN, SEFLG_EQUATORIAL);
+
+// When SEFLG_EQUATORIAL is set:
+//   longitude  -> Right Ascension (degrees, 0-360)
+//   latitude   -> Declination (degrees, -90 to +90)
+//   distance   -> distance in AU (same as ecliptic)
+console.log(`Sun RA:  ${sun.longitude.toFixed(4)} deg`);
+console.log(`Sun Dec: ${sun.latitude.toFixed(4)} deg`);
+
+// Convert RA from degrees to hours/minutes/seconds
+const raHours = sun.longitude / 15;
+const h = Math.floor(raHours);
+const m = Math.floor((raHours - h) * 60);
+const s = ((raHours - h) * 60 - m) * 60;
+console.log(`Sun RA:  ${h}h ${m}m ${s.toFixed(1)}s`);
+
+swe.close();
+```
+
+### Heliocentric positions
+
+View planets from the Sun's perspective instead of from Earth. Useful for heliocentric astrology and astronomical research.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MARS, SE_EARTH, SEFLG_HELCTR } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+
+// Heliocentric Mars (as seen from the Sun)
+const mars = swe.calc(jd, SE_MARS, SEFLG_HELCTR);
+console.log(`Mars heliocentric longitude: ${mars.longitude.toFixed(4)} deg`);
+console.log(`Mars distance from Sun: ${mars.distance.toFixed(6)} AU`);
+
+// Heliocentric Earth
+const earth = swe.calc(jd, SE_EARTH, SEFLG_HELCTR);
+console.log(`Earth heliocentric longitude: ${earth.longitude.toFixed(4)} deg`);
+
+swe.close();
+```
+
+### Lunar nodes and Lilith
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MEAN_NODE, SE_TRUE_NODE, SE_MEAN_APOG, SE_OSCU_APOG } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+
+const meanNode = swe.calc(jd, SE_MEAN_NODE);
+const trueNode = swe.calc(jd, SE_TRUE_NODE);
+console.log(`Mean North Node: ${meanNode.longitude.toFixed(4)} deg`);
+console.log(`True North Node: ${trueNode.longitude.toFixed(4)} deg`);
+// The South Node is always 180 degrees opposite the North Node.
+
+const meanLilith = swe.calc(jd, SE_MEAN_APOG);
+const oscuLilith = swe.calc(jd, SE_OSCU_APOG);
+console.log(`Mean Lilith (Black Moon): ${meanLilith.longitude.toFixed(4)} deg`);
+console.log(`Osculating Lilith:        ${oscuLilith.longitude.toFixed(4)} deg`);
+
+swe.close();
+```
+
+### Chiron and the main asteroids
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_CHIRON, SE_CERES, SE_PALLAS, SE_JUNO, SE_VESTA } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+
+const bodies = [
+  { id: SE_CHIRON, name: 'Chiron' },
+  { id: SE_CERES,  name: 'Ceres' },
+  { id: SE_PALLAS, name: 'Pallas' },
+  { id: SE_JUNO,   name: 'Juno' },
+  { id: SE_VESTA,  name: 'Vesta' },
+];
+
+for (const b of bodies) {
+  const pos = swe.calc(jd, b.id);
+  console.log(`${b.name.padEnd(8)} ${pos.longitude.toFixed(4)} deg`);
+}
+
+swe.close();
+```
+
+### Detecting retrograde motion
+
+A planet is retrograde when its longitudinal speed is negative.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MERCURY } from '../../constants';
+
+const swe = new SwissEph();
+
+// Check Mercury's direction over several months
+for (let month = 1; month <= 12; month++) {
+  const jd = SwissEph.julianDay(2024, month, 15, 12);
+  const pos = swe.calc(jd, SE_MERCURY);
+  const direction = pos.longitudeSpeed < 0 ? 'RETROGRADE' : 'direct';
+  console.log(`2024-${String(month).padStart(2,'0')}-15  Mercury speed: ${pos.longitudeSpeed.toFixed(4)} deg/day  ${direction}`);
+}
+
+swe.close();
+```
+
+### Topocentric positions (observer on Earth's surface)
+
+Geocentric positions are calculated from Earth's center. For the Moon especially, the difference from a specific location on Earth's surface (topocentric) can be up to about 1 degree.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MOON, SEFLG_TOPOCTR } from '../../constants';
+
+// Set up the observer's location in the constructor
+const swe = new SwissEph({
+  topo: { longitude: -73.9857, latitude: 40.7484, altitude: 10 }, // New York
+});
+
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+
+// Topocentric Moon
+const moonTopo = swe.calc(jd, SE_MOON, SEFLG_TOPOCTR);
+console.log(`Moon (topocentric): ${moonTopo.longitude.toFixed(4)} deg`);
+
+// Compare with geocentric (no SEFLG_TOPOCTR)
+const swe2 = new SwissEph();
+const moonGeo = swe2.calc(jd, SE_MOON);
+console.log(`Moon (geocentric):  ${moonGeo.longitude.toFixed(4)} deg`);
+console.log(`Difference: ${(moonTopo.longitude - moonGeo.longitude).toFixed(4)} deg`);
+
+swe.close();
+swe2.close();
+```
+
+### Sidereal positions
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN, SE_SIDM_LAHIRI, SEFLG_SIDEREAL } from '../../constants';
+
+const swe = new SwissEph({ siderealMode: SE_SIDM_LAHIRI });
+const jd = SwissEph.julianDay(2024, 1, 15, 12);
+
+// IMPORTANT: you must pass SEFLG_SIDEREAL in the flags to calc()
+// Setting siderealMode in the constructor only configures which ayanamsa to use;
+// it does NOT automatically add SEFLG_SIDEREAL to calc() calls.
+const sun = swe.calc(jd, SE_SUN, SEFLG_SIDEREAL);
+console.log(`Sun sidereal longitude (Lahiri): ${sun.longitude.toFixed(4)} deg`);
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### What the return values mean
+
+| Field             | Description                                                                                   |
+|-------------------|-----------------------------------------------------------------------------------------------|
+| `longitude`       | Position along the ecliptic (or RA if `SEFLG_EQUATORIAL`), in degrees 0-360                   |
+| `latitude`        | Angular distance above/below the ecliptic (or Declination if `SEFLG_EQUATORIAL`), in degrees  |
+| `distance`        | Distance in AU (astronomical units; 1 AU = ~149.6 million km). For the Moon, also in AU.      |
+| `longitudeSpeed`  | Daily motion in longitude (degrees per day). Negative = retrograde.                           |
+| `latitudeSpeed`   | Daily motion in latitude (degrees per day).                                                   |
+| `distanceSpeed`   | Daily change in distance (AU per day). Negative = approaching.                                |
+| `flags`           | Flags actually used by the engine (may differ from your input if the engine fell back).       |
+
+### Available planets and bodies
+
+| Constant         | Value | Description                                                         |
+|------------------|-------|---------------------------------------------------------------------|
+| `SE_SUN`         | 0     | The Sun                                                             |
+| `SE_MOON`        | 1     | The Moon                                                            |
+| `SE_MERCURY`     | 2     | Mercury                                                             |
+| `SE_VENUS`       | 3     | Venus                                                               |
+| `SE_MARS`        | 4     | Mars                                                                |
+| `SE_JUPITER`     | 5     | Jupiter                                                             |
+| `SE_SATURN`      | 6     | Saturn                                                              |
+| `SE_URANUS`      | 7     | Uranus                                                              |
+| `SE_NEPTUNE`     | 8     | Neptune                                                             |
+| `SE_PLUTO`       | 9     | Pluto                                                               |
+| `SE_MEAN_NODE`   | 10    | Mean Lunar Node (North Node / Rahu). Moves smoothly.               |
+| `SE_TRUE_NODE`   | 11    | True (osculating) Lunar Node. Wobbles with lunar perturbations.     |
+| `SE_MEAN_APOG`   | 12    | Mean Lunar Apogee (Black Moon Lilith). Smooth mean motion.         |
+| `SE_OSCU_APOG`   | 13    | Osculating Lunar Apogee. True instantaneous value, wobbles.        |
+| `SE_EARTH`       | 14    | Earth (only meaningful for heliocentric/barycentric calculations). |
+| `SE_CHIRON`      | 15    | Chiron (minor planet / centaur orbiting between Saturn and Uranus). |
+| `SE_CERES`       | 17    | Ceres (dwarf planet, largest body in the asteroid belt).           |
+| `SE_PALLAS`      | 18    | Pallas (second-largest asteroid).                                  |
+| `SE_JUNO`        | 19    | Juno (asteroid).                                                   |
+| `SE_VESTA`       | 20    | Vesta (second-most-massive asteroid).                              |
+
+**Note on the South Node**: The Swiss Ephemeris only calculates the North Node. The South Node is always exactly 180 degrees opposite: `southNode = (northNode + 180) % 360`.
+
+**Note on SE_EARTH**: Requesting SE_EARTH in normal geocentric mode is meaningless (you would be asking for Earth's position as seen from Earth). Use it with `SEFLG_HELCTR` (heliocentric) or `SEFLG_BARYCTR` (barycentric).
+
+### Flag constants
+
+Flags modify the calculation. They are combined with the bitwise OR operator (`|`). The wrapper automatically adds `SEFLG_SPEED` so you always get speed values.
+
+| Constant           | Value  | Effect                                                                     |
+|--------------------|--------|----------------------------------------------------------------------------|
+| `SEFLG_SPEED`      | 256    | Compute speed (added automatically by wrapper).                            |
+| `SEFLG_EQUATORIAL` | 2048   | Return Right Ascension / Declination instead of ecliptic longitude/lat.    |
+| `SEFLG_XYZ`        | 4096   | Return Cartesian (X, Y, Z) instead of polar (lon, lat, dist).             |
+| `SEFLG_RADIANS`    | 8192   | Return angles in radians instead of degrees.                               |
+| `SEFLG_HELCTR`     | 8      | Heliocentric position (as seen from the Sun).                              |
+| `SEFLG_BARYCTR`    | 16384  | Barycentric position (relative to solar system barycenter).                |
+| `SEFLG_TOPOCTR`    | 32768  | Topocentric (from observer's location). Requires `topo` to be set.        |
+| `SEFLG_SIDEREAL`   | 65536  | Sidereal zodiac. Requires `siderealMode` to be configured.                |
+| `SEFLG_TRUEPOS`    | 16     | True/geometric position (no light-time correction).                        |
+| `SEFLG_NOABERR`    | 1024   | No aberration of light correction.                                         |
+| `SEFLG_NOGDEFL`    | 512    | No gravitational deflection of light.                                      |
+| `SEFLG_J2000`      | 32     | Refer positions to the J2000 equinox (not the equinox of date).           |
+| `SEFLG_NONUT`      | 64     | No nutation (use mean equinox of date, not true equinox).                  |
+
+You can combine flags:
+
+```typescript
+import { SEFLG_EQUATORIAL, SEFLG_TOPOCTR, SEFLG_SIDEREAL } from '../../constants';
+
+// Sidereal equatorial topocentric position
+const pos = swe.calc(jd, SE_SUN, SEFLG_EQUATORIAL | SEFLG_SIDEREAL | SEFLG_TOPOCTR);
+```
+
+### Understanding ecliptic longitude
+
+Ecliptic longitude is measured along the ecliptic (the Sun's apparent path through the sky over a year). It starts at the **vernal equinox point** (0 degrees Aries in the tropical zodiac) and increases eastward through the zodiac signs:
+
+| Degrees   | Sign        |
+|-----------|-------------|
+| 0 - 30    | Aries       |
+| 30 - 60   | Taurus      |
+| 60 - 90   | Gemini      |
+| 90 - 120  | Cancer      |
+| 120 - 150 | Leo         |
+| 150 - 180 | Virgo       |
+| 180 - 210 | Libra       |
+| 210 - 240 | Scorpio     |
+| 240 - 270 | Sagittarius |
+| 270 - 300 | Capricorn   |
+| 300 - 330 | Aquarius    |
+| 330 - 360 | Pisces      |
+
+To convert absolute longitude to sign + degree within sign:
+```typescript
+const signIndex = Math.floor(longitude / 30);     // 0 = Aries, 11 = Pisces
+const degreeInSign = longitude - signIndex * 30;   // 0.0 to 29.999...
+```
+
+### Understanding ecliptic latitude
+
+Most planets stay very close to the ecliptic (latitude near 0). The Moon can reach about +/-5 degrees. Pluto can reach about +/-17 degrees. The Sun's ecliptic latitude is always essentially 0 (by definition, since the ecliptic is the Sun's apparent path).
+
+### Time input: UT vs ET
+
+The Julian Day number you pass to `calc()` is interpreted according to the `timeMode` set in the constructor:
+
+- **`'ut'`** (default): Universal Time. This is clock time corrected for time zones. Use this for most astrological work.
+- **`'et'`**: Ephemeris Time (also called Terrestrial Time / TT). This is the uniform time scale used internally by the ephemeris. It differs from UT by "delta-T", which is about 69 seconds in 2024.
+
+For dates within a few centuries of the present, the difference between UT and ET is small and the library handles the conversion internally. For ancient or far-future dates, the distinction becomes significant.
+
+### Edge cases
+
+- **Speed is always included**: The wrapper adds `SEFLG_SPEED` automatically. You do not need to pass it.
+- **Ephemeris fallback**: If you request `'swisseph'` or `'jpl'` but the ephemeris files are not loaded, the engine silently falls back to the Moshier analytical ephemeris. You can check the returned `flags` field to see which ephemeris was actually used.
+- **Retrograde planets**: When `longitudeSpeed < 0`, the planet is retrograde (appearing to move backward through the zodiac from Earth's perspective). This is a normal geometric effect of orbital mechanics.
+- **Mean vs True Node**: The mean node moves smoothly backward through the zodiac (~19.3 degrees/year). The true node oscillates around the mean with a period of about 173 days. Most astrologers use the mean node; Vedic astrology traditionally uses the true node (Rahu/Ketu).