@motioncomplex/cosmos-lib 1.0.9

package/dist/planner.d.ts

@@ -0,0 +1,224 @@
+import type { CelestialObject, ObserverParams, ObjectType, PlanetName } from './types.js';
+/** A visible object with its current horizontal position and metadata. */
+export interface VisibleObject {
+    /** The catalog object. */
+    object: CelestialObject;
+    /** Current altitude in degrees (above horizon). */
+    alt: number;
+    /** Current azimuth in degrees (0=N, 90=E, 180=S, 270=W). */
+    az: number;
+    /** Angular separation from the Moon in degrees, or `null` if Moon position unavailable. */
+    moonSeparation: number | null;
+    /** Moon interference score 0–1 (0 = no interference, 1 = full moon on top of object). */
+    moonInterference: number;
+}
+/** Options for {@link Planner.whatsUp}. */
+export interface WhatsUpOptions {
+    /** Minimum altitude in degrees above horizon. @defaultValue `10` */
+    minAltitude?: number;
+    /** Maximum (faintest) apparent magnitude to include. @defaultValue `6` */
+    magnitudeLimit?: number;
+    /** Filter by object type(s). */
+    types?: ObjectType[];
+    /** Filter by constellation abbreviation (3-letter, case-insensitive). */
+    constellation?: string;
+    /** Filter by catalog tag (e.g. `'messier'`). */
+    tag?: string;
+    /** Maximum number of results. @defaultValue `50` */
+    limit?: number;
+}
+/** A point on the altitude-vs-time visibility curve. */
+export interface VisibilityCurvePoint {
+    /** The date/time of this sample. */
+    date: Date;
+    /** Altitude in degrees at this time. */
+    alt: number;
+    /** Azimuth in degrees at this time. */
+    az: number;
+}
+/** Result from {@link Planner.bestWindow}. */
+export interface BestWindowResult {
+    /** Time of maximum altitude. */
+    peak: Date;
+    /** Maximum altitude in degrees. */
+    peakAltitude: number;
+    /** Rise time (altitude crosses `minAlt`), or `null` if already up at start of night. */
+    rise: Date | null;
+    /** Set time (altitude drops below `minAlt`), or `null` if still up at end of night. */
+    set: Date | null;
+}
+/** Result from planet opposition/conjunction detection. */
+export interface PlanetEvent {
+    /** The planet involved. */
+    planet: PlanetName;
+    /** Type of event. */
+    type: 'opposition' | 'conjunction';
+    /** Approximate date of the event. */
+    date: Date;
+    /** Elongation from the Sun in degrees at the event. */
+    elongation: number;
+}
+/** Moon interference details for a target. */
+export interface MoonInterference {
+    /** Angular separation from the Moon in degrees. */
+    separation: number;
+    /** Moon illumination fraction 0–1. */
+    illumination: number;
+    /** Combined interference score 0–1 (0 = no interference, 1 = worst case). */
+    score: number;
+}
+/** Airmass at a given time. */
+export interface AirmassPoint {
+    /** The date/time of this sample. */
+    date: Date;
+    /** Altitude in degrees. */
+    alt: number;
+    /** Airmass value (1.0 at zenith, higher near horizon). */
+    airmass: number;
+}
+/**
+ * Observation planning utilities — "What can I see tonight?"
+ *
+ * Provides functions to determine which objects are visible for a given
+ * observer, compute optimal viewing windows, altitude curves, moon
+ * interference scoring, airmass calculations, and planet event detection.
+ *
+ * @example
+ * ```ts
+ * import { Planner } from '@motioncomplex/cosmos-lib'
+ *
+ * const observer = { lat: 47.05, lng: 8.31, date: new Date('2024-08-15') }
+ *
+ * // What's visible tonight?
+ * const visible = Planner.whatsUp(observer)
+ * visible.forEach(v => console.log(v.object.name, `alt: ${v.alt.toFixed(1)}°`))
+ *
+ * // Best time to observe M42
+ * const window = Planner.bestWindow('m42', observer)
+ * console.log('Peak altitude:', window?.peakAltitude.toFixed(1))
+ *
+ * // Altitude curve for Sirius
+ * const curve = Planner.visibilityCurve('sirius', observer)
+ * ```
+ */
+export declare const Planner: {
+    /**
+     * Objects currently above the horizon, sorted by altitude (highest first).
+     *
+     * Returns all catalog objects that are above the specified minimum altitude
+     * at the observer's date/time, filtered by optional magnitude limit,
+     * object type, constellation, or catalog tag. Each result includes the
+     * current alt/az position and moon interference scoring.
+     *
+     * @param observer - Observer location and time.
+     * @param options - Filtering and sorting options.
+     * @returns Visible objects sorted by altitude (highest first).
+     *
+     * @example
+     * ```ts
+     * const visible = Planner.whatsUp(
+     *   { lat: 47.05, lng: 8.31, date: new Date('2024-08-15T22:00:00Z') },
+     *   { minAltitude: 15, magnitudeLimit: 5, types: ['nebula', 'cluster', 'galaxy'] }
+     * )
+     * ```
+     */
+    readonly whatsUp: (observer: ObserverParams, options?: WhatsUpOptions) => VisibleObject[];
+    /**
+     * Find the best observation window for an object on a given night.
+     *
+     * Samples the object's altitude between astronomical dusk and dawn,
+     * returning the peak altitude time and the rise/set times relative
+     * to the minimum observable altitude.
+     *
+     * @param objectId - Catalog object ID (e.g. `'m42'`, `'sirius'`, `'jupiter'`).
+     * @param observer - Observer location and date (date determines which night).
+     * @param minAlt - Minimum useful altitude in degrees. @defaultValue `10`
+     * @returns The best window, or `null` if the object is never above `minAlt` during darkness.
+     *
+     * @example
+     * ```ts
+     * const window = Planner.bestWindow('m42', { lat: 47.05, lng: 8.31, date: new Date('2024-01-15') })
+     * if (window) {
+     *   console.log('Peak at', window.peak, `(${window.peakAltitude.toFixed(1)}°)`)
+     * }
+     * ```
+     */
+    readonly bestWindow: (objectId: string, observer: ObserverParams, minAlt?: number) => BestWindowResult | null;
+    /**
+     * Compute altitude vs. time for an object over a night.
+     *
+     * Returns an array of altitude/azimuth samples from astronomical dusk
+     * to astronomical dawn, suitable for plotting a visibility curve.
+     *
+     * @param objectId - Catalog object ID.
+     * @param observer - Observer location and date.
+     * @param steps - Number of samples. @defaultValue `100`
+     * @returns Array of time/alt/az points, or `null` if the object is unknown or no darkness occurs.
+     *
+     * @example
+     * ```ts
+     * const curve = Planner.visibilityCurve('sirius', { lat: 47.05, lng: 8.31, date: new Date('2024-01-15') })
+     * // Plot curve.map(p => ({ x: p.date, y: p.alt }))
+     * ```
+     */
+    readonly visibilityCurve: (objectId: string, observer: ObserverParams, steps?: number) => VisibilityCurvePoint[] | null;
+    /**
+     * Detect oppositions and conjunctions for outer planets near a given date.
+     *
+     * Scans a date range (default: 1 year forward) for dates where a planet's
+     * elongation from the Sun is near 180° (opposition) or 0° (conjunction).
+     *
+     * @param observer - Observer with date as the start of the search range.
+     * @param options - Search options.
+     * @returns Array of detected planet events, sorted by date.
+     *
+     * @example
+     * ```ts
+     * const events = Planner.planetEvents({ lat: 47, lng: 8, date: new Date('2024-01-01') })
+     * events.forEach(e => console.log(e.planet, e.type, e.date.toISOString()))
+     * ```
+     */
+    readonly planetEvents: (observer: ObserverParams, options?: {
+        planets?: PlanetName[];
+        days?: number;
+    }) => PlanetEvent[];
+    /**
+     * Moon interference score for a specific target.
+     *
+     * Combines angular separation from the Moon with the current lunar
+     * illumination to produce a 0–1 interference score. Score of 0 means
+     * no interference (new moon or far away), 1 means maximum interference
+     * (full moon very close to the target).
+     *
+     * @param objectId - Catalog object ID.
+     * @param observer - Observer location and time.
+     * @returns Moon interference details, or `null` if the object is unknown.
+     *
+     * @example
+     * ```ts
+     * const mi = Planner.moonInterference('m42', { lat: 47, lng: 8, date: new Date() })
+     * if (mi && mi.score > 0.5) console.log('Significant moon interference!')
+     * ```
+     */
+    readonly moonInterference: (objectId: string, observer: ObserverParams) => MoonInterference | null;
+    /**
+     * Airmass curve for an object over a night.
+     *
+     * Returns airmass values (using Kasten & Young 1989 formula) sampled
+     * from astronomical dusk to dawn. Airmass is 1.0 at zenith and increases
+     * toward the horizon. Only points where the object is above the horizon
+     * are included (airmass at or below 0° altitude is infinite).
+     *
+     * @param objectId - Catalog object ID.
+     * @param observer - Observer location and date.
+     * @param steps - Number of samples. @defaultValue `100`
+     * @returns Array of time/alt/airmass points (only above-horizon), or `null`.
+     *
+     * @example
+     * ```ts
+     * const am = Planner.airmassCurve('sirius', { lat: 47, lng: 8, date: new Date('2024-01-15') })
+     * // Plot am.map(p => ({ x: p.date, y: p.airmass }))
+     * ```
+     */
+    readonly airmassCurve: (objectId: string, observer: ObserverParams, steps?: number) => AirmassPoint[] | null;
+};

