@motioncomplex/cosmos-lib 1.0.9

package/dist/data/cutouts.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Runtime coordinate-based image cutout functions.
+ *
+ * These query Pan-STARRS DR2 and DSS by exact RA/Dec coordinates,
+ * guaranteeing the returned image is the correct object. The precomputed
+ * file list in {@link PS1_FILES} eliminates the first of Pan-STARRS'
+ * two-step request flow, cutting latency roughly in half.
+ *
+ * @module
+ */
+/** Result from a coordinate-based cutout request. */
+export interface CutoutResult {
+    /** Direct image URL. */
+    url: string;
+    /** Image format. */
+    format: 'jpg' | 'gif';
+    /** Attribution string. */
+    credit: string;
+    /** Source identifier. */
+    source: 'panstarrs' | 'dss';
+}
+/** Options controlling cutout generation. */
+export interface CutoutOptions {
+    /** Desired output width in pixels. @defaultValue `1024` */
+    outputSize?: number;
+    /** FOV multiplier around object angular size. @defaultValue `1.6` */
+    padding?: number;
+    /** Minimum FOV floor in arcminutes. @defaultValue `4` */
+    minFov?: number;
+    /** Maximum FOV ceiling in arcminutes. @defaultValue `120` */
+    maxFov?: number;
+    /** Timeout in milliseconds for each API call. @defaultValue `15000` */
+    timeout?: number;
+}
+/**
+ * Compute the field-of-view in arcminutes for a given object.
+ *
+ * Uses the object's angular size with padding when known, or a
+ * type-based default. Clamped to `[minFov, maxFov]`.
+ *
+ * @param sizeArcmin - Angular diameter in arcminutes, or `undefined`.
+ * @param objectType - Object type string (e.g. `'nebula'`, `'star'`).
+ * @param opts       - Padding and clamping overrides.
+ */
+export declare function computeFov(sizeArcmin: number | undefined, objectType: string, opts?: Pick<CutoutOptions, 'padding' | 'minFov' | 'maxFov'>): number;
+/**
+ * Build a Pan-STARRS DR2 color cutout URL using the precomputed file list.
+ *
+ * Returns `null` if dec < -30 (below coverage), no precomputed file list
+ * exists for this object, or the HEAD check fails.
+ *
+ * @param id         - Object identifier for the precomputed lookup.
+ * @param ra         - Right Ascension in degrees (J2000).
+ * @param dec        - Declination in degrees (J2000).
+ * @param fovArcmin  - Desired field of view in arcminutes.
+ * @param opts       - Output size and timeout options.
+ */
+export declare function tryPanSTARRS(id: string, ra: number, dec: number, fovArcmin: number, opts?: CutoutOptions): Promise<CutoutResult | null>;
+/**
+ * Build a DSS cutout URL via MAST and verify it exists.
+ *
+ * Full-sky grayscale coverage. Uses POSS2/UKSTU Red for dec > -40,
+ * DSS1 Red for the extreme south.
+ *
+ * @param ra         - Right Ascension in degrees (J2000).
+ * @param dec        - Declination in degrees (J2000).
+ * @param fovArcmin  - Desired field of view in arcminutes.
+ * @param opts       - Timeout options.
+ */
+export declare function tryDSS(ra: number, dec: number, fovArcmin: number, opts?: CutoutOptions): Promise<CutoutResult | null>;

package/dist/data/deep-sky.d.ts

@@ -0,0 +1,27 @@
+import type { CelestialObject } from '../types.js';
+/**
+ * Notable deep-sky objects not covered by the Messier catalog.
+ *
+ * Includes prominent non-Messier objects such as the Helix Nebula,
+ * the Milky Way itself, Omega Centauri, and supermassive black holes
+ * (Sgr A* and M87's black hole). These are merged into the unified
+ * catalog by {@link Data}.
+ *
+ * @remarks
+ * This collection is intentionally small and curated. It supplements
+ * the Messier catalog with objects that are either too famous to omit
+ * (e.g. the Milky Way, Sgr A*) or are among the finest deep-sky objects
+ * in the southern sky (e.g. Omega Centauri, Helix Nebula).
+ *
+ * @example
+ * ```ts
+ * import { DEEP_SKY_EXTRAS } from '@motioncomplex/cosmos-lib'
+ *
+ * const helix = DEEP_SKY_EXTRAS.find(o => o.id === 'ngc7293')
+ * console.log(helix?.name) // 'Helix Nebula'
+ *
+ * const sgrA = DEEP_SKY_EXTRAS.find(o => o.id === 'sgr-a-star')
+ * console.log(sgrA?.aliases) // ['Sgr A*', 'SgrA*']
+ * ```
+ */
+export declare const DEEP_SKY_EXTRAS: readonly CelestialObject[];

