@typescriptify/sweph 1.0.0

package/src/SwissEph/UseCases/EphemerisFiles.md

@@ -0,0 +1,338 @@
+# Ephemeris Files
+
+The Swiss Ephemeris supports three different ephemeris modes, each offering a different tradeoff between convenience, precision, and resource requirements:
+
+- **Moshier** (default): A purely analytical ephemeris built into the library. No external files needed. Accuracy is about 1 arcsecond for planets and a few arcseconds for the Moon over the period 3000 BCE to 3000 CE. This is the easiest to use and is sufficient for most astrological applications.
+
+- **Swiss Ephemeris (SWIEPH)**: Compressed data derived from NASA's JPL ephemerides, stored in `.se1` binary files. Accuracy is about 0.001 arcsecond (1 milliarcsecond) -- roughly 1000 times more precise than Moshier. Covers about 10,800 years (5400 BCE to 5400 CE). File sizes are modest (a few hundred KB each).
+
+- **JPL Development Ephemeris**: NASA's own ephemeris files (DE441, DE440, etc.), the gold standard used for space mission navigation. Accuracy is limited only by the observations used to construct it. File sizes are large (hundreds of MB to several GB). Covers up to 26,000 years (DE441).
+
+For most applications, the built-in Moshier ephemeris is perfectly adequate. You only need external files if you require milliarcsecond precision or have specific research needs.
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MARS } from '../../constants';
+
+// Default: Moshier analytical ephemeris (no files needed)
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 6, 21, 12);
+const mars = swe.calc(jd, SE_MARS);
+console.log(`Mars (Moshier): ${mars.longitude.toFixed(6)} deg`);
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### Using the Moshier ephemeris (default)
+
+No setup required. Just create a SwissEph instance and start calculating:
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN, SE_MOON, SE_MARS } from '../../constants';
+
+const swe = new SwissEph(); // Default: Moshier
+
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+console.log(`Sun:  ${swe.calc(jd, SE_SUN).longitude.toFixed(6)} deg`);
+console.log(`Moon: ${swe.calc(jd, SE_MOON).longitude.toFixed(6)} deg`);
+console.log(`Mars: ${swe.calc(jd, SE_MARS).longitude.toFixed(6)} deg`);
+
+swe.close();
+```
+
+### Loading Swiss Ephemeris (SE1) files
+
+SE1 files contain compressed Chebyshev polynomial coefficients for very high precision. You need separate files for planets, the Moon, and asteroids:
+
+| File pattern    | Contents              |
+|-----------------|-----------------------|
+| `sepl_*.se1`    | Major planets         |
+| `semo_*.se1`    | The Moon              |
+| `seas_*.se1`    | Asteroids             |
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN, SE_MOON, SE_MARS } from '../../constants';
+
+// Create instance configured for Swiss Ephemeris mode
+const swe = new SwissEph({ ephemeris: 'swisseph' });
+
+// Load the SE1 files (you must provide the ArrayBuffer data)
+// In Node.js:
+import { readFileSync } from 'fs';
+const planetData = readFileSync('ephe/sepl_18.se1');
+const moonData = readFileSync('ephe/semo_18.se1');
+
+swe.loadEphemerisFile(planetData.buffer, 'sepl_18.se1');
+swe.loadEphemerisFile(moonData.buffer, 'semo_18.se1');
+
+// In a browser, you would fetch the files:
+// const resp = await fetch('/ephe/sepl_18.se1');
+// const planetData = await resp.arrayBuffer();
+// swe.loadEphemerisFile(planetData, 'sepl_18.se1');
+
+// Now calculate with milliarcsecond precision
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+console.log(`Sun (SWIEPH):  ${swe.calc(jd, SE_SUN).longitude.toFixed(6)} deg`);
+console.log(`Moon (SWIEPH): ${swe.calc(jd, SE_MOON).longitude.toFixed(6)} deg`);
+console.log(`Mars (SWIEPH): ${swe.calc(jd, SE_MARS).longitude.toFixed(6)} deg`);
+
+swe.close();
+```
+
+### Loading JPL ephemeris files
+
+JPL files (like DE441) provide the ultimate in precision:
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SUN, SE_MOON, SE_MARS } from '../../constants';
+import { readFileSync } from 'fs';
+
+const swe = new SwissEph({ ephemeris: 'jpl' });
+
+// Load the JPL file
+const jplData = readFileSync('ephe/de441.eph');
+swe.loadJplFile(jplData.buffer, 'de441.eph');
+
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+console.log(`Sun (JPL):  ${swe.calc(jd, SE_SUN).longitude.toFixed(6)} deg`);
+console.log(`Moon (JPL): ${swe.calc(jd, SE_MOON).longitude.toFixed(6)} deg`);
+console.log(`Mars (JPL): ${swe.calc(jd, SE_MARS).longitude.toFixed(6)} deg`);
+
+swe.close();
+```
+
+### Fallback behavior
+
+If you request a higher-precision ephemeris but the necessary file is not loaded, the engine silently falls back:
+
+- JPL mode falls back to SWIEPH (if SE1 files loaded), then to Moshier
+- SWIEPH mode falls back to Moshier
+
+You can detect the actual ephemeris used by checking the returned `flags`:
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MARS, SEFLG_MOSEPH, SEFLG_SWIEPH, SEFLG_JPLEPH } from '../../constants';
+
+// Request SWIEPH but do not load any files
+const swe = new SwissEph({ ephemeris: 'swisseph' });
+
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+const mars = swe.calc(jd, SE_MARS);
+
+// Check which ephemeris was actually used
+if (mars.flags & SEFLG_JPLEPH) {
+  console.log('Used: JPL');
+} else if (mars.flags & SEFLG_SWIEPH) {
+  console.log('Used: Swiss Ephemeris (SE1 files)');
+} else {
+  console.log('Used: Moshier (fallback)');
+}
+// Output: "Used: Moshier (fallback)" because no SE1 files were loaded
+
+swe.close();
+```
+
+### Comparing precision between ephemeris modes
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MARS } from '../../constants';
+import { readFileSync } from 'fs';
+
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+
+// Moshier
+const mosh = new SwissEph();
+const marsMosh = mosh.calc(jd, SE_MARS);
+
+// Swiss Ephemeris
+const swi = new SwissEph({ ephemeris: 'swisseph' });
+const planetData = readFileSync('ephe/sepl_18.se1');
+swi.loadEphemerisFile(planetData.buffer, 'sepl_18.se1');
+const marsSwi = swi.calc(jd, SE_MARS);
+
+// Compare
+const diffArcsec = Math.abs(marsMosh.longitude - marsSwi.longitude) * 3600;
+console.log(`Mars (Moshier):  ${marsMosh.longitude.toFixed(8)} deg`);
+console.log(`Mars (SWIEPH):   ${marsSwi.longitude.toFixed(8)} deg`);
+console.log(`Difference:      ${diffArcsec.toFixed(4)} arcseconds`);
+
+mosh.close();
+swi.close();
+```
+
+### Setting the ephemeris file path
+
+For systems that read files from disk (not applicable to in-memory ArrayBuffer loading, but useful if the underlying engine supports path-based loading):
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph({ ephemeris: 'swisseph' });
+
+// Tell the engine where to look for ephemeris files
+swe.setEphePath('/path/to/ephemeris/files');
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### The JPL Development Ephemeris series
+
+NASA's Jet Propulsion Laboratory (JPL) has been producing numerical ephemerides since the 1960s. Each version (called a "Development Ephemeris" or DE) incorporates improved observations and models. The major versions:
+
+| Version | Year | Time span              | Notes                                                   |
+|---------|------|------------------------|---------------------------------------------------------|
+| DE200   | 1981 | 1600-2169              | First widely used modern ephemeris. Based on optical and radar observations. |
+| DE405   | 1998 | 1600-2200              | Major improvement incorporating VLBI data and LLR (Lunar Laser Ranging). Used as reference for many years. |
+| DE406   | 1998 | -3000 to +3000         | Long-span version of DE405 with slightly reduced precision. |
+| DE421   | 2008 | 1900-2050              | Updated with additional LLR data and Mars spacecraft tracking. |
+| DE430   | 2014 | 1550-2650              | Incorporated MESSENGER data at Mercury and improved Mars data. |
+| DE431   | 2014 | -13200 to +17191       | Long-span version of DE430 for historical research.     |
+| DE440   | 2020 | 1550-2650              | Latest short-span ephemeris with Juno data at Jupiter.   |
+| DE441   | 2020 | -13200 to +17191       | Long-span version of DE440. Current standard.            |
+
+Short-span versions (DE440) are slightly more accurate than their long-span counterparts (DE441) because they can include the effect of the Moon's liquid core-mantle interaction, which dissipates over long timescales but matters for the highest precision over short intervals. The difference is sub-milliarcsecond and irrelevant for nearly all applications.
+
+### What the files contain
+
+All three ephemeris formats store the same fundamental data: positions (and sometimes velocities) of solar system bodies as functions of time. The difference is in representation and precision:
+
+**JPL files** store **Chebyshev polynomial coefficients** in fixed-length records. Each record covers a specific time interval (typically 32 days) and contains sets of polynomial coefficients for each body. To get a position at any time, the engine evaluates the Chebyshev polynomial for the relevant interval. The polynomials are fitted to the output of JPL's numerical integration to the full precision of the integration. Velocities are obtained by differentiating the polynomial.
+
+Bodies covered: Sun, Moon, Mercury through Pluto, lunar librations, and (in newer versions) the Earth-Moon nutation angles.
+
+**SE1 files** use the same Chebyshev polynomial approach but with compressed coefficients. The Swiss Ephemeris developers took the JPL data, verified it, and repackaged it with data compression (reducing precision from ~10 significant digits to ~8, still yielding milliarcsecond accuracy) and split it into separate files for planets, Moon, and asteroids. This dramatically reduces file sizes.
+
+**Moshier** uses completely different analytical expressions -- series expansions in powers of time fitted to the JPL ephemeris. No Chebyshev polynomials, no external data. The series terms are hard-coded in the library. For the planets, Moshier's implementation is based on Steve Moshier's adaptation of Jean Meeus's algorithms (themselves based on the VSOP87 planetary theory for planets and ELP 2000-85 for the Moon). The limited number of terms in the series expansion is what limits accuracy to about 1 arcsecond.
+
+### File sizes
+
+| Ephemeris     | Files needed                       | Total size (approx)  |
+|---------------|------------------------------------|-----------------------|
+| Moshier       | None                               | 0 (built-in)         |
+| SE1 (planets) | `sepl_18.se1`                      | ~500 KB              |
+| SE1 (Moon)    | `semo_18.se1`                      | ~1.2 MB              |
+| SE1 (asteroids) | `seas_18.se1`                    | varies               |
+| DE405         | `de405.eph` (or segments)          | ~55 MB               |
+| DE406         | `de406.eph`                        | ~190 MB              |
+| DE441         | `de441.eph`                        | ~2.6 GB              |
+| DE440         | `de440.eph`                        | ~115 MB              |
+
+### Accuracy comparison
+
+| Ephemeris | Planet accuracy (modern dates) | Moon accuracy  | Time range          |
+|-----------|-------------------------------|----------------|---------------------|
+| Moshier   | ~1 arcsecond                  | ~3 arcseconds  | ~3000 BCE-3000 CE   |
+| SE1       | ~0.001 arcsecond              | ~0.001 arcsec  | ~5400 BCE-5400 CE   |
+| DE441     | ~0.0001 arcsecond (inner planets) | ~0.001 arcsec | 13200 BCE-17191 CE |
+
+To put 1 arcsecond in perspective: at the distance of the Moon, 1 arcsecond corresponds to about 1.9 km on the lunar surface. At the distance of Mars at closest approach, it corresponds to about 530 km. For astrology, where positions are meaningful to about 1 arcminute (60 arcseconds), Moshier's 1-arcsecond accuracy is more than adequate.
+
+### Tidal acceleration and DE versions
+
+Different JPL ephemeris versions use different values for the tidal acceleration of the Moon (which affects long-term lunar motion). The Swiss Ephemeris automatically adjusts its internal tidal acceleration parameter to match the loaded ephemeris:
+
+| DE version     | Tidal acceleration (arcsec/cy^2) |
+|----------------|----------------------------------|
+| DE200          | -23.8946                         |
+| DE405/DE406    | -25.826                          |
+| DE421          | -25.85                           |
+| DE430/DE431    | -25.82                           |
+| DE440/DE441    | -25.936                          |
+
+This parameter affects Delta-T calculations and long-term lunar motion predictions. When a JPL or SE1 file is loaded, the appropriate value is set automatically.
+
+### When to use which ephemeris
+
+**Moshier (default)** -- Use for:
+- General astrological software
+- Mobile/web applications where you want to minimize download size
+- Quick calculations where sub-arcsecond precision is not needed
+- Dates within about 3000 BCE to 3000 CE
+
+**Swiss Ephemeris (SE1 files)** -- Use for:
+- Professional astrological software requiring milliarcsecond precision
+- Applications where you need both high precision and moderate file sizes
+- Date ranges up to about 5400 BCE to 5400 CE
+- Research requiring highly accurate historical positions
+
+**JPL (DE441 etc.)** -- Use for:
+- Scientific research
+- Verifying calculations against the "gold standard"
+- Space mission planning and navigation
+- Very long time spans (DE441 covers 26,000 years)
+- When you need the absolute highest precision available
+
+### Loading files in different environments
+
+**Node.js:**
+```typescript
+import { readFileSync } from 'fs';
+
+const data = readFileSync('ephe/sepl_18.se1');
+swe.loadEphemerisFile(data.buffer, 'sepl_18.se1');
+```
+
+**Browser (fetch):**
+```typescript
+const response = await fetch('/ephe/sepl_18.se1');
+const data = await response.arrayBuffer();
+swe.loadEphemerisFile(data, 'sepl_18.se1');
+```
+
+**Bundled (import):**
+If your build tool supports importing binary files as ArrayBuffers, you can bundle the SE1 files directly into your application. This is convenient for small files like `sepl_18.se1` (~500 KB).
+
+### SE1 file naming convention
+
+SE1 files follow a naming pattern where the number indicates the century range:
+
+| File         | Century coverage                  |
+|-------------|-----------------------------------|
+| `sepl_18.se1` | Planets, covering centuries 18-27 (1800-2700 CE) |
+| `semo_18.se1` | Moon, covering centuries 18-27    |
+| `sepl_06.se1` | Planets, covering centuries 6-17 (600-1800 CE) |
+
+For most modern-date applications, the `_18` files are sufficient. For historical work you may need additional files covering earlier centuries.
+
+### Multiple files can be loaded
+
+You can load multiple SE1 files simultaneously. The engine will use whichever file covers the requested date:
+
+```typescript
+import { readFileSync } from 'fs';
+
+// Load planet files for two century ranges
+swe.loadEphemerisFile(readFileSync('ephe/sepl_06.se1').buffer, 'sepl_06.se1');
+swe.loadEphemerisFile(readFileSync('ephe/sepl_18.se1').buffer, 'sepl_18.se1');
+
+// This works for dates in both ranges
+const jd1 = SwissEph.julianDay(1200, 6, 15, 12); // Uses sepl_06
+const jd2 = SwissEph.julianDay(2024, 6, 15, 12); // Uses sepl_18
+```
+
+### JPL file auto-detection
+
+When loading a JPL file, the library automatically detects the DE version, time span, and endianness. You do not need to specify which DE version you are loading -- the library reads this from the file header.
+
+```typescript
+swe.loadJplFile(data, 'de441.eph');
+// Internally, the library reads the header and configures itself for DE441
+```
+
+If the file name is not provided, the library attempts to use a default name. It is best practice to always provide the name.

package/src/SwissEph/UseCases/FixedStars.md

@@ -0,0 +1,300 @@
+# Fixed Stars
+
+Fixed stars are the distant suns that form the constellations. Despite the name "fixed," they are not truly stationary -- they have proper motion (their own movement through space), and their apparent positions shift slowly due to precession of the equinoxes. However, compared to planets, their motion is extremely slow (typically fractions of an arcsecond per year), so for most practical purposes they appear fixed against the celestial background.
+
+In astrology, certain bright stars have been considered significant for thousands of years. Conjunctions of planets with prominent stars like Regulus, Spica, Aldebaran, Antares, and Sirius are interpreted in natal and mundane astrology. In Vedic astrology, specific stars define the sidereal zodiac (the nakshatras).
+
+The Swiss Ephemeris includes a catalog of thousands of fixed stars with their positions, proper motions, and visual magnitudes.
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+
+// Look up Spica
+const spica = swe.fixedStar('Spica', jd);
+console.log(`Spica: ${spica.longitude.toFixed(4)} deg, magnitude visible from fixedStarMagnitude()`);
+console.log(`Full name: ${spica.starName}`);
+// Full name: "Spica,alVir" (traditional name, Bayer designation)
+
+// Get visual magnitude
+const mag = swe.fixedStarMagnitude('Spica');
+console.log(`Spica magnitude: ${mag.toFixed(2)}`);
+
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### Looking up several well-known stars
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 6, 21, 12); // Summer solstice 2024
+
+const starNames = [
+  'Aldebaran',   // alpha Tauri, "Eye of the Bull"
+  'Regulus',     // alpha Leonis, "Heart of the Lion"
+  'Spica',       // alpha Virginis
+  'Antares',     // alpha Scorpii, "Heart of the Scorpion"
+  'Sirius',      // alpha Canis Majoris, brightest star in the sky
+  'Fomalhaut',   // alpha Piscis Austrini, one of the "Royal Stars"
+  'Algol',       // beta Persei, the "Demon Star"
+  'Polaris',     // alpha Ursae Minoris, the North Star
+  'Vega',        // alpha Lyrae
+  'Canopus',     // alpha Carinae, second-brightest star
+];
+
+for (const name of starNames) {
+  const star = swe.fixedStar(name, jd);
+  const mag = swe.fixedStarMagnitude(name);
+  console.log(
+    `${name.padEnd(12)} lon: ${star.longitude.toFixed(4).padStart(9)} deg` +
+    `  lat: ${star.latitude.toFixed(4).padStart(8)} deg` +
+    `  mag: ${mag.toFixed(2)}`
+  );
+}
+
+swe.close();
+```
+
+### The starName field format
+
+When you call `fixedStar()`, the returned `starName` field contains the canonical name in the format `"traditional,Bayer"`. The traditional name is the common name (e.g., "Spica"), and the Bayer designation uses the Greek letter abbreviation and constellation abbreviation (e.g., "alVir" for alpha Virginis).
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+
+const star = swe.fixedStar('Regulus', jd);
+console.log(star.starName);
+// "Regulus,alLeo"
+// "Regulus" = traditional name
+// "alLeo"  = alpha Leonis (Bayer designation)
+
+swe.close();
+```
+
+### Searching by partial name
+
+You can pass a partial name and the engine will find the first matching star. The search is case-insensitive for the traditional name portion.
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+
+// Search by partial traditional name
+const result = swe.fixedStar('Alde', jd);
+console.log(result.starName); // "Aldebaran,alTau"
+
+swe.close();
+```
+
+### Searching by Bayer/Flamsteed designation
+
+You can also search by the Bayer designation. Prefix the search string with a comma to search the designation field:
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+
+// Search by Bayer designation: comma prefix tells the engine
+// to search the designation field
+const result = swe.fixedStar(',alTau', jd);
+console.log(result.starName); // "Aldebaran,alTau"
+
+const result2 = swe.fixedStar(',alCMa', jd);
+console.log(result2.starName); // "Sirius,alCMa"
+
+swe.close();
+```
+
+### Stars used for sidereal ayanamsas
+
+Several ayanamsa systems are defined by the position of a specific star. These stars are built into the engine and are used internally when computing star-based ayanamsas:
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_SIDM_TRUE_CITRA, SE_SIDM_TRUE_REVATI, SE_SIDM_TRUE_PUSHYA } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+
+// Spica (Citra in Sanskrit) -- defines SE_SIDM_TRUE_CITRA
+// In this system, Spica is fixed at exactly 0 deg Libra (180 deg)
+const spica = swe.fixedStar('Spica', jd);
+console.log(`Spica (Citra): ${spica.longitude.toFixed(4)} deg`);
+
+// Revati (zeta Piscium) -- defines SE_SIDM_TRUE_REVATI
+// In this system, Revati is fixed at exactly 29d50' Pisces (359.833 deg)
+const revati = swe.fixedStar(',zePs', jd);
+console.log(`Revati: ${revati.longitude.toFixed(4)} deg  (${revati.starName})`);
+
+// Pushya (delta Cancri) -- defines SE_SIDM_TRUE_PUSHYA
+// In this system, Pushya is fixed at exactly 16 deg Cancer (106 deg)
+const pushya = swe.fixedStar(',deCnc', jd);
+console.log(`Pushya: ${pushya.longitude.toFixed(4)} deg  (${pushya.starName})`);
+
+swe.close();
+```
+
+### Getting equatorial coordinates of a star
+
+```typescript
+import { SwissEph } from '../index';
+import { SEFLG_EQUATORIAL } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+
+const sirius = swe.fixedStar('Sirius', jd, SEFLG_EQUATORIAL);
+// longitude -> Right Ascension (degrees)
+// latitude  -> Declination (degrees)
+const raHours = sirius.longitude / 15;
+console.log(`Sirius RA:  ${raHours.toFixed(4)} hours`);
+console.log(`Sirius Dec: ${sirius.latitude.toFixed(4)} deg`);
+
+swe.close();
+```
+
+### fixedStar vs fixedStar2
+
+Both `fixedStar()` and `fixedStar2()` compute fixed star positions and accept the same parameters. They are functionally equivalent in this wrapper. The distinction comes from the original C library where `swe_fixstar2` used a slightly different internal search algorithm. You can use either one interchangeably.
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2024, 1, 1, 12);
+
+const r1 = swe.fixedStar('Regulus', jd);
+const r2 = swe.fixedStar2('Regulus', jd);
+
+console.log(`fixedStar:  ${r1.longitude.toFixed(6)}`);
+console.log(`fixedStar2: ${r2.longitude.toFixed(6)}`);
+// Both return identical results
+
+swe.close();
+```
+
+### Visual magnitude
+
+Visual magnitude measures how bright a star appears from Earth. Lower numbers are brighter. Negative magnitudes are very bright. The scale is logarithmic: a difference of 5 magnitudes corresponds to a factor of 100 in brightness.
+
+```typescript
+import { SwissEph } from '../index';
+
+const swe = new SwissEph();
+
+// Some notable magnitudes for reference:
+const stars = ['Sirius', 'Canopus', 'Vega', 'Polaris', 'Algol', 'Spica'];
+
+for (const name of stars) {
+  const mag = swe.fixedStarMagnitude(name);
+  console.log(`${name.padEnd(10)} magnitude: ${mag.toFixed(2)}`);
+}
+// Sirius is about -1.46 (very bright)
+// Polaris is about 2.02 (moderately bright)
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### What positions mean for fixed stars
+
+The return values for fixed stars are the same as for planets:
+
+| Field             | Meaning for fixed stars                                                    |
+|-------------------|----------------------------------------------------------------------------|
+| `longitude`       | Ecliptic longitude in degrees (0-360), or RA if `SEFLG_EQUATORIAL`        |
+| `latitude`        | Ecliptic latitude in degrees, or Declination if `SEFLG_EQUATORIAL`        |
+| `distance`        | Distance in AU (very large numbers for stars; 1 parsec = 206265 AU)       |
+| `longitudeSpeed`  | Annual proper motion in longitude, expressed as degrees per day            |
+| `latitudeSpeed`   | Annual proper motion in latitude, expressed as degrees per day             |
+| `distanceSpeed`   | Radial velocity contribution to distance change (degrees per day)         |
+| `starName`        | Canonical name: `"TraditionalName,BayerDesignation"`                      |
+
+### Why fixed star positions change
+
+Even though stars appear "fixed," their calculated ecliptic longitude changes over time for two reasons:
+
+1. **Precession of the equinoxes** (~50.3 arcseconds/year): The Earth's axis wobbles like a top with a period of about 25,800 years. This shifts the reference point (vernal equinox) that defines 0 degrees Aries in the tropical zodiac. All star longitudes increase by about 50.3"/year due to precession alone. This is by far the dominant effect.
+
+2. **Proper motion**: Each star has its own velocity through space. Most proper motions are tiny (under 1"/year), but a few nearby stars move noticeably. Barnard's Star has the largest proper motion at about 10.3"/year.
+
+### The Four Royal Stars
+
+In ancient Persian (Zoroastrian) astrology, four bright stars were considered the "Watchers" or "Royal Stars," roughly marking the four cardinal directions of the zodiac around 3000 BCE:
+
+- **Aldebaran** (Watcher of the East) -- currently ~10 degrees Gemini
+- **Regulus** (Watcher of the North) -- currently ~0 degrees Virgo
+- **Antares** (Watcher of the West) -- currently ~10 degrees Sagittarius
+- **Fomalhaut** (Watcher of the South) -- currently ~4 degrees Pisces
+
+Due to precession, these stars have moved about 40 degrees since the system was established.
+
+### Bayer designation abbreviations
+
+The Bayer designation uses abbreviated Greek letters and constellation names:
+
+| Abbreviation | Greek Letter | Example             |
+|-------------|--------------|---------------------|
+| al          | alpha        | alVir = alpha Virginis (Spica) |
+| be          | beta         | bePer = beta Persei (Algol)   |
+| ga          | gamma        | gaOri = gamma Orionis         |
+| de          | delta        | deCnc = delta Cancri          |
+| ep          | epsilon      | epCMa = epsilon Canis Majoris |
+| ze          | zeta         | zePs = zeta Piscium (Revati)  |
+
+Constellation abbreviations follow the standard IAU three-letter codes: Vir (Virgo), Leo (Leo), Tau (Taurus), Ori (Orion), CMa (Canis Major), etc.
+
+### Applicable flags
+
+Most flags that work with planets also work with fixed stars:
+
+- `SEFLG_EQUATORIAL` -- get Right Ascension and Declination
+- `SEFLG_XYZ` -- get Cartesian coordinates
+- `SEFLG_SIDEREAL` -- get sidereal position (requires `siderealMode` configured)
+- `SEFLG_J2000` -- refer to J2000 equinox
+- `SEFLG_NONUT` -- mean equinox of date (no nutation)
+- `SEFLG_RADIANS` -- angles in radians
+
+Flags that do not apply to fixed stars (they are silently ignored):
+- `SEFLG_HELCTR` -- stars are so distant that heliocentric/geocentric makes no difference
+- `SEFLG_TOPOCTR` -- similarly, topocentric parallax is negligible for stars
+- `SEFLG_TRUEPOS`, `SEFLG_NOABERR`, `SEFLG_NOGDEFL` -- aberration and light deflection do apply and can be toggled
+
+### Magnitude scale reference
+
+| Magnitude | Example                          |
+|-----------|----------------------------------|
+| -1.46     | Sirius (brightest star)          |
+| -0.72     | Canopus (second brightest)       |
+| 0.03      | Vega                             |
+| 0.08      | Capella                          |
+| 0.85      | Aldebaran                        |
+| 1.00      | Spica                            |
+| 1.06      | Antares                          |
+| 1.35      | Regulus                          |
+| 2.02      | Polaris                          |
+| 6.0       | Approximate naked-eye limit      |
+
+Lower magnitude = brighter. Each step of 1 magnitude = ~2.512x brightness difference.