package/dist/react/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const m=require("react/jsx-runtime"),c=require("react"),i=require("../skymap-interactive-D2OZFwJ7.cjs"),D=typeof window<"u";function C(e,t,s=1e4){const[o,f]=c.useState(null);return c.useEffect(()=>{const a=()=>{const u=i.Data.get(e);if(!u){f(null);return}const p=new Date,r=q(u,p);if(!r){f(null);return}f(i.AstroMath.equatorialToHorizontal(r,{...t,date:p}))};if(a(),!D)return;const h=setInterval(a,s);return()=>clearInterval(h)},[e,t.lat,t.lng,s]),o}function E(e,t=6e4){const[s,o]=c.useState(()=>i.Moon.phase(e??new Date));return c.useEffect(()=>{if(e){o(i.Moon.phase(e));return}const f=()=>o(i.Moon.phase(new Date));if(f(),!D)return;const a=setInterval(f,t);return()=>clearInterval(a)},[e==null?void 0:e.valueOf(),t]),s}function M(e={}){const[t,s]=c.useState(()=>e.startDate??new Date),[o,f]=c.useState(e.speed??1),[a,h]=c.useState(e.autoPlay??!1),u=c.useRef(null);u.current===null&&(u.current=new i.AstroClock(e)),c.useEffect(()=>{const n=u.current,d=k=>s(k.date),g=()=>h(!0),S=()=>h(!1),l=k=>s(k.date),P=k=>f(k.speed);return n.on("tick",d),n.on("play",g),n.on("pause",S),n.on("datechange",l),n.on("speedchange",P),()=>{n.off("tick",d),n.off("play",g),n.off("pause",S),n.off("datechange",l),n.off("speedchange",P),n.dispose(),u.current=null}},[]);const p=c.useCallback(()=>{var n;return(n=u.current)==null?void 0:n.play()},[]),r=c.useCallback(()=>{var n;return(n=u.current)==null?void 0:n.pause()},[]),y=c.useCallback(n=>{var d;return(d=u.current)==null?void 0:d.setDate(n)},[]),w=c.useCallback(n=>{var d;return(d=u.current)==null?void 0:d.setSpeed(n)},[]);return{date:t,speed:o,playing:a,play:p,pause:r,setDate:y,setSpeed:w,clock:u.current}}function v(e,t={},s=3e4){var a,h;const[o,f]=c.useState([]);return c.useEffect(()=>{const u=()=>{const r={...e,date:e.date??new Date};f(i.Planner.whatsUp(r,t))};if(u(),!D)return;const p=setInterval(u,s);return()=>clearInterval(p)},[e.lat,e.lng,(a=e.date)==null?void 0:a.valueOf(),s,t.minAltitude,t.magnitudeLimit,t.limit,t.tag,t.constellation,(h=t.types)==null?void 0:h.join(",")]),o}function x(e,t){var s;return c.useMemo(()=>{const o={...e,date:t??e.date??new Date};return i.Sun.twilight(o)},[e.lat,e.lng,t==null?void 0:t.valueOf(),(s=e.date)==null?void 0:s.valueOf()])}function I({objects:e,width:t="100%",height:s="400px",onSelect:o,onHover:f,skymapRef:a,...h}){const u=c.useRef(null),p=c.useRef(null);return c.useEffect(()=>{const r=u.current;if(!r||!D)return;const y=r.parentElement;if(!y)return;const w=window.devicePixelRatio||1,n=y.getBoundingClientRect();r.width=n.width*w,r.height=n.height*w,r.style.width=`${n.width}px`,r.style.height=`${n.height}px`;const d=e??i.Data.all().filter(l=>l.ra!=null&&l.dec!=null),g=new i.InteractiveSkyMap(r,d,h);p.current=g,a&&"current"in a&&(a.current=g),o&&g.on("select",({object:l})=>o(l)),f&&g.on("hover",({object:l})=>f(l));const S=()=>{const l=y.getBoundingClientRect();r.width=l.width*w,r.height=l.height*w,r.style.width=`${l.width}px`,r.style.height=`${l.height}px`,g.render()};return window.addEventListener("resize",S),()=>{window.removeEventListener("resize",S),g.dispose(),p.current=null,a&&"current"in a&&(a.current=null)}},[]),m.jsx("div",{style:{width:t,height:s,position:"relative"},children:m.jsx("canvas",{ref:u,style:{width:"100%",height:"100%",display:"block"},"aria-label":"Interactive sky map"})})}function q(e,t){if(e.ra!==null&&e.dec!==null)return{ra:e.ra,dec:e.dec};if(e.type==="planet")try{const s=i.AstroMath.planetEcliptic(e.id,t);return i.AstroMath.eclipticToEquatorial(s)}catch{return null}if(e.id==="sun"){const s=i.Sun.position(t);return{ra:s.ra,dec:s.dec}}if(e.id==="moon"){const s=i.Moon.position(t);return{ra:s.ra,dec:s.dec}}return null}exports.SkyMap=I;exports.useAstroClock=M;exports.useMoonPhase=E;exports.useSkyPosition=C;exports.useTwilight=x;exports.useWhatsUp=v;