package/dist/data/images.d.ts

@@ -0,0 +1,147 @@
+import type { ImageRef, ObjectImageResult, GetImageOptions, ProximityResult, EquatorialCoord } from '../types.js';
+interface CatalogInfo {
+    id: string;
+    ra: number | null;
+    dec: number | null;
+    size_arcmin?: number | undefined;
+    type: string;
+    name: string;
+    aliases: string[];
+}
+type CatalogLookupFn = (id: string) => CatalogInfo | null;
+type NearbyFn = (center: EquatorialCoord, radiusDeg: number) => ProximityResult[];
+/** @internal Wire the catalog lookup. Called once from index.ts. */
+export declare function _setCatalogLookup(fn: CatalogLookupFn): void;
+/** @internal Wire the nearby-search function. Called once from index.ts. */
+export declare function _setNearbyFn(fn: NearbyFn): void;
+/**
+ * Curated Wikimedia Commons image entries for the most iconic celestial objects.
+ *
+ * Each key is an object ID (e.g. `'m42'`) mapping to an array of
+ * {@link ImageRef} records with a Wikimedia `filename` and `credit` string.
+ * These are guaranteed-available with no API call needed, making them
+ * ideal for offline fallbacks and static site generation.
+ *
+ * @example
+ * ```ts
+ * import { IMAGE_FALLBACKS } from '@motioncomplex/cosmos-lib'
+ *
+ * const orionImages = IMAGE_FALLBACKS['m42']
+ * console.log(orionImages?.[0].filename)
+ * // => 'Orion_Nebula_-_Hubble_2006_mosaic_18000.jpg'
+ * ```
+ */
+export declare const IMAGE_FALLBACKS: Readonly<Record<string, ImageRef[]>>;
+/**
+ * A resolved image result from NASA or ESA image APIs.
+ *
+ * Contains multiple resolution URLs (highest quality first), a thumbnail
+ * preview, and attribution metadata. Suitable for progressive loading,
+ * fallback chains, or Three.js texture inputs.
+ */
+export interface ResolvedImage {
+    /** Multiple resolution URLs, highest quality first. */
+    urls: string[];
+    /** Preview/thumbnail URL, or `null` if unavailable. */
+    previewUrl: string | null;
+    /** Image title from the source API. */
+    title: string;
+    /** Attribution/credit string. */
+    credit: string;
+    /** Which API the image came from. */
+    source: 'nasa' | 'esa';
+}
+/**
+ * Options for the {@link resolveImages} function.
+ */
+export interface ResolveImageOptions {
+    /** Which API source to search. Defaults to `'nasa'`. */
+    source?: 'nasa' | 'esa' | 'all';
+    /** Maximum number of results. Defaults to `5`. */
+    limit?: number;
+}
+/**
+ * Search NASA and/or ESA APIs for images of a celestial object by name.
+ *
+ * Returns multi-resolution image results that can feed directly into
+ * `Media.chainLoad()`, `Media.progressive()`, or `createNebula({ textureUrls })`.
+ * Works for any object -- not limited to the static {@link IMAGE_FALLBACKS} registry.
+ *
+ * @param name - Object name to search (e.g. `'Orion Nebula'`, `'M42'`, `'Sirius'`).
+ * @param opts - Search options controlling source and result count.
+ * @returns A promise resolving to an array of {@link ResolvedImage} results.
+ *
+ * @example
+ * ```ts
+ * import { resolveImages } from '@motioncomplex/cosmos-lib'
+ *
+ * // Search NASA for Orion Nebula images
+ * const images = await resolveImages('Orion Nebula', { limit: 3 })
+ * console.log(images[0].title, images[0].urls[0])
+ *
+ * // Search both NASA and ESA
+ * const all = await resolveImages('Crab Nebula', { source: 'all' })
+ * ```
+ */
+export declare function resolveImages(name: string, opts?: ResolveImageOptions): Promise<ResolvedImage[]>;
+/**
+ * Prefetch images for a list of object IDs in the background.
+ *
+ * Fires off `getObjectImage` for each ID concurrently (with `prefetch: false`
+ * to avoid recursive expansion). Results are stored in the in-memory cache
+ * so subsequent `Data.getImage()` calls for these objects resolve instantly.
+ *
+ * Call this when you know which objects the user is likely to view next —
+ * e.g. when a list of objects renders or when filtering narrows the results.
+ *
+ * @param ids - Object IDs to prefetch (e.g. `['m1', 'm2', 'm3']`).
+ *
+ * @example
+ * ```ts
+ * // Prefetch when a filtered list renders
+ * Data.prefetchImages(filteredObjects.map(o => o.id))
+ *
+ * // Later, when user taps M2:
+ * const img = await Data.getImage('m2', 'M2') // instant from cache
+ * ```
+ */
+export declare function prefetchImages(ids: string[]): void;
+/**
+ * Unified image pipeline that resolves the best available image for any
+ * celestial object, with built-in auto-prefetching of nearby objects.
+ *
+ * The pipeline runs a cascade of sources in priority order:
+ * 1. **In-memory cache** — instant (0ms) for previously resolved images.
+ * 2. **Curated Wikimedia static registry** — hand-picked iconic images
+ *    served via Wikimedia's thumbnail API with responsive `srcset`.
+ *    No network validation — URLs are trusted for zero-latency resolution.
+ * 3. **NASA / ESA text search** — high-quality press release imagery.
+ * 4. **Pan-STARRS DR2 cutout** *(opt-in, `skipCutouts: false`)* —
+ *    coordinate-based color composite. Accurate but raw survey data.
+ * 5. **DSS cutout** *(opt-in)* — full-sky grayscale fallback.
+ *
+ * After resolving, the pipeline automatically prefetches images for nearby
+ * objects in the background, so spatial browsing feels instant.
+ *
+ * @param id   - Object ID (e.g. `'mars'`, `'m42'`, `'sirius'`).
+ * @param name - Object display name used for API searches when no
+ *               coordinate-based source is available.
+ * @param opts - Width, srcset, cutout, and prefetch options.
+ * @returns The best available image, or `null` if no image could be found.
+ *
+ * @example
+ * ```ts
+ * // Just works — auto-prefetches nearby objects
+ * const img = await Data.getImage('m42', 'Orion Nebula', { width: 1200 })
+ * if (img) {
+ *   heroEl.src = img.src
+ *   heroEl.srcset = img.srcset ?? ''
+ *   creditEl.textContent = img.credit
+ * }
+ *
+ * // Disable auto-prefetch
+ * const img2 = await Data.getImage('m42', 'Orion Nebula', { prefetch: false })
+ * ```
+ */
+export declare function getObjectImage(id: string, name: string, opts?: GetImageOptions): Promise<ObjectImageResult | null>;
+export {};

