@motioncomplex/cosmos-lib 1.0.9

package/README.md

@@ -0,0 +1,125 @@
+# cosmos-lib
+
+[![npm version](https://img.shields.io/npm/v/@motioncomplex/cosmos-lib.svg)](https://www.npmjs.com/package/@motioncomplex/cosmos-lib)
+[![npm downloads](https://img.shields.io/npm/dm/@motioncomplex/cosmos-lib.svg)](https://www.npmjs.com/package/@motioncomplex/cosmos-lib)
+[![license](https://img.shields.io/npm/l/@motioncomplex/cosmos-lib.svg)](https://github.com/MotionComplex/cosmos-lib/blob/main/LICENSE)
+
+Reusable TypeScript library for astronomical data, coordinate math, sky maps, NASA/ESA APIs, media loading, and UI transitions. Zero runtime dependencies — Three.js and React support are optional peer dependencies in separate entry points.
+
+## Install
+
+```bash
+npm install @motioncomplex/cosmos-lib
+```
+
+Optional peer dependencies (only install what you use):
+
+```bash
+npm install three    # for cosmos-lib/three (3D scene helpers)
+npm install react    # for cosmos-lib/react (React hooks & components)
+```
+
+## Quick start
+
+```ts
+import Cosmos from '@motioncomplex/cosmos-lib'
+
+// Search the built-in catalog (300+ stars, 110 Messier, 88 constellations)
+const results = Cosmos.Data.search('orion')
+const nebulae = Cosmos.Data.getByType('nebula')
+const near    = Cosmos.Data.nearby({ ra: 83.8, dec: -5.4 }, 20)
+
+// Coordinate transforms
+const { alt, az } = Cosmos.Math.equatorialToHorizontal(
+  { ra: 101.287, dec: -16.716 },                // Sirius
+  { lat: 47.05,  lng: 8.31, date: new Date() }  // Lucerne
+)
+
+// Sun, Moon & eclipses
+const sunPos    = Cosmos.Sun.position()
+const moonPhase = Cosmos.Moon.phase()
+const twilight  = Cosmos.Sun.twilight({ lat: 51.5, lng: -0.1 })
+
+// NASA APIs
+const apod = await Cosmos.API.NASA.apod()
+const imgs = await Cosmos.API.NASA.searchImages('pillars of creation', { pageSize: 5 })
+```
+
+## Tree-shakeable named exports
+
+```ts
+import { AstroMath, Data, NASA, Units, renderSkyMap, staggerIn } from '@motioncomplex/cosmos-lib'
+```
+
+## React hooks (optional)
+
+```ts
+import { useSkyPosition, useMoonPhase, useWhatsUp, useTwilight, SkyMap } from '@motioncomplex/cosmos-lib/react'
+
+// Reactive sky position — auto-updates every 10s
+const pos = useSkyPosition('sirius', { lat: 47.05, lng: 8.31 })
+
+// What's visible tonight?
+const visible = useWhatsUp({ lat: 47.05, lng: 8.31 }, { magnitudeLimit: 4 })
+```
+
+## Three.js helpers (optional)
+
+```ts
+import { createPlanet, LODTextureManager, CameraFlight } from '@motioncomplex/cosmos-lib/three'
+import * as THREE from 'three'
+
+const { group, dispose } = createPlanet({
+  radius: 6.5,
+  textureUrl: 'earth-bluemarble-4k.jpg',
+  atmosphere: { color: 0x4488ff, intensity: 1.3 },
+}, THREE)
+scene.add(group)
+```
+
+## Features
+
+| Module | Description | Docs |
+|--------|-------------|------|
+| **Data** | 300+ bright stars, 110 Messier objects, 88 constellations, 20 meteor showers, solar system bodies. Fuzzy search, proximity queries, image resolution. | [Data](docs/api/data.md) |
+| **AstroMath** | Julian dates, sidereal time, coordinate transforms (equatorial, horizontal, galactic, ecliptic), Kepler solver, planetary ephemeris, precession, nutation, refraction, rise/transit/set. | [Math](docs/api/math.md) |
+| **Sun / Moon / Eclipse** | Solar & lunar positions, moon phases, twilight times, eclipse prediction. | [Sun/Moon/Eclipse](docs/api/sun-moon-eclipse.md) |
+| **NASA / ESA / Simbad** | NASA Image Library, APOD, ESA Hubble archive, CDS Simbad object resolution. | [API Integrations](docs/api/api-integrations.md) |
+| **Planner** | "What's up tonight?" — visible objects, best observation windows, visibility curves, moon interference scoring, airmass, planet oppositions/conjunctions. | [Planner](docs/api/planner.md) |
+| **AstroClock** | Simulation clock with speed control, forward/reverse playback, snap-to-event, and requestAnimationFrame support. | [Clock](docs/api/clock.md) |
+| **Sky Map** | Stereographic, Mollweide, and gnomonic projections. Interactive canvas sky chart with pan, zoom, click-to-identify, FOV overlays, HUD, and real-time tracking. | [Sky Map](docs/api/skymap.md) |
+| **React Hooks** | `useSkyPosition`, `useMoonPhase`, `useAstroClock`, `useWhatsUp`, `useTwilight`, `<SkyMap />`. SSR-safe. Optional peer dependency. | [React](docs/api/react.md) |
+| **Media** | Progressive image loading with fallback chains, Wikimedia/Cloudinary URL builders, responsive `srcset` generation. | [Media](docs/api/media.md) |
+| **Transitions** | View Transitions API wrappers: morph, stagger reveal, fade, crossfade, hero expand/collapse. | [Transitions](docs/api/transitions.md) |
+| **Three.js** | Planet/nebula/starfield factories, LOD texture management, camera flights. Optional peer dependency. | [Three.js](docs/api/three.md) |
+| **Constants & Units** | Astronomical constants (IAU 2012), distance/angle conversions, RA/Dec formatters. | [Constants & Units](docs/api/constants-and-units.md) |
+
+## Documentation
+
+Full documentation lives in the [`docs/`](docs/README.md) folder:
+
+- [Getting Started](docs/getting-started.md) — installation, import patterns, quick start
+- [API Reference](docs/README.md#api-reference) — per-module docs with signatures, parameters, and examples
+- [Guides](docs/README.md#guides) — conceptual walkthroughs for coordinate systems, catalog data, and Three.js integration
+- [Type Reference](docs/types.md) — quick-reference table of all exported types
+
+Generate HTML API docs from TSDoc comments:
+
+```bash
+npm run docs
+```
+
+## Development
+
+```bash
+npm install
+npm test              # run tests
+npm run test:watch    # watch mode
+npm run typecheck     # tsc --noEmit
+npm run build         # compile to dist/
+npm run docs          # generate TypeDoc API reference
+```
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,246 @@
+import type { NASAImageResult, APODResult, ESAHubbleResult, SimbadResult } from './types.js';
+/**
+ * Options for filtering and paginating NASA Image and Video Library searches.
+ *
+ * @see {@link NASA.searchImages} for usage.
+ */
+export interface NASASearchOptions {
+    /** Media type filter. Defaults to `'image'`. */
+    mediaType?: 'image' | 'video' | 'audio';
+    /** Restrict results to items published on or after this year. */
+    yearStart?: number;
+    /** Restrict results to items published on or before this year. */
+    yearEnd?: number;
+    /** Number of results per page. Defaults to `10`. */
+    pageSize?: number;
+    /** 1-based page number for pagination. Defaults to `1`. */
+    page?: number;
+}
+/**
+ * Client for the NASA public APIs, including the Image and Video Library
+ * and the Astronomy Picture of the Day (APOD) service.
+ *
+ * By default requests use the `DEMO_KEY` API key, which is subject to
+ * strict rate limits. Call {@link NASA.setApiKey} with a free key from
+ * {@link https://api.nasa.gov} before making production requests.
+ *
+ * @example
+ * ```ts
+ * import { NASA } from 'cosmos-lib'
+ *
+ * NASA.setApiKey('your-api-key')
+ * const results = await NASA.searchImages('pillars of creation')
+ * console.log(results[0].title)
+ * ```
+ */
+export declare const NASA: {
+    /**
+     * Set the NASA API key used for APOD requests.
+     *
+     * The default key (`DEMO_KEY`) is heavily rate-limited (30 req/hr,
+     * 50 req/day). Register for a free key at {@link https://api.nasa.gov}
+     * to raise these limits to 1,000 req/hr.
+     *
+     * @param key - Your NASA API key.
+     *
+     * @example
+     * ```ts
+     * NASA.setApiKey('Ab12Cd34Ef56Gh78Ij90KlMnOpQrStUvWxYz0123')
+     * ```
+     */
+    setApiKey(key: string): void;
+    /**
+     * Search the NASA Image and Video Library.
+     *
+     * Queries the public NASA images API and returns an array of
+     * {@link NASAImageResult} objects containing metadata and preview URLs.
+     *
+     * @param query - Free-text search term (e.g. `'pillars of creation'`).
+     * @param opts  - Optional filters and pagination settings.
+     *
+     * @returns An array of search results. An empty array is returned when
+     *          the query matches nothing.
+     *
+     * @throws {Error} If the NASA API responds with a non-2xx status code.
+     *
+     * @example
+     * ```ts
+     * const results = await NASA.searchImages('pillars of creation', {
+     *   yearStart: 2010,
+     *   pageSize: 5,
+     * })
+     * for (const r of results) {
+     *   console.log(r.title, r.previewUrl)
+     * }
+     * ```
+     *
+     * @see {@link https://images.nasa.gov/docs/images.nasa.gov_api_docs.pdf | NASA Image API docs}
+     */
+    searchImages(query: string, opts?: NASASearchOptions): Promise<NASAImageResult[]>;
+    /**
+     * Fetch all asset URLs for a given NASA image ID.
+     *
+     * Returns the full list of available renditions (JPEG, TIFF, etc.)
+     * sorted by quality: original, large, medium, small, then thumbnail.
+     *
+     * @param nasaId - The NASA-assigned identifier (e.g. `'PIA06890'`).
+     *
+     * @returns An array of absolute URLs sorted from highest to lowest quality.
+     *
+     * @throws {Error} If the NASA asset endpoint responds with a non-2xx status.
+     *
+     * @example
+     * ```ts
+     * const urls = await NASA.getAssets('PIA06890')
+     * console.log(urls[0]) // highest quality rendition
+     * ```
+     */
+    getAssets(nasaId: string): Promise<string[]>;
+    /**
+     * Convenience helper that returns the single highest-quality image URL
+     * for a NASA asset ID.
+     *
+     * Internally calls {@link NASA.getAssets} and filters for image file
+     * extensions (JPEG, PNG, GIF, TIFF), returning the first match (which
+     * is the original-resolution rendition when available).
+     *
+     * @param nasaId - The NASA-assigned identifier (e.g. `'PIA06890'`).
+     *
+     * @returns The URL of the best available image, or `null` if no image
+     *          renditions exist for the given ID.
+     *
+     * @throws {Error} If the underlying {@link NASA.getAssets} call fails.
+     *
+     * @example
+     * ```ts
+     * const url = await NASA.getBestImageUrl('PIA06890')
+     * if (url) {
+     *   document.querySelector('img')!.src = url
+     * }
+     * ```
+     */
+    getBestImageUrl(nasaId: string): Promise<string | null>;
+    /**
+     * Fetch the NASA Astronomy Picture of the Day (APOD).
+     *
+     * Returns a single {@link APODResult} containing the title, explanation,
+     * standard and HD image URLs, and copyright information.
+     *
+     * @param date - An ISO-8601 date string (`'2024-06-15'`) or a `Date`
+     *               object. When omitted the API returns today's picture.
+     *
+     * @returns The APOD entry for the requested date.
+     *
+     * @throws {Error} If the APOD API responds with a non-2xx status code
+     *                 (e.g. 403 for an invalid API key, 404 for a date with
+     *                 no entry).
+     *
+     * @example
+     * ```ts
+     * // Today's APOD
+     * const today = await NASA.apod()
+     * console.log(today.title, today.hdUrl)
+     *
+     * // A specific date
+     * const historic = await NASA.apod('1995-06-16')
+     * ```
+     */
+    apod(date?: string | Date): Promise<APODResult>;
+    /**
+     * Fetch a random selection of recent APOD entries.
+     *
+     * Uses the `count` parameter of the APOD API to retrieve multiple
+     * randomly-selected entries at once. Thumbnails are requested for
+     * video entries.
+     *
+     * @param count - Number of random entries to return. Defaults to `7`.
+     *                The NASA API supports a maximum of `100`.
+     *
+     * @returns An array of {@link APODResult} objects.
+     *
+     * @throws {Error} If the APOD API responds with a non-2xx status code.
+     *
+     * @example
+     * ```ts
+     * const week = await NASA.recentAPOD()
+     * for (const entry of week) {
+     *   console.log(`${entry.date}: ${entry.title}`)
+     * }
+     *
+     * // Fetch 20 random entries
+     * const batch = await NASA.recentAPOD(20)
+     * ```
+     */
+    recentAPOD(count?: number): Promise<APODResult[]>;
+};
+/**
+ * Client for the European Space Agency (ESA) Hubble Space Telescope
+ * public image archive.
+ *
+ * @example
+ * ```ts
+ * import { ESA } from 'cosmos-lib'
+ *
+ * const images = await ESA.searchHubble('crab nebula', 5)
+ * console.log(images[0].title, images[0].imageUrl)
+ * ```
+ */
+export declare const ESA: {
+    /**
+     * Search the ESA Hubble Space Telescope image archive.
+     *
+     * Queries the ESAHubble public REST API and returns an array of
+     * {@link ESAHubbleResult} objects with image metadata and URLs.
+     *
+     * @param query - Free-text search term (e.g. `'crab nebula'`).
+     * @param limit - Maximum number of results to return. Defaults to `10`.
+     *
+     * @returns An array of matching Hubble image results. Each result
+     *          includes both a full-resolution `imageUrl` and a
+     *          screen-sized `thumbUrl`.
+     *
+     * @throws {Error} If the ESA API responds with a non-2xx status code.
+     *
+     * @example
+     * ```ts
+     * const results = await ESA.searchHubble('crab nebula', 3)
+     * for (const r of results) {
+     *   console.log(r.title, r.thumbUrl)
+     * }
+     * ```
+     *
+     * @see {@link https://esahubble.org/api/v1/ | ESA Hubble API docs}
+     */
+    searchHubble(query: string, limit?: number): Promise<ESAHubbleResult[]>;
+};
+/**
+ * Resolve an astronomical object name through the CDS SIMBAD TAP service.
+ *
+ * Performs an ADQL query against the SIMBAD database at the Strasbourg
+ * Astronomical Data Centre (CDS) and returns the J2000 equatorial
+ * coordinates and object type for the first match.
+ *
+ * @param objectName - Any object identifier recognised by SIMBAD
+ *                     (e.g. `'M1'`, `'NGC 6611'`, `'Betelgeuse'`).
+ *
+ * @returns A {@link SimbadResult} with the main identifier, RA/Dec in
+ *          degrees, and the SIMBAD object-type code, or `null` if the
+ *          object name could not be resolved.
+ *
+ * @throws {Error} If the SIMBAD TAP endpoint responds with a non-2xx
+ *                 status code.
+ *
+ * @example
+ * ```ts
+ * import { resolveSimbad } from 'cosmos-lib'
+ *
+ * const m1 = await resolveSimbad('M1')
+ * if (m1) {
+ *   console.log(`RA: ${m1.ra}, Dec: ${m1.dec}, Type: ${m1.type}`)
+ * }
+ *
+ * const star = await resolveSimbad('Betelgeuse')
+ * // => { id: '* alf Ori', ra: 88.792..., dec: 7.407..., type: 'LP*' }
+ * ```
+ */
+export declare function resolveSimbad(objectName: string): Promise<SimbadResult | null>;

package/dist/cache.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Time-bucketed memoization for astronomical position functions.
+ *
+ * Rounds Date inputs to the nearest `bucketMs` milliseconds to create
+ * cache keys. Uses LRU eviction via Map insertion order.
+ *
+ * @param fn - Pure function accepting a Date as its first argument.
+ * @param bucketMs - Time bucket size in milliseconds (default: 60 000 = 1 minute).
+ * @param maxSize - Maximum cache entries before LRU eviction (default: 128).
+ */
+export declare function memoByTime<T>(fn: (date: Date) => T, bucketMs?: number, maxSize?: number): (date?: Date) => T;

package/dist/clock.d.ts

@@ -0,0 +1,181 @@
+import type { ObserverParams } from './types.js';
+/** Event types emitted by {@link AstroClock}. */
+export interface AstroClockEventMap {
+    /** Fired on each tick with the current simulation date. */
+    tick: {
+        date: Date;
+        speed: number;
+        playing: boolean;
+    };
+    /** Fired when playback starts or resumes. */
+    play: {
+        date: Date;
+        speed: number;
+    };
+    /** Fired when playback pauses. */
+    pause: {
+        date: Date;
+    };
+    /** Fired when the date is set programmatically (including snap-to-event). */
+    datechange: {
+        date: Date;
+        reason: 'set' | 'snap';
+    };
+    /** Fired when the speed multiplier changes. */
+    speedchange: {
+        speed: number;
+    };
+}
+/** Options for creating an {@link AstroClock}. */
+export interface AstroClockOptions {
+    /** Initial simulation date. @defaultValue `new Date()` */
+    startDate?: Date;
+    /** Speed multiplier (1 = real-time, 60 = 1 minute/second, -1 = reverse). @defaultValue `1` */
+    speed?: number;
+    /** Tick interval in milliseconds (used in timer mode). @defaultValue `1000` */
+    tickInterval?: number;
+    /** Use `requestAnimationFrame` for frame-accurate ticking. @defaultValue `false` */
+    useRAF?: boolean;
+    /** Auto-start playback on creation. @defaultValue `false` */
+    autoPlay?: boolean;
+}
+/** An astronomical event type for snap-to-event navigation. */
+export type AstroEventType = 'sunrise' | 'sunset' | 'moonrise' | 'moonset' | 'solar-noon' | 'moon-transit' | 'civil-dawn' | 'civil-dusk' | 'nautical-dawn' | 'nautical-dusk' | 'astro-dawn' | 'astro-dusk';
+/**
+ * A simulation clock that decouples observation time from wall-clock time.
+ *
+ * `AstroClock` maintains a virtual date that advances at a configurable speed
+ * multiplier. It supports forward and reverse playback, pause/resume, snap-to-event
+ * navigation, and both timer-based and `requestAnimationFrame`-based ticking.
+ *
+ * @remarks
+ * The clock advances the simulation date by `elapsed_ms * speed` on each tick.
+ * A speed of 1 means real-time; 60 means 1 minute of simulated time per second
+ * of wall-clock time; -1 means reverse real-time. The clock emits typed events
+ * via `on()`/`off()` for integration with UI frameworks.
+ *
+ * @example
+ * ```ts
+ * import { AstroClock } from '@motioncomplex/cosmos-lib'
+ *
+ * const clock = new AstroClock({ speed: 60, useRAF: true, autoPlay: true })
+ *
+ * clock.on('tick', ({ date }) => {
+ *   updateSkyMap(date)
+ *   updateUI(date)
+ * })
+ *
+ * // Jump to a specific date
+ * clock.setDate(new Date('2024-12-21T00:00:00Z'))
+ *
+ * // Snap to next sunset
+ * clock.snapTo('sunset', { lat: 47.05, lng: 8.31 })
+ *
+ * // Reverse playback at 10x speed
+ * clock.setSpeed(-10)
+ *
+ * // Clean up
+ * clock.dispose()
+ * ```
+ */
+export declare class AstroClock {
+    private _date;
+    private _speed;
+    private _tickInterval;
+    private _useRAF;
+    private _playing;
+    private _disposed;
+    private _lastWallTime;
+    private _timerId;
+    private _rafId;
+    private _listeners;
+    constructor(options?: AstroClockOptions);
+    /**
+     * Subscribe to a clock event.
+     *
+     * @param event   - Event name.
+     * @param handler - Callback invoked when the event fires.
+     *
+     * @example
+     * ```ts
+     * clock.on('tick', ({ date, speed }) => console.log(date, speed))
+     * clock.on('pause', () => console.log('Paused'))
+     * ```
+     */
+    on<K extends keyof AstroClockEventMap>(event: K, handler: (data: AstroClockEventMap[K]) => void): void;
+    /**
+     * Unsubscribe from a clock event.
+     */
+    off<K extends keyof AstroClockEventMap>(event: K, handler: (data: AstroClockEventMap[K]) => void): void;
+    private _emit;
+    /**
+     * Start or resume playback.
+     *
+     * The simulation date advances by `elapsed_ms * speed` on each tick.
+     * If already playing, this is a no-op.
+     */
+    play(): void;
+    /**
+     * Pause playback. The simulation date freezes at its current value.
+     */
+    pause(): void;
+    /** Whether the clock is currently playing. */
+    get playing(): boolean;
+    /**
+     * Set the simulation date. Emits `'datechange'`.
+     *
+     * @param date - The new simulation date.
+     */
+    setDate(date: Date): void;
+    /** Get the current simulation date. */
+    get date(): Date;
+    /**
+     * Set the speed multiplier. Emits `'speedchange'`.
+     *
+     * @param speed - New speed (1 = real-time, 60 = 1min/sec, -1 = reverse real-time).
+     *
+     * @example
+     * ```ts
+     * clock.setSpeed(3600) // 1 hour per second
+     * clock.setSpeed(-60)  // reverse, 1 minute per second
+     * clock.setSpeed(0)    // frozen (like pause but still "playing")
+     * ```
+     */
+    setSpeed(speed: number): void;
+    /** Get the current speed multiplier. */
+    get speed(): number;
+    /**
+     * Jump to the next occurrence of an astronomical event.
+     *
+     * Computes the next rise, set, or transit for the Sun or Moon from the
+     * current simulation date and observer location, then sets the clock to
+     * that time.
+     *
+     * @param eventType - The event to snap to.
+     * @param observer  - Observer location (date is ignored; current sim date is used).
+     * @returns The date snapped to, or `null` if the event doesn't occur.
+     *
+     * @example
+     * ```ts
+     * clock.snapTo('sunset', { lat: 47.05, lng: 8.31 })
+     * clock.snapTo('moonrise', { lat: 51.5, lng: -0.1 })
+     * ```
+     */
+    snapTo(eventType: AstroEventType, observer: ObserverParams): Date | null;
+    /**
+     * If the event time is in the past (relative to current sim date),
+     * try the next day. Returns null if the event is null.
+     */
+    private _nextOccurrence;
+    /**
+     * Stop the clock, remove all listeners, and release resources.
+     * The instance should not be used after calling `dispose()`.
+     */
+    dispose(): void;
+    private _advance;
+    private _tick;
+    private _rafTick;
+    private _emitTick;
+    private _scheduleNext;
+    private _cancelScheduled;
+}

package/dist/constants.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Fundamental astronomical and physical constants used throughout the library.
+ *
+ * All values follow IAU 2012 / IERS conventions unless otherwise noted.
+ *
+ * @example
+ * ```ts
+ * import { CONSTANTS } from '@motioncomplex/cosmos-lib'
+ * const earthSunKm = 1 * CONSTANTS.AU_TO_KM // 149 597 870.7
+ * ```
+ */
+export declare const CONSTANTS: {
+    /** One Astronomical Unit in kilometres (IAU 2012 exact definition). */
+    readonly AU_TO_KM: 149597870.7;
+    /** One light-year in kilometres. */
+    readonly LY_TO_KM: 9460730472580.8;
+    /** One parsec in light-years. */
+    readonly PC_TO_LY: 3.261563777;
+    /** One parsec in kilometres. */
+    readonly PC_TO_KM: 30856775810000;
+    /** Speed of light in km/s (exact, SI definition). */
+    readonly C_KM_S: 299792.458;
+    /** Newtonian gravitational constant in m^3 kg^-1 s^-2 (CODATA 2018). */
+    readonly G: 6.674e-11;
+    /** Solar mass in kilograms. */
+    readonly SOLAR_MASS_KG: 1.989e+30;
+    /** Solar radius in kilometres. */
+    readonly SOLAR_RADIUS_KM: 695700;
+    /** Earth mass in kilograms. */
+    readonly EARTH_MASS_KG: 5.972e+24;
+    /** Mean Earth radius in kilometres (IUGG). */
+    readonly EARTH_RADIUS_KM: 6371;
+    /** Julian Date of the J2000.0 epoch (2000-01-01T12:00:00 TT). */
+    readonly J2000: 2451545;
+    /** Mean obliquity of the ecliptic at J2000.0, in degrees. */
+    readonly ECLIPTIC_OBL: 23.4392911;
+    /** Conversion factor: degrees to radians. */
+    readonly DEG_TO_RAD: number;
+    /** Conversion factor: radians to degrees. */
+    readonly RAD_TO_DEG: number;
+};
+/** The type of the {@link CONSTANTS} object. */
+export type Constants = typeof CONSTANTS;

package/dist/data/constellations.d.ts

@@ -0,0 +1,58 @@
+/**
+ * All 88 IAU constellations with metadata and stick-figure asterism line segments.
+ *
+ * Coordinates are J2000 epoch, in degrees.
+ * Stick-figure segments connect the major naked-eye stars of each traditional
+ * Western asterism (similar to Stellarium's default patterns).
+ * Each segment is `[ra1, dec1, ra2, dec2]` in degrees.
+ *
+ * @module
+ */
+/**
+ * An IAU constellation with boundary metadata and a stick-figure asterism.
+ *
+ * Contains the official 3-letter abbreviation, full and genitive names,
+ * approximate center coordinates for label placement, the official area
+ * in square degrees, the brightest star name, and an array of line
+ * segments that form the traditional stick-figure pattern.
+ */
+export interface Constellation {
+    /** 3-letter IAU abbreviation (e.g., "Ori") */
+    abbr: string;
+    /** Full name (e.g., "Orion") */
+    name: string;
+    /** Genitive form (e.g., "Orionis") */
+    genitive: string;
+    /** Approximate center RA for labeling (degrees) */
+    ra: number;
+    /** Approximate center Dec for labeling (degrees) */
+    dec: number;
+    /** IAU official area in square degrees */
+    area: number;
+    /** Array of line segments, each [ra1_deg, dec1_deg, ra2_deg, dec2_deg] */
+    stickFigure: number[][];
+    /** IAU proper name of the brightest star */
+    brightestStar: string;
+}
+/**
+ * All 88 IAU constellations with stick-figure asterism data.
+ *
+ * Each constellation includes center coordinates for label placement,
+ * its official area in square degrees, its brightest star, and an array
+ * of line segments (`[ra1, dec1, ra2, dec2]`) defining the traditional
+ * Western asterism pattern.
+ *
+ * @example
+ * ```ts
+ * import { CONSTELLATIONS } from '@motioncomplex/cosmos-lib'
+ *
+ * const orion = CONSTELLATIONS.find(c => c.abbr === 'Ori')
+ * console.log(orion?.name)          // 'Orion'
+ * console.log(orion?.brightestStar) // 'Rigel'
+ * console.log(orion?.stickFigure.length) // number of line segments
+ *
+ * // Get all constellations larger than 1000 sq deg
+ * const large = CONSTELLATIONS.filter(c => c.area > 1000)
+ * ```
+ */
+export declare const CONSTELLATIONS: readonly Constellation[];