package/dist/react/index.d.ts

@@ -0,0 +1,167 @@
+/**
+ * React hooks for `@motioncomplex/cosmos-lib`.
+ *
+ * Import from the `/react` sub-path:
+ *
+ * ```ts
+ * import { useSkyPosition, useMoonPhase, useWhatsUp } from '@motioncomplex/cosmos-lib/react'
+ * ```
+ *
+ * All hooks are SSR-safe — they return sensible defaults during server
+ * rendering and only start intervals/effects in the browser. React is an
+ * optional peer dependency; this module is not included in the core bundle.
+ *
+ * @packageDocumentation
+ */
+import { type RefObject } from 'react';
+import { AstroClock } from '../clock.js';
+import { InteractiveSkyMap } from '../skymap-interactive.js';
+import type { ObserverParams, HorizontalCoord, MoonPhase, TwilightTimes, CelestialObject, InteractiveSkyMapOptions } from '../types.js';
+import type { VisibleObject, WhatsUpOptions } from '../planner.js';
+import type { AstroClockOptions } from '../clock.js';
+/**
+ * Reactive altitude/azimuth for any catalog object.
+ *
+ * Recomputes the horizontal position at a configurable interval (default 10s).
+ * For solar-system bodies, dynamically computes the current RA/Dec.
+ *
+ * @param objectId - Catalog object ID (e.g. `'sirius'`, `'mars'`, `'m42'`).
+ * @param observer - Observer location.
+ * @param intervalMs - Update interval in milliseconds. @defaultValue `10000`
+ * @returns Current `{ alt, az }` or `null` if the object is unknown.
+ *
+ * @example
+ * ```tsx
+ * const pos = useSkyPosition('sirius', { lat: 47.05, lng: 8.31 })
+ * return <p>Sirius: {pos?.alt.toFixed(1)}° alt</p>
+ * ```
+ */
+export declare function useSkyPosition(objectId: string, observer: ObserverParams, intervalMs?: number): HorizontalCoord | null;
+/**
+ * Reactive Moon phase data.
+ *
+ * Returns current phase, illumination, age, and name, updating at
+ * the specified interval (default 60s).
+ *
+ * @param date - Fixed date, or omit for live updates.
+ * @param intervalMs - Update interval in ms (only used when `date` is omitted). @defaultValue `60000`
+ * @returns Current {@link MoonPhase} data.
+ *
+ * @example
+ * ```tsx
+ * const phase = useMoonPhase()
+ * return <p>{phase.name} — {(phase.illumination * 100).toFixed(0)}%</p>
+ * ```
+ */
+export declare function useMoonPhase(date?: Date, intervalMs?: number): MoonPhase;
+/** Return value of {@link useAstroClock}. */
+export interface UseAstroClockReturn {
+    /** Current simulation date (updates on each tick). */
+    date: Date;
+    /** Current speed multiplier. */
+    speed: number;
+    /** Whether the clock is playing. */
+    playing: boolean;
+    /** Start or resume playback. */
+    play: () => void;
+    /** Pause playback. */
+    pause: () => void;
+    /** Set the simulation date. */
+    setDate: (date: Date) => void;
+    /** Set the speed multiplier. */
+    setSpeed: (speed: number) => void;
+    /** The underlying AstroClock instance. */
+    clock: AstroClock;
+}
+/**
+ * AstroClock instance managed by React lifecycle.
+ *
+ * Creates, controls, and disposes an {@link AstroClock} automatically.
+ * State updates (date, speed, playing) trigger re-renders.
+ *
+ * @param options - AstroClock options.
+ * @returns Controls and reactive state for the clock.
+ *
+ * @example
+ * ```tsx
+ * const { date, playing, play, pause, setSpeed } = useAstroClock({ speed: 60 })
+ * return (
+ *   <div>
+ *     <p>{date.toLocaleTimeString()}</p>
+ *     <button onClick={playing ? pause : play}>{playing ? 'Pause' : 'Play'}</button>
+ *   </div>
+ * )
+ * ```
+ */
+export declare function useAstroClock(options?: AstroClockOptions): UseAstroClockReturn;
+/**
+ * Reactive list of visible objects above the horizon.
+ *
+ * Recomputes at the specified interval using {@link Planner.whatsUp}.
+ *
+ * @param observer - Observer location.
+ * @param options - WhatsUp filtering options.
+ * @param intervalMs - Update interval in ms. @defaultValue `30000`
+ * @returns Array of visible objects with alt/az and moon interference.
+ *
+ * @example
+ * ```tsx
+ * const visible = useWhatsUp({ lat: 47, lng: 8 }, { magnitudeLimit: 4, limit: 10 })
+ * return <ul>{visible.map(v => <li key={v.object.id}>{v.object.name} ({v.alt.toFixed(0)}°)</li>)}</ul>
+ * ```
+ */
+export declare function useWhatsUp(observer: ObserverParams, options?: WhatsUpOptions, intervalMs?: number): VisibleObject[];
+/**
+ * Reactive twilight times (sunrise, sunset, dawn, dusk).
+ *
+ * Recomputes daily or when the observer changes.
+ *
+ * @param observer - Observer location.
+ * @param date - Fixed date, or omit for today.
+ * @returns {@link TwilightTimes} for the given location and date.
+ *
+ * @example
+ * ```tsx
+ * const tw = useTwilight({ lat: 51.5, lng: -0.1 })
+ * return <p>Sunset: {tw.sunset?.toLocaleTimeString()}</p>
+ * ```
+ */
+export declare function useTwilight(observer: ObserverParams, date?: Date): TwilightTimes;
+/** Props for {@link SkyMap}. */
+export interface SkyMapProps extends InteractiveSkyMapOptions {
+    /** Objects to render. Defaults to `Data.all()`. */
+    objects?: CelestialObject[];
+    /** Width CSS value. @defaultValue `'100%'` */
+    width?: string | number;
+    /** Height CSS value. @defaultValue `'400px'` */
+    height?: string | number;
+    /** Callback when an object is selected. */
+    onSelect?: (object: CelestialObject) => void;
+    /** Callback when a hover changes. */
+    onHover?: (object: CelestialObject | null) => void;
+    /** Ref to access the underlying InteractiveSkyMap instance. */
+    skymapRef?: RefObject<InteractiveSkyMap | null>;
+}
+/**
+ * React component wrapping {@link InteractiveSkyMap}.
+ *
+ * Manages canvas lifecycle, DPI scaling, resize handling, and event
+ * wiring automatically. SSR-safe — renders an empty `<canvas>` on the
+ * server and initialises the sky map on mount.
+ *
+ * @example
+ * ```tsx
+ * import { SkyMap } from '@motioncomplex/cosmos-lib/react'
+ *
+ * <SkyMap
+ *   projection="stereographic"
+ *   center={{ ra: 83.8, dec: -5.4 }}
+ *   scale={400}
+ *   observer={{ lat: 47.05, lng: 8.31 }}
+ *   onSelect={obj => console.log(obj.name)}
+ *   width="100%"
+ *   height="500px"
+ * />
+ * ```
+ */
+export declare function SkyMap({ objects, width, height, onSelect, onHover, skymapRef, ...opts }: SkyMapProps): import("react/jsx-runtime").JSX.Element;