package/dist/data/index.d.ts

@@ -0,0 +1,422 @@
+import { resolveImages, getObjectImage, prefetchImages } from './images.js';
+import type { CelestialObject, ObjectType, ProximityResult, EquatorialCoord, ProgressiveImageOptions } from '../types.js';
+import type { BrightStar } from './stars.js';
+import type { Constellation } from './constellations.js';
+import type { MessierObject } from './messier.js';
+import type { MeteorShower } from './showers.js';
+export type { BrightStar } from './stars.js';
+export type { Constellation } from './constellations.js';
+export type { MessierObject } from './messier.js';
+export type { MeteorShower } from './showers.js';
+export type { SolarSystemBody } from './solar-system.js';
+export type { ResolvedImage, ResolveImageOptions } from './images.js';
+export { SOLAR_SYSTEM } from './solar-system.js';
+export { DEEP_SKY_EXTRAS } from './deep-sky.js';
+export { BRIGHT_STARS } from './stars.js';
+export { CONSTELLATIONS } from './constellations.js';
+export { MESSIER_CATALOG } from './messier.js';
+export { METEOR_SHOWERS } from './showers.js';
+export { IMAGE_FALLBACKS, resolveImages, getObjectImage, prefetchImages } from './images.js';
+export { computeFov, tryPanSTARRS, tryDSS } from './cutouts.js';
+export type { CutoutResult, CutoutOptions } from './cutouts.js';
+/**
+ * Unified data-access facade for all built-in astronomical catalogs.
+ *
+ * Merges solar-system bodies, bright stars, Messier objects, and deep-sky
+ * extras into a single searchable collection. Also exposes typed accessors
+ * for individual catalogs (stars, constellations, Messier, meteor showers)
+ * and image-resolution helpers.
+ *
+ * @example
+ * ```ts
+ * import { Data } from '@motioncomplex/cosmos-lib'
+ *
+ * const orion = Data.search('orion')
+ * const sirius = Data.getByName('Sirius')
+ * const m42 = Data.getMessier(42)
+ * ```
+ */
+export declare const Data: {
+    /**
+     * Look up a celestial object by its exact identifier.
+     *
+     * @param id - The unique object ID (e.g. `'mars'`, `'m42'`, `'sirius'`).
+     * @returns The matching {@link CelestialObject}, or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const mars = Data.get('mars')
+     * // => { id: 'mars', name: 'Mars', type: 'planet', ... }
+     *
+     * const missing = Data.get('nonexistent')
+     * // => null
+     * ```
+     */
+    get(id: string): CelestialObject | null;
+    /**
+     * Look up a celestial object by name or any known alias (case-insensitive).
+     *
+     * @param name - The common name or alias (e.g. `'Sirius'`, `'Morning Star'`, `'NGC 1976'`).
+     * @returns The matching {@link CelestialObject}, or `null` if no match.
+     *
+     * @example
+     * ```ts
+     * const sirius = Data.getByName('Sirius')
+     * // => { id: 'sirius', name: 'Sirius', type: 'star', ... }
+     *
+     * const venus = Data.getByName('morning star')
+     * // => { id: 'venus', name: 'Venus', ... }
+     * ```
+     */
+    getByName(name: string): CelestialObject | null;
+    /**
+     * Return a shallow copy of the full unified catalog.
+     *
+     * The returned array is a new instance on every call, so it is safe to
+     * sort, filter, or mutate without affecting the internal data.
+     *
+     * @returns A new array containing every {@link CelestialObject} in the catalog.
+     *
+     * @example
+     * ```ts
+     * const catalog = Data.all()
+     * console.log(catalog.length) // ~420+ objects
+     * ```
+     */
+    all(): CelestialObject[];
+    /**
+     * Filter the unified catalog by object type.
+     *
+     * @param type - The {@link ObjectType} to filter on (e.g. `'planet'`, `'nebula'`, `'galaxy'`).
+     * @returns All objects matching the given type.
+     *
+     * @example
+     * ```ts
+     * const nebulae = Data.getByType('nebula')
+     * // => [{ id: 'm1', name: 'Crab Nebula', ... }, ...]
+     *
+     * const planets = Data.getByType('planet')
+     * // => [{ id: 'mercury', ... }, { id: 'venus', ... }, ...]
+     * ```
+     */
+    getByType(type: ObjectType): CelestialObject[];
+    /**
+     * Filter the unified catalog by a tag string.
+     *
+     * @param tag - A tag to match (e.g. `'messier'`, `'solar-system'`, `'globular'`).
+     * @returns All objects whose `tags` array includes the given string.
+     *
+     * @example
+     * ```ts
+     * const messierObjects = Data.getByTag('messier')
+     * // => all 110 Messier catalog entries
+     *
+     * const solarSystem = Data.getByTag('solar-system')
+     * // => Sun, planets, and Moon
+     * ```
+     */
+    getByTag(tag: string): CelestialObject[];
+    /**
+     * Fuzzy search across name, aliases, description, and tags.
+     *
+     * Results are ranked by a weighted relevance score: exact ID and name
+     * matches rank highest, followed by alias matches, partial name matches,
+     * description hits, and tag hits. Results are sorted highest-score first.
+     *
+     * @param query - The search term (case-insensitive). An empty string returns `[]`.
+     * @returns Matching {@link CelestialObject CelestialObjects} sorted by relevance.
+     *
+     * @example
+     * ```ts
+     * const results = Data.search('orion')
+     * // => [Orion Nebula (M42), De Mairan's Nebula (M43), Betelgeuse, ...]
+     *
+     * const galaxies = Data.search('spiral')
+     * // => all objects with 'spiral' in name, subtype, description, or tags
+     * ```
+     */
+    search(query: string): CelestialObject[];
+    /**
+     * Find all objects within a given angular radius of a sky position.
+     *
+     * Only considers objects with known RA/Dec coordinates (solar-system
+     * bodies with `null` RA/Dec are excluded). Results are sorted by
+     * angular separation, nearest first.
+     *
+     * @param center - The sky position to search around, in J2000 equatorial coordinates.
+     * @param radiusDeg - Search radius in degrees.
+     * @returns An array of {@link ProximityResult} objects, each containing the
+     *   matched object and its angular separation from the center.
+     *
+     * @example
+     * ```ts
+     * // Find objects within 5 degrees of the Orion Nebula
+     * const nearby = Data.nearby({ ra: 83.82, dec: -5.39 }, 5)
+     * nearby.forEach(r =>
+     *   console.log(`${r.object.name}: ${r.separation.toFixed(2)}deg`)
+     * )
+     * ```
+     */
+    nearby(center: EquatorialCoord, radiusDeg: number): ProximityResult[];
+    /**
+     * Get static Wikimedia image URLs for an object from the fallback registry.
+     *
+     * Uses the curated {@link IMAGE_FALLBACKS} registry (no API call needed).
+     * Returns an empty array if the object has no static images registered.
+     *
+     * @param id - The object ID (e.g. `'m42'`, `'m31'`).
+     * @param width - Optional pixel width for Wikimedia thumbnail resizing.
+     * @returns An array of Wikimedia Commons thumbnail URLs.
+     *
+     * @example
+     * ```ts
+     * const urls = Data.imageUrls('m42', 1280)
+     * // => ['https://upload.wikimedia.org/...Orion_Nebula.../1280px-...']
+     *
+     * const empty = Data.imageUrls('mercury')
+     * // => []
+     * ```
+     */
+    imageUrls(id: string, width?: number): string[];
+    /**
+     * Build a {@link ProgressiveImageOptions} config from the static fallback registry.
+     *
+     * Produces a tiny 64 px placeholder, a standard-resolution source, and a
+     * 2x HD source -- ready to feed into `Media.progressive()`.
+     * Returns `null` if the object has no static images registered.
+     *
+     * @param id - The object ID (e.g. `'m42'`, `'m51'`).
+     * @param width - Target width in pixels for the standard source. Defaults to `800`.
+     * @returns A {@link ProgressiveImageOptions} object, or `null`.
+     *
+     * @example
+     * ```ts
+     * const prog = Data.progressiveImage('m42', 1024)
+     * // => { placeholder: '...64px...', src: '...1024px...', srcHD: '...2048px...' }
+     * ```
+     */
+    progressiveImage(id: string, width?: number): ProgressiveImageOptions | null;
+    /**
+     * Generate an HTML `srcset` string from the static fallback registry.
+     *
+     * Produces a comma-separated list of `<url> <width>w` entries suitable
+     * for the `srcset` attribute of an `<img>` element.
+     * Returns `null` if the object has no static images registered.
+     *
+     * @param id - The object ID (e.g. `'m31'`).
+     * @param widths - Array of pixel widths to include. Defaults to `[640, 1280, 1920]`.
+     * @returns A `srcset`-formatted string, or `null`.
+     *
+     * @example
+     * ```ts
+     * const srcset = Data.imageSrcset('m31')
+     * // => '...640px-... 640w, ...1280px-... 1280w, ...1920px-... 1920w'
+     * ```
+     */
+    imageSrcset(id: string, widths?: number[]): string | null;
+    /**
+     * Search NASA and/or ESA APIs for images of any celestial object by name.
+     *
+     * Returns multi-resolution {@link ResolvedImage} results suitable for
+     * progressive loading, fallback chains, or Three.js textures.
+     * Unlike the static `imageUrls` / `imageSrcset` helpers, this method
+     * works for **any** object -- it is not limited to the curated fallback registry.
+     *
+     * @param name - Object name to search (e.g. `'Orion Nebula'`, `'M42'`, `'Sirius'`).
+     * @param opts - Optional {@link ResolveImageOptions} to control source and limit.
+     * @returns A promise resolving to an array of {@link ResolvedImage} results.
+     *
+     * @example
+     * ```ts
+     * const images = await Data.resolveImages('Crab Nebula', { source: 'all', limit: 3 })
+     * images.forEach(img => console.log(img.title, img.urls[0]))
+     * ```
+     */
+    resolveImages: typeof resolveImages;
+    /**
+     * Unified image pipeline — resolves the best available image for any
+     * celestial object and returns it in an optimized, ready-to-render format.
+     *
+     * Runs a cascading lookup: static registry (instant) → NASA → ESA.
+     * Results from API sources are cached in memory. The consumer only needs
+     * to provide the object ID and name — the pipeline handles source selection,
+     * URL construction, and responsive `srcset` generation.
+     *
+     * @param id   - Object ID (e.g. `'mars'`, `'m42'`, `'sirius'`).
+     * @param name - Display name for API search fallback (e.g. `'Mars'`).
+     * @param opts - Width, srcset, and source preferences.
+     * @returns The best available image, or `null` if nothing was found.
+     *
+     * @example
+     * ```ts
+     * const img = await Data.getImage('mars', 'Mars')
+     * if (img) {
+     *   heroEl.src = img.src
+     *   heroEl.srcset = img.srcset ?? ''
+     *   creditEl.textContent = img.credit
+     * }
+     * ```
+     */
+    getImage: typeof getObjectImage;
+    /**
+     * Prefetch images for a list of object IDs in the background.
+     *
+     * Results are stored in the in-memory cache so subsequent
+     * {@link Data.getImage} calls resolve instantly.
+     *
+     * @param ids - Object IDs to prefetch.
+     *
+     * @example
+     * ```ts
+     * Data.prefetchImages(filteredObjects.map(o => o.id))
+     * ```
+     */
+    prefetchImages: typeof prefetchImages;
+    /**
+     * Get all bright stars in the catalog (~200 IAU named stars).
+     *
+     * @returns The full {@link BRIGHT_STARS} array (readonly).
+     *
+     * @example
+     * ```ts
+     * const stars = Data.stars()
+     * console.log(stars[0].name) // 'Sirius'
+     * ```
+     */
+    stars(): readonly BrightStar[];
+    /**
+     * Look up a bright star by its IAU proper name (case-insensitive).
+     *
+     * @param name - The IAU proper name (e.g. `'Sirius'`, `'Betelgeuse'`, `'Polaris'`).
+     * @returns The matching {@link BrightStar}, or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const sirius = Data.getStarByName('Sirius')
+     * // => { id: 'sirius', name: 'Sirius', con: 'CMa', mag: -1.46, ... }
+     * ```
+     */
+    getStarByName(name: string): BrightStar | null;
+    /**
+     * Get all bright stars belonging to a given constellation.
+     *
+     * @param con - The 3-letter IAU constellation abbreviation (case-insensitive),
+     *   e.g. `'Ori'`, `'CMa'`, `'UMa'`.
+     * @returns All {@link BrightStar BrightStars} in that constellation.
+     *
+     * @example
+     * ```ts
+     * const orionStars = Data.getStarsByConstellation('Ori')
+     * // => [Rigel, Betelgeuse, Bellatrix, Alnilam, Alnitak, Mintaka, Saiph]
+     * ```
+     */
+    getStarsByConstellation(con: string): BrightStar[];
+    /**
+     * Find bright stars within a given angular radius of a sky position.
+     *
+     * Results are sorted by angular separation (nearest first).
+     *
+     * @param center - The sky position to search around, in J2000 equatorial coordinates.
+     * @param radiusDeg - Search radius in degrees.
+     * @returns An array of objects, each containing the matched {@link BrightStar}
+     *   and its angular `separation` in degrees from the center.
+     *
+     * @example
+     * ```ts
+     * // Find bright stars within 10 degrees of Sirius
+     * const nearby = Data.nearbyStars({ ra: 101.287, dec: -16.716 }, 10)
+     * nearby.forEach(r =>
+     *   console.log(`${r.star.name}: ${r.separation.toFixed(2)}deg`)
+     * )
+     * ```
+     */
+    nearbyStars(center: EquatorialCoord, radiusDeg: number): Array<{
+        star: BrightStar;
+        separation: number;
+    }>;
+    /**
+     * Get all 88 IAU constellations.
+     *
+     * @returns The full {@link CONSTELLATIONS} array (readonly).
+     *
+     * @example
+     * ```ts
+     * const all = Data.constellations()
+     * console.log(all.length) // 88
+     * ```
+     */
+    constellations(): readonly Constellation[];
+    /**
+     * Look up a constellation by its 3-letter IAU abbreviation (case-insensitive).
+     *
+     * @param abbr - The abbreviation (e.g. `'Ori'`, `'UMa'`, `'Sco'`).
+     * @returns The matching {@link Constellation}, or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const orion = Data.getConstellation('Ori')
+     * // => { abbr: 'Ori', name: 'Orion', genitive: 'Orionis', area: 594, ... }
+     * ```
+     */
+    getConstellation(abbr: string): Constellation | null;
+    /**
+     * Get all 110 Messier objects.
+     *
+     * @returns The full {@link MESSIER_CATALOG} array (readonly).
+     *
+     * @example
+     * ```ts
+     * const catalog = Data.messier()
+     * console.log(catalog.length) // 110
+     * ```
+     */
+    messier(): readonly MessierObject[];
+    /**
+     * Look up a Messier object by its catalog number.
+     *
+     * @param number - The Messier number, from 1 to 110.
+     * @returns The matching {@link MessierObject}, or `null` if out of range.
+     *
+     * @example
+     * ```ts
+     * const m42 = Data.getMessier(42)
+     * // => { messier: 42, name: 'Orion Nebula', type: 'nebula', mag: 4.0, ... }
+     *
+     * const m1 = Data.getMessier(1)
+     * // => { messier: 1, name: 'Crab Nebula', ... }
+     * ```
+     */
+    getMessier(number: number): MessierObject | null;
+    /**
+     * Get all meteor showers in the catalog (~23 significant annual showers).
+     *
+     * @returns The full {@link METEOR_SHOWERS} array (readonly).
+     *
+     * @example
+     * ```ts
+     * const showers = Data.showers()
+     * const perseids = showers.find(s => s.id === 'perseids')
+     * console.log(perseids?.zhr) // 100
+     * ```
+     */
+    showers(): readonly MeteorShower[];
+    /**
+     * Get meteor showers that are active on a given date.
+     *
+     * Computes the Sun's ecliptic longitude for the date and compares it
+     * against each shower's peak solar longitude, returning those within
+     * a +/-20 degree activity window.
+     *
+     * @param date - The date to check for active showers.
+     * @returns An array of {@link MeteorShower MeteorShowers} active on the given date.
+     *
+     * @example
+     * ```ts
+     * // Check for active showers on August 12 (Perseid peak)
+     * const active = Data.getActiveShowers(new Date('2025-08-12'))
+     * console.log(active.map(s => s.name))
+     * // => ['Perseids', 'Kappa Cygnids', ...]
+     * ```
+     */
+    getActiveShowers(date: Date): MeteorShower[];
+};