siderust-js 0.1.0

package/siderust-node/index.d.ts

@@ -0,0 +1,623 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** Physical parameters of a solar-system planet. */
+export interface PlanetInfo {
+  /** Planet name. */
+  name: string
+  /** Mass in kilograms. */
+  massKg: number
+  /** Mean equatorial radius in kilometres. */
+  radiusKm: number
+  /** Semi-major axis in AU. */
+  semiMajorAxisAu: number
+  /** Orbital eccentricity. */
+  eccentricity: number
+  /** Orbital inclination in degrees. */
+  inclinationDeg: number
+}
+/**
+ * Get physical parameters for a named planet.
+ *
+ * Valid names: `"Mercury"`, `"Venus"`, `"Earth"`, `"Mars"`, `"Jupiter"`,
+ * `"Saturn"`, `"Uranus"`, `"Neptune"`.
+ *
+ * ```js
+ * const { getPlanet } = require('@siderust/siderust');
+ * const mars = getPlanet('Mars');
+ * console.log(mars.massKg, mars.radiusKm);
+ * ```
+ */
+export declare function getPlanet(name: string): PlanetInfo
+/** List the names of all available solar-system bodies for altitude/azimuth queries. */
+export declare function listBodies(): Array<string>
+/** A spherical direction (two angles in degrees) with a frame label. */
+export interface SphericalDirection {
+  /** First angle in degrees (Dec / polar / altitude). */
+  polarDeg: number
+  /** Second angle in degrees (RA / azimuth / longitude). */
+  azimuthDeg: number
+  /** Reference frame name. */
+  frame: string
+}
+/** Cartesian ECEF coordinates in metres. */
+export interface CartesianEcef {
+  /** X coordinate in metres. */
+  x: number
+  /** Y coordinate in metres. */
+  y: number
+  /** Z coordinate in metres. */
+  z: number
+}
+/**
+ * Transform a spherical direction between celestial reference frames.
+ *
+ * Supported source and destination frames: `"ICRS"`, `"EclipticMeanJ2000"`,
+ * `"EquatorialMeanJ2000"`, `"EquatorialMeanOfDate"`, `"EquatorialTrueOfDate"`.
+ *
+ * @param polarDeg   — Declination / polar angle in degrees.
+ * @param azimuthDeg — Right ascension / longitude in degrees.
+ * @param srcFrame   — Source frame name.
+ * @param dstFrame   — Destination frame name.
+ * @param jd         — Julian Date (needed for of-date frames; use J2000 = 2451545.0 for epoch-independent frames).
+ *
+ * ```js
+ * const { transformDirection } = require('@siderust/siderust');
+ * const result = transformDirection(38.78, 279.23, 'EquatorialMeanJ2000', 'EclipticMeanJ2000', 2451545.0);
+ * ```
+ */
+export declare function transformDirection(polarDeg: number, azimuthDeg: number, srcFrame: string, dstFrame: string, jd: number): SphericalDirection
+/**
+ * Transform a spherical direction to the local Horizontal frame.
+ *
+ * @returns `{ polarDeg, azimuthDeg, frame }` where polarDeg is altitude
+ * and azimuthDeg is azimuth (N=0° E=90°).
+ */
+export declare function directionToHorizontal(polarDeg: number, azimuthDeg: number, srcFrame: string, jd: number, observer: JsObserver): SphericalDirection
+/**
+ * Convert a geodetic position (WGS84) to ECEF Cartesian coordinates.
+ *
+ * @param observer — Observer with lon/lat/height.
+ * @returns `{ x, y, z }` in metres.
+ */
+export declare function geodeticToEcef(observer: JsObserver): CartesianEcef
+/**
+ * Compute the angular separation between two spherical directions (Vincenty formula).
+ *
+ * Both directions must be in the same reference frame.
+ *
+ * @param polar1Deg   — Declination / polar angle of first direction in degrees.
+ * @param azimuth1Deg — RA / azimuth of first direction in degrees.
+ * @param polar2Deg   — Declination / polar angle of second direction in degrees.
+ * @param azimuth2Deg — RA / azimuth of second direction in degrees.
+ * @param frame       — Reference frame (both directions must share the same frame).
+ * @returns Angular separation in degrees.
+ *
+ * ```js
+ * const { angularSeparation } = require('@siderust/siderust');
+ * const sep = angularSeparation(89.26, 37.95, -16.72, 101.29, 'EquatorialMeanJ2000');
+ * ```
+ */
+export declare function angularSeparation(polar1Deg: number, azimuth1Deg: number, polar2Deg: number, azimuth2Deg: number, frame: string): number
+/**
+ * Compute the Euclidean distance between two 3D Cartesian positions.
+ *
+ * The positions must be in the same frame and center. Units follow input.
+ *
+ * @returns Distance in the same units as the input coordinates.
+ */
+export declare function cartesianDistance(x1: number, y1: number, z1: number, x2: number, y2: number, z2: number): number
+/**
+ * Compute the magnitude (distance from origin) of a 3D Cartesian vector.
+ *
+ * @returns Distance from origin in the same units.
+ */
+export declare function cartesianMagnitude(x: number, y: number, z: number): number
+/**
+ * Compute the dot product of two 3D Cartesian vectors.
+ *
+ * @returns The scalar dot product.
+ */
+export declare function dotProduct(x1: number, y1: number, z1: number, x2: number, y2: number, z2: number): number
+/**
+ * Convert a direction (unit vector) from spherical to Cartesian.
+ *
+ * @param polarDeg   — Declination / polar angle in degrees.
+ * @param azimuthDeg — RA / azimuth in degrees.
+ * @returns `{ x, y, z }` unit vector.
+ */
+export declare function directionToCartesian(polarDeg: number, azimuthDeg: number): CartesianEcef
+/** A 3D Cartesian position with frame and center metadata. */
+export interface CartesianPosition {
+  /** X coordinate (AU for solar-system, km for Moon geocentric). */
+  x: number
+  /** Y coordinate. */
+  y: number
+  /** Z coordinate. */
+  z: number
+  /** Reference frame (e.g. `"EclipticMeanJ2000"`). */
+  frame: string
+  /** Reference center (e.g. `"Heliocentric"`, `"Barycentric"`, `"Geocentric"`). */
+  center: string
+}
+/**
+ * Compute the heliocentric ecliptic position of a planet via VSOP87 (Series A).
+ *
+ * Returns Cartesian coordinates in AU, in the EclipticMeanJ2000 frame,
+ * centered on the Sun.
+ *
+ * @param body — Planet name: Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune.
+ * @param jd   — Julian Date of the epoch.
+ *
+ * ```js
+ * const { vsop87Heliocentric } = require('@siderust/siderust');
+ * const mars = vsop87Heliocentric('Mars', 2451545.0);
+ * console.log(mars.x, mars.y, mars.z);
+ * ```
+ */
+export declare function vsop87Heliocentric(body: string, jd: number): CartesianPosition
+/**
+ * Compute the barycentric ecliptic position of a planet via VSOP87 (Series E).
+ *
+ * Returns Cartesian coordinates in AU, in the EclipticMeanJ2000 frame,
+ * centered on the solar-system barycentre.
+ *
+ * @param body — Planet name or `"Sun"`.
+ * @param jd   — Julian Date of the epoch.
+ */
+export declare function vsop87Barycentric(body: string, jd: number): CartesianPosition
+/**
+ * Get the Sun's barycentric position via VSOP87.
+ *
+ * @param jd — Julian Date.
+ * @returns Cartesian position in AU (EclipticMeanJ2000, Barycentric).
+ */
+export declare function vsop87SunBarycentric(jd: number): CartesianPosition
+/**
+ * Get the Earth's barycentric position via VSOP87.
+ *
+ * @param jd — Julian Date.
+ * @returns Cartesian position in AU (EclipticMeanJ2000, Barycentric).
+ */
+export declare function vsop87EarthBarycentric(jd: number): CartesianPosition
+/**
+ * Get the Earth's heliocentric position via VSOP87.
+ *
+ * @param jd — Julian Date.
+ * @returns Cartesian position in AU (EclipticMeanJ2000, Heliocentric).
+ */
+export declare function vsop87EarthHeliocentric(jd: number): CartesianPosition
+/**
+ * Get the Moon's geocentric position via ELP2000.
+ *
+ * @param jd — Julian Date.
+ * @returns Cartesian position in **km** (EclipticMeanJ2000, Geocentric).
+ */
+export declare function vsop87MoonGeocentric(jd: number): CartesianPosition
+/**
+ * Transform a Cartesian position from one reference center to another.
+ *
+ * Stays in the EclipticMeanJ2000 frame (the natural VSOP87 frame).
+ * Units are AU (except Geocentric Moon which is km).
+ *
+ * Supported center pairs: Heliocentric ↔ Geocentric, Heliocentric ↔ Barycentric,
+ * Geocentric ↔ Barycentric.
+ *
+ * @param x, y, z       — Cartesian coordinates.
+ * @param srcCenter      — Source center: `"Heliocentric"`, `"Barycentric"`, `"Geocentric"`.
+ * @param dstCenter      — Destination center.
+ * @param jd             — Julian Date.
+ *
+ * ```js
+ * const mars = vsop87Heliocentric('Mars', 2451545.0);
+ * const marsGeo = transformPositionCenter(mars.x, mars.y, mars.z, 'Heliocentric', 'Geocentric', 2451545.0);
+ * ```
+ */
+export declare function transformPositionCenter(x: number, y: number, z: number, srcCenter: string, dstCenter: string, jd: number): CartesianPosition
+/**
+ * Transform a Cartesian position between celestial reference frames.
+ *
+ * Stays in the same center. Coordinates are in AU.
+ *
+ * Supported frames: `"ICRS"`, `"EclipticMeanJ2000"`, `"EquatorialMeanJ2000"`.
+ *
+ * @param x, y, z    — Cartesian coordinates in AU.
+ * @param srcFrame    — Source frame name.
+ * @param dstFrame    — Destination frame name.
+ * @param jd          — Julian Date.
+ */
+export declare function transformPositionFrame(x: number, y: number, z: number, srcFrame: string, dstFrame: string, jd: number): CartesianPosition
+/**
+ * Compute the orbital period of a named planet in days (Keplerian).
+ *
+ * @param name — Planet name.
+ * @returns Orbital period in days.
+ */
+export declare function orbitalPeriodDays(name: string): number
+/** A threshold-crossing event (rise or set). */
+export interface CrossingEvent {
+  /** Time of the crossing (Modified Julian Date). */
+  mjd: number
+  /** Direction: `"rising"` or `"setting"`. */
+  direction: string
+}
+/** A culmination event (local altitude extremum). */
+export interface CulminationEvent {
+  /** Time of the culmination (Modified Julian Date). */
+  mjd: number
+  /** Altitude at the extremum in degrees. */
+  altitudeDeg: number
+  /** Kind: `"max"` (upper culmination) or `"min"` (lower culmination). */
+  kind: string
+}
+/** A time period (MJD interval). */
+export interface MjdPeriod {
+  /** Start of the period (Modified Julian Date). */
+  startMjd: number
+  /** End of the period (Modified Julian Date). */
+  endMjd: number
+}
+/** An azimuth-crossing event. */
+export interface AzimuthCrossingEvent {
+  /** Time of the event (Modified Julian Date). */
+  mjd: number
+  /** Crossing direction: `"rising"` or `"setting"`. */
+  direction: string
+}
+/** An azimuth extremum (local max or min bearing). */
+export interface AzimuthExtremum {
+  /** Time of the extremum (Modified Julian Date). */
+  mjd: number
+  /** Azimuth at the extremum in degrees. */
+  azimuthDeg: number
+  /** Kind: `"max"` or `"min"`. */
+  kind: string
+}
+/**
+ * Compute the altitude of a solar-system body at a single instant.
+ *
+ * @param body     — Body name (e.g. `"Sun"`, `"Moon"`, `"Mars"`).
+ * @param observer — Observer location.
+ * @param mjd      — Modified Julian Date of the instant.
+ * @returns Altitude in degrees.
+ *
+ * ```js
+ * const { Observer, bodyAltitudeAt } = require('@siderust/siderust');
+ * const obs = Observer.roqueDeLasMuchachos();
+ * const alt = bodyAltitudeAt('Sun', obs, 60000.0);
+ * ```
+ */
+export declare function bodyAltitudeAt(body: string, observer: JsObserver, mjd: number): number
+/**
+ * Compute the azimuth of a solar-system body at a single instant.
+ *
+ * @returns Azimuth in degrees (north = 0°, east = 90°).
+ */
+export declare function bodyAzimuthAt(body: string, observer: JsObserver, mjd: number): number
+/**
+ * Find threshold-crossing events (rise/set) for a solar-system body.
+ *
+ * @param body         — Body name.
+ * @param observer     — Observer location.
+ * @param startMjd     — Window start (MJD).
+ * @param endMjd       — Window end (MJD).
+ * @param thresholdDeg — Altitude threshold in degrees (e.g. 0 for horizon).
+ * @returns Array of crossing events `{ mjd, direction }`.
+ */
+export declare function bodyCrossings(body: string, observer: JsObserver, startMjd: number, endMjd: number, thresholdDeg: number): Array<CrossingEvent>
+/**
+ * Find culmination events (altitude local extrema) for a solar-system body.
+ *
+ * @returns Array of culmination events `{ mjd, altitudeDeg, kind }`.
+ */
+export declare function bodyCulminations(body: string, observer: JsObserver, startMjd: number, endMjd: number): Array<CulminationEvent>
+/**
+ * Find periods where a body's altitude is above a threshold.
+ *
+ * @returns Array of MJD periods `{ startMjd, endMjd }`.
+ */
+export declare function bodyAboveThreshold(body: string, observer: JsObserver, startMjd: number, endMjd: number, thresholdDeg: number): Array<MjdPeriod>
+/**
+ * Find periods where a body's altitude is below a threshold.
+ *
+ * @returns Array of MJD periods `{ startMjd, endMjd }`.
+ */
+export declare function bodyBelowThreshold(body: string, observer: JsObserver, startMjd: number, endMjd: number, thresholdDeg: number): Array<MjdPeriod>
+/**
+ * Find azimuth-crossing events for a body.
+ *
+ * @param bearingDeg — Target azimuth bearing in degrees.
+ * @returns Array of azimuth crossing events `{ mjd, direction }`.
+ */
+export declare function bodyAzimuthCrossings(body: string, observer: JsObserver, startMjd: number, endMjd: number, bearingDeg: number): Array<AzimuthCrossingEvent>
+/**
+ * Find azimuth extrema (max/min bearing) for a body.
+ *
+ * @returns Array of azimuth extrema `{ mjd, azimuthDeg, kind }`.
+ */
+export declare function bodyAzimuthExtrema(body: string, observer: JsObserver, startMjd: number, endMjd: number): Array<AzimuthExtremum>
+/**
+ * Compute the altitude of a catalog or custom star at a single instant.
+ *
+ * @returns Altitude in degrees.
+ */
+export declare function starAltitudeAt(star: JsStar, observer: JsObserver, mjd: number): number
+/**
+ * Compute the azimuth of a star at a single instant.
+ *
+ * @returns Azimuth in degrees.
+ */
+export declare function starAzimuthAt(star: JsStar, observer: JsObserver, mjd: number): number
+/** Find threshold-crossing events for a star. */
+export declare function starCrossings(star: JsStar, observer: JsObserver, startMjd: number, endMjd: number, thresholdDeg: number): Array<CrossingEvent>
+/** Find culmination events for a star. */
+export declare function starCulminations(star: JsStar, observer: JsObserver, startMjd: number, endMjd: number): Array<CulminationEvent>
+/** Find periods where a star's altitude is above a threshold. */
+export declare function starAboveThreshold(star: JsStar, observer: JsObserver, startMjd: number, endMjd: number, thresholdDeg: number): Array<MjdPeriod>
+/** Find periods where a star's altitude is below a threshold. */
+export declare function starBelowThreshold(star: JsStar, observer: JsObserver, startMjd: number, endMjd: number, thresholdDeg: number): Array<MjdPeriod>
+/**
+ * Find azimuth-crossing events for a star.
+ *
+ * @param bearingDeg — Target azimuth bearing in degrees.
+ * @returns Array of azimuth crossing events `{ mjd, direction }`.
+ */
+export declare function starAzimuthCrossings(star: JsStar, observer: JsObserver, startMjd: number, endMjd: number, bearingDeg: number): Array<AzimuthCrossingEvent>
+/**
+ * Find azimuth extrema (max/min bearing) for a star.
+ *
+ * @returns Array of azimuth extrema `{ mjd, azimuthDeg, kind }`.
+ */
+export declare function starAzimuthExtrema(star: JsStar, observer: JsObserver, startMjd: number, endMjd: number): Array<AzimuthExtremum>
+/**
+ * Intersect two lists of MJD periods, returning only overlapping intervals.
+ *
+ * This is useful for combining altitude and azimuth constraints, or
+ * combining target visibility with astronomical night periods.
+ *
+ * @param periods1 — First list of MJD periods.
+ * @param periods2 — Second list of MJD periods.
+ * @returns Array of MJD periods representing the intersection.
+ *
+ * ```js
+ * const altPeriods = starAboveThreshold(star, obs, mjd0, mjd1, 25);
+ * const azPeriods = bodyAboveThreshold('Sun', obs, mjd0, mjd1, -18); // dark sky
+ * const observable = intersectPeriods(altPeriods, azPeriods);
+ * ```
+ */
+export declare function intersectPeriods(periods1: Array<MjdPeriod>, periods2: Array<MjdPeriod>): Array<MjdPeriod>
+/** Moon phase geometry at a single instant. */
+export interface MoonPhase {
+  /** Phase angle in degrees (Sun-Moon-Earth/observer angle). */
+  phaseAngleDeg: number
+  /** Fraction of the disk illuminated [0, 1]. */
+  illuminatedFraction: number
+  /** Elongation in degrees (eastward from the Sun). */
+  elongationDeg: number
+  /** Whether the Moon is waxing. */
+  waxing: boolean
+  /** Named phase label (e.g. `"FullMoon"`, `"WaxingCrescent"`). */
+  label: string
+}
+/** A principal lunar phase event (New Moon, First Quarter, Full Moon, Last Quarter). */
+export interface PhaseEvent {
+  /** Time of the event (Modified Julian Date). */
+  mjd: number
+  /** Phase kind: `"NewMoon"`, `"FirstQuarter"`, `"FullMoon"`, `"LastQuarter"`. */
+  kind: string
+}
+/**
+ * Compute geocentric Moon phase geometry at a Julian Date.
+ *
+ * @param jd — Julian Date.
+ * @returns Phase geometry including illumination, elongation, and named label.
+ *
+ * ```js
+ * const { moonPhase } = require('@siderust/siderust');
+ * const phase = moonPhase(2451545.0);
+ * console.log(phase.label, phase.illuminatedFraction);
+ * ```
+ */
+export declare function moonPhase(jd: number): MoonPhase
+/**
+ * Compute topocentric Moon phase geometry at a Julian Date for an observer.
+ *
+ * @param jd       — Julian Date.
+ * @param observer — Observer location on Earth.
+ */
+export declare function moonPhaseTopocentric(jd: number, observer: Observer): MoonPhase
+/**
+ * Find all principal lunar phase events in a time window.
+ *
+ * @param startMjd — Window start (MJD).
+ * @param endMjd   — Window end (MJD).
+ * @returns Sorted array of `{ mjd, kind }` events.
+ *
+ * ```js
+ * const { findPhaseEvents } = require('@siderust/siderust');
+ * const events = findPhaseEvents(60000.0, 60030.0);  // ~1 month
+ * events.forEach(e => console.log(e.kind, e.mjd));
+ * ```
+ */
+export declare function findPhaseEvents(startMjd: number, endMjd: number): Array<PhaseEvent>
+/**
+ * Find periods where geocentric Moon illumination is above `kMin` ∈ [0, 1].
+ *
+ * @param startMjd — Window start (MJD).
+ * @param endMjd   — Window end (MJD).
+ * @param kMin     — Minimum illumination fraction.
+ * @returns Array of MJD periods.
+ */
+export declare function moonIlluminationAbove(startMjd: number, endMjd: number, kMin: number): Array<MjdPeriod>
+/** Find periods where geocentric Moon illumination is below `kMax` ∈ [0, 1]. */
+export declare function moonIlluminationBelow(startMjd: number, endMjd: number, kMax: number): Array<MjdPeriod>
+/** Find periods where geocentric Moon illumination is in `[kMin, kMax]`. */
+export declare function moonIlluminationRange(startMjd: number, endMjd: number, kMin: number, kMax: number): Array<MjdPeriod>
+/** List all catalog star names. */
+export declare function listCatalogStars(): Array<string>
+/** Return the siderust-node version string. */
+export declare function version(): string
+export type JsObserver = Observer
+/**
+ * A geodetic observer location on the Earth's surface (WGS84 ellipsoid).
+ *
+ * Used as the reference site for all topocentric computations: altitude,
+ * azimuth, crossings, culminations, and coordinate transforms to the
+ * Horizontal frame.
+ *
+ * ```js
+ * const { Observer } = require('@siderust/siderust');
+ *
+ * // Custom site
+ * const obs = new Observer(-17.8925, 28.7543, 2396);
+ *
+ * // Preset observatory
+ * const orm = Observer.roqueDeLasMuchachos();
+ * ```
+ */
+export declare class Observer {
+  /**
+   * Create an observer at a geodetic position.
+   *
+   * @param lonDeg   — Longitude in degrees (east positive).
+   * @param latDeg   — Latitude in degrees (north positive).
+   * @param heightM  — Height above WGS84 ellipsoid in metres.
+   */
+  constructor(lonDeg: number, latDeg: number, heightM: number)
+  /**
+   * Roque de los Muchachos Observatory (La Palma, Spain).
+   *
+   * Longitude −17.8925°, Latitude +28.7543°, Altitude 2396 m.
+   */
+  static roqueDeLasMuchachos(): JsObserver
+  /**
+   * Paranal Observatory (ESO, Chile).
+   *
+   * Longitude −70.4043°, Latitude −24.6272°, Altitude 2635 m.
+   */
+  static elParanal(): JsObserver
+  /**
+   * Mauna Kea Observatory (Hawaiʻi, USA).
+   *
+   * Longitude −155.4681°, Latitude +19.8207°, Altitude 4207 m.
+   */
+  static maunaKea(): JsObserver
+  /**
+   * La Silla Observatory (ESO, Chile).
+   *
+   * Longitude −70.7346°, Latitude −29.2584°, Altitude 2400 m.
+   */
+  static laSilla(): JsObserver
+  /** Longitude in degrees (east positive). */
+  get lonDeg(): number
+  /** Latitude in degrees (north positive). */
+  get latDeg(): number
+  /** Height above the WGS84 ellipsoid in metres. */
+  get heightM(): number
+  /** Human-readable string representation. */
+  format(): string
+}
+/**
+ * A 3D cartesian position with frame, center, and unit metadata.
+ *
+ * This mirrors the Python `Position` type for API parity.
+ */
+export declare class Position {
+  /** Create a new position with explicit coordinates, frame, center, and unit. */
+  constructor(x: number, y: number, z: number, frame: string, center: string, unit: string)
+  /** X coordinate. */
+  get x(): number
+  /** Y coordinate. */
+  get y(): number
+  /** Z coordinate. */
+  get z(): number
+  /** Reference frame (e.g., "EclipticMeanJ2000", "ICRS"). */
+  get frame(): string
+  /** Coordinate center (e.g., "Barycentric", "Heliocentric", "Geocentric"). */
+  get center(): string
+  /** Distance unit ("au" or "km"). */
+  get unit(): string
+  /** Euclidean distance from origin. */
+  magnitude(): number
+  /** Subtract another position to get a displacement vector. */
+  subtract(other: Position): Displacement
+  /** Add a displacement to get a new position. */
+  addDisplacement(d: Displacement): Position
+}
+/** A displacement vector (difference between two positions). */
+export declare class Displacement {
+  /** Create a new displacement. */
+  constructor(dx: number, dy: number, dz: number, frame: string, unit: string)
+  /** X component of displacement. */
+  get dx(): number
+  /** Y component of displacement. */
+  get dy(): number
+  /** Z component of displacement. */
+  get dz(): number
+  /** Reference frame. */
+  get frame(): string
+  /** Distance unit. */
+  get unit(): string
+  /** Euclidean magnitude. */
+  magnitude(): number
+  /** Scale displacement by a factor. */
+  scale(factor: number): Displacement
+  /** Add another displacement. */
+  add(other: Displacement): Displacement
+}
+export type JsStar = Star
+/**
+ * A star with physical parameters and sky coordinates.
+ *
+ * Use the factory methods to look up well-known stars from the built-in
+ * catalog, or the constructor to define custom stars.
+ *
+ * ```js
+ * const { Star } = require('@siderust/siderust');
+ *
+ * // Catalog look-up
+ * const vega = Star.catalog('Vega');
+ *
+ * // Custom star
+ * const custom = new Star('MyStar', 100, 1.5, 1.2, 3.0, 200.0, 45.0);
+ * ```
+ */
+export declare class Star {
+  /**
+   * Create a custom star.
+   *
+   * @param name        — Display name.
+   * @param distanceLy  — Distance in light-years.
+   * @param massSolar   — Mass in solar masses (M☉).
+   * @param radiusSolar — Radius in solar radii (R☉).
+   * @param luminositySolar — Luminosity in solar luminosities (L☉).
+   * @param raDeg       — Right ascension at J2000.0 in degrees.
+   * @param decDeg      — Declination at J2000.0 in degrees.
+   */
+  constructor(name: string, distanceLy: number, massSolar: number, radiusSolar: number, luminositySolar: number, raDeg: number, decDeg: number)
+  /**
+   * Look up a star from the built-in catalog by name.
+   *
+   * Supported names (case-insensitive): Vega, Sirius, Polaris, Canopus,
+   * Arcturus, Rigel, Betelgeuse, Procyon, Aldebaran, Altair.
+   */
+  static catalog(name: string): JsStar
+  /** Star name. */
+  get name(): string
+  /** Distance in light-years. */
+  get distanceLy(): number
+  /** Mass in solar masses (M☉). */
+  get massSolar(): number
+  /** Radius in solar radii (R☉). */
+  get radiusSolar(): number
+  /** Luminosity in solar luminosities (L☉). */
+  get luminositySolar(): number
+  /** Right ascension at J2000.0 in degrees. */
+  get raDeg(): number
+  /** Declination at J2000.0 in degrees. */
+  get decDeg(): number
+  /** Human-readable representation. */
+  format(): string
+}