package/dist/react/index.js

@@ -0,0 +1,163 @@
+import { jsx as C } from "react/jsx-runtime";
+import { useRef as v, useEffect as D, useState as g, useCallback as P, useMemo as q } from "react";
+import { D as E, I as z, b as F, M as k, S as A, A as x, P as M } from "../skymap-interactive-CLg6FA0X.js";
+const S = typeof window < "u";
+function B(t, e, r = 1e4) {
+  const [l, u] = g(null);
+  return D(() => {
+    const a = () => {
+      const c = E.get(t);
+      if (!c) {
+        u(null);
+        return;
+      }
+      const f = /* @__PURE__ */ new Date(), s = O(c, f);
+      if (!s) {
+        u(null);
+        return;
+      }
+      u(x.equatorialToHorizontal(s, { ...e, date: f }));
+    };
+    if (a(), !S) return;
+    const d = setInterval(a, r);
+    return () => clearInterval(d);
+  }, [t, e.lat, e.lng, r]), l;
+}
+function L(t, e = 6e4) {
+  const [r, l] = g(() => k.phase(t ?? /* @__PURE__ */ new Date()));
+  return D(() => {
+    if (t) {
+      l(k.phase(t));
+      return;
+    }
+    const u = () => l(k.phase(/* @__PURE__ */ new Date()));
+    if (u(), !S) return;
+    const a = setInterval(u, e);
+    return () => clearInterval(a);
+  }, [t == null ? void 0 : t.valueOf(), e]), r;
+}
+function U(t = {}) {
+  const [e, r] = g(() => t.startDate ?? /* @__PURE__ */ new Date()), [l, u] = g(t.speed ?? 1), [a, d] = g(t.autoPlay ?? !1), c = v(null);
+  c.current === null && (c.current = new F(t)), D(() => {
+    const n = c.current, o = (m) => r(m.date), h = () => d(!0), y = () => d(!1), i = (m) => r(m.date), I = (m) => u(m.speed);
+    return n.on("tick", o), n.on("play", h), n.on("pause", y), n.on("datechange", i), n.on("speedchange", I), () => {
+      n.off("tick", o), n.off("play", h), n.off("pause", y), n.off("datechange", i), n.off("speedchange", I), n.dispose(), c.current = null;
+    };
+  }, []);
+  const f = P(() => {
+    var n;
+    return (n = c.current) == null ? void 0 : n.play();
+  }, []), s = P(() => {
+    var n;
+    return (n = c.current) == null ? void 0 : n.pause();
+  }, []), w = P((n) => {
+    var o;
+    return (o = c.current) == null ? void 0 : o.setDate(n);
+  }, []), p = P((n) => {
+    var o;
+    return (o = c.current) == null ? void 0 : o.setSpeed(n);
+  }, []);
+  return {
+    date: e,
+    speed: l,
+    playing: a,
+    play: f,
+    pause: s,
+    setDate: w,
+    setSpeed: p,
+    clock: c.current
+  };
+}
+function W(t, e = {}, r = 3e4) {
+  var a, d;
+  const [l, u] = g([]);
+  return D(() => {
+    const c = () => {
+      const s = { ...t, date: t.date ?? /* @__PURE__ */ new Date() };
+      u(M.whatsUp(s, e));
+    };
+    if (c(), !S) return;
+    const f = setInterval(c, r);
+    return () => clearInterval(f);
+  }, [
+    t.lat,
+    t.lng,
+    (a = t.date) == null ? void 0 : a.valueOf(),
+    r,
+    e.minAltitude,
+    e.magnitudeLimit,
+    e.limit,
+    e.tag,
+    e.constellation,
+    (d = e.types) == null ? void 0 : d.join(",")
+  ]), l;
+}
+function G(t, e) {
+  var r;
+  return q(() => {
+    const l = { ...t, date: e ?? t.date ?? /* @__PURE__ */ new Date() };
+    return A.twilight(l);
+  }, [t.lat, t.lng, e == null ? void 0 : e.valueOf(), (r = t.date) == null ? void 0 : r.valueOf()]);
+}
+function H({
+  objects: t,
+  width: e = "100%",
+  height: r = "400px",
+  onSelect: l,
+  onHover: u,
+  skymapRef: a,
+  ...d
+}) {
+  const c = v(null), f = v(null);
+  return D(() => {
+    const s = c.current;
+    if (!s || !S) return;
+    const w = s.parentElement;
+    if (!w) return;
+    const p = window.devicePixelRatio || 1, n = w.getBoundingClientRect();
+    s.width = n.width * p, s.height = n.height * p, s.style.width = `${n.width}px`, s.style.height = `${n.height}px`;
+    const o = t ?? E.all().filter((i) => i.ra != null && i.dec != null), h = new z(s, o, d);
+    f.current = h, a && "current" in a && (a.current = h), l && h.on("select", ({ object: i }) => l(i)), u && h.on("hover", ({ object: i }) => u(i));
+    const y = () => {
+      const i = w.getBoundingClientRect();
+      s.width = i.width * p, s.height = i.height * p, s.style.width = `${i.width}px`, s.style.height = `${i.height}px`, h.render();
+    };
+    return window.addEventListener("resize", y), () => {
+      window.removeEventListener("resize", y), h.dispose(), f.current = null, a && "current" in a && (a.current = null);
+    };
+  }, []), /* @__PURE__ */ C("div", { style: { width: e, height: r, position: "relative" }, children: /* @__PURE__ */ C(
+    "canvas",
+    {
+      ref: c,
+      style: { width: "100%", height: "100%", display: "block" },
+      "aria-label": "Interactive sky map"
+    }
+  ) });
+}
+function O(t, e) {
+  if (t.ra !== null && t.dec !== null) return { ra: t.ra, dec: t.dec };
+  if (t.type === "planet")
+    try {
+      const r = x.planetEcliptic(t.id, e);
+      return x.eclipticToEquatorial(r);
+    } catch {
+      return null;
+    }
+  if (t.id === "sun") {
+    const r = A.position(e);
+    return { ra: r.ra, dec: r.dec };
+  }
+  if (t.id === "moon") {
+    const r = k.position(e);
+    return { ra: r.ra, dec: r.dec };
+  }
+  return null;
+}
+export {
+  H as SkyMap,
+  U as useAstroClock,
+  L as useMoonPhase,
+  B as useSkyPosition,
+  G as useTwilight,
+  W as useWhatsUp
+};

package/dist/skymap-hittest.d.ts

@@ -0,0 +1,69 @@
+import type { EquatorialCoord, ProjectedObject, ProjectionName } from './types.js';
+/**
+ * Inverse stereographic projection.
+ *
+ * Converts pixel offsets (relative to canvas centre, with y increasing
+ * **upward**) back to equatorial coordinates given the projection centre
+ * and scale.
+ *
+ * @param px     - Horizontal pixel offset from canvas centre.
+ * @param py     - Vertical pixel offset from canvas centre (positive = up).
+ * @param center - Projection centre in equatorial coordinates.
+ * @param scale  - Pixel scale factor (same value passed to the forward projection).
+ * @returns The equatorial coordinate, or `null` if the point is at the
+ *          antipodal singularity.
+ */
+export declare function stereographicInverse(px: number, py: number, center: EquatorialCoord, scale: number): EquatorialCoord | null;
+/**
+ * Inverse gnomonic (tangent-plane) projection.
+ *
+ * @param px     - Horizontal pixel offset from canvas centre.
+ * @param py     - Vertical pixel offset from canvas centre (positive = up).
+ * @param center - Projection tangent point in equatorial coordinates.
+ * @param scale  - Pixel scale factor.
+ * @returns The equatorial coordinate, or `null` if the result is invalid.
+ */
+export declare function gnomonicInverse(px: number, py: number, center: EquatorialCoord, scale: number): EquatorialCoord | null;
+/**
+ * Inverse Mollweide (equal-area) projection.
+ *
+ * Takes **absolute** canvas pixel coordinates (matching the forward
+ * projection output) and returns equatorial coordinates.
+ *
+ * @param canvasX - Absolute x pixel position on the canvas.
+ * @param canvasY - Absolute y pixel position on the canvas.
+ * @param width   - Canvas width in pixels.
+ * @param height  - Canvas height in pixels.
+ * @returns The equatorial coordinate, or `null` if the point falls outside
+ *          the Mollweide ellipse boundary.
+ */
+export declare function mollweideInverse(canvasX: number, canvasY: number, width: number, height: number): EquatorialCoord | null;
+/**
+ * Convert a canvas pixel position to equatorial coordinates.
+ *
+ * Dispatches to the appropriate inverse projection based on the current
+ * projection mode. The `canvasX` / `canvasY` values should be in the
+ * **canvas coordinate space** (i.e. after accounting for DPI scaling).
+ *
+ * @param canvasX    - Pixel x on the canvas.
+ * @param canvasY    - Pixel y on the canvas.
+ * @param width      - Canvas width in pixels.
+ * @param height     - Canvas height in pixels.
+ * @param projection - Active projection mode.
+ * @param center     - Current view centre (ignored for Mollweide).
+ * @param scale      - Current zoom scale factor (ignored for Mollweide).
+ * @returns The equatorial coordinate at that pixel, or `null` if outside
+ *          the valid projection area.
+ */
+export declare function canvasToEquatorial(canvasX: number, canvasY: number, width: number, height: number, projection: ProjectionName, center: EquatorialCoord, scale: number): EquatorialCoord | null;
+/**
+ * Find the nearest projected object within a pixel radius of a given point.
+ *
+ * @param cache     - Array of projected objects (rebuilt each render frame).
+ * @param canvasX   - Pixel x on the canvas.
+ * @param canvasY   - Pixel y on the canvas.
+ * @param hitRadius - Maximum distance in pixels to consider a match.
+ * @returns The closest {@link ProjectedObject}, or `null` if nothing is
+ *          within range.
+ */
+export declare function hitTest(cache: readonly ProjectedObject[], canvasX: number, canvasY: number, hitRadius: number): ProjectedObject | null;