@motioncomplex/cosmos-lib 1.0.9

package/dist/media-DVOcIMa1.js

@@ -0,0 +1,252 @@
+const d = {
+  /**
+   * Try a list of image URLs in order and resolve with the first one
+   * that loads successfully.
+   *
+   * Each URL is attempted sequentially; when an image fires its `load`
+   * event the promise resolves immediately with that URL. If every URL
+   * fires an `error` event the promise is rejected.
+   *
+   * @param urls - Ordered array of image URLs to attempt, from most
+   *               preferred to least preferred.
+   *
+   * @returns The first URL that loaded successfully.
+   *
+   * @throws {Error} If every URL in the list fails to load.
+   *
+   * @example
+   * ```ts
+   * const url = await Media.chainLoad([
+   *   'https://esahubble.org/media/archives/images/original/heic0506a.tif',
+   *   'https://esahubble.org/media/archives/images/large/heic0506a.jpg',
+   *   'https://esahubble.org/media/archives/images/screen/heic0506a.jpg',
+   * ])
+   * ```
+   */
+  chainLoad(t) {
+    return new Promise((a, e) => {
+      const o = (i) => {
+        const [r, ...s] = i;
+        if (r === void 0) {
+          e(new Error("All image URLs failed to load."));
+          return;
+        }
+        const n = new Image();
+        n.onload = () => a(r), n.onerror = () => o(s), n.src = r;
+      };
+      o([...t]);
+    });
+  },
+  /**
+   * Progressive image loader that shows a blurred placeholder immediately,
+   * then upgrades through quality tiers as each resolves.
+   *
+   * Works on both `<img>` elements (sets `src`) and any other
+   * `HTMLElement` (sets `background-image`). A CSS blur filter is applied
+   * while the placeholder is shown, then removed with a smooth transition
+   * once the full-quality image is ready.
+   *
+   * @param target - The DOM element to receive the image. Can be an
+   *                 `HTMLImageElement` or any `HTMLElement` with a
+   *                 background-image style.
+   * @param opts   - Image source configuration. See
+   *                 {@link ProgressiveImageOptions}.
+   *
+   * @returns Resolves when the highest available quality tier has been
+   *          applied (or all tiers have been attempted).
+   *
+   * @example
+   * ```ts
+   * const hero = document.getElementById('hero-image')!
+   * await Media.progressive(hero, {
+   *   placeholder: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...',
+   *   src:   'https://cdn.example.com/andromeda-1280.jpg',
+   *   srcHD: 'https://cdn.example.com/andromeda-4k.jpg',
+   * })
+   * ```
+   */
+  async progressive(t, a) {
+    const { placeholder: e, src: o, srcHD: i } = a, r = (s, n) => {
+      t instanceof HTMLImageElement ? t.src = s : t.style.backgroundImage = `url('${s}')`, t.style.filter = n ? "blur(10px) saturate(0.6)" : "", t.style.transition = "filter 0.5s ease";
+    };
+    e && r(e, !0);
+    try {
+      await this._loadImage(o), r(o, !1);
+    } catch {
+    }
+    if (i)
+      try {
+        await this._loadImage(i), r(i, !1);
+      } catch {
+      }
+  },
+  /**
+   * Preload a list of images in the background using concurrent fetches.
+   *
+   * All URLs are loaded in parallel via `Promise.allSettled`. URLs that
+   * fail to load are silently dropped; only successfully loaded URLs are
+   * returned.
+   *
+   * @param urls - Array of image URLs to preload.
+   *
+   * @returns The subset of `urls` that loaded successfully, preserving
+   *          original order.
+   *
+   * @example
+   * ```ts
+   * const loaded = await Media.preload([
+   *   'https://cdn.example.com/m31-thumb.jpg',
+   *   'https://cdn.example.com/m42-thumb.jpg',
+   *   'https://cdn.example.com/m45-thumb.jpg',
+   * ])
+   * console.log(`${loaded.length} of 3 images cached`)
+   * ```
+   */
+  async preload(t) {
+    return (await Promise.allSettled(t.map((e) => this._loadImage(e)))).filter((e) => e.status === "fulfilled").map((e) => e.value);
+  },
+  /**
+   * Build a Wikimedia Commons URL for a given filename.
+   *
+   * Uses the `Special:FilePath` redirect, which resolves to the correct
+   * CDN path without requiring the internal MD5 hash. When a `width` is
+   * provided, the Wikimedia thumbnail API generates a resized version
+   * server-side.
+   *
+   * @param filename - The Wikimedia Commons filename, including extension
+   *                   (e.g. `'Orion_Nebula_-_Hubble_2006_mosaic_18000.jpg'`).
+   * @param width    - Optional pixel width for on-the-fly thumbnail
+   *                   generation. Omit to get the original-resolution file.
+   *
+   * @returns A fully-qualified Wikimedia Commons URL.
+   *
+   * @example
+   * ```ts
+   * // Original resolution
+   * Media.wikimediaUrl('Orion_Nebula_-_Hubble_2006_mosaic_18000.jpg')
+   * // => 'https://commons.wikimedia.org/wiki/Special:FilePath/Orion_Nebula...'
+   *
+   * // 800px thumbnail
+   * Media.wikimediaUrl('Crab_Nebula.jpg', 800)
+   * // => 'https://commons.wikimedia.org/wiki/Special:FilePath/Crab_Nebula.jpg?width=800'
+   * ```
+   */
+  wikimediaUrl(t, a) {
+    const e = `https://commons.wikimedia.org/wiki/Special:FilePath/${encodeURIComponent(t)}`;
+    return a ? `${e}?width=${a}` : e;
+  },
+  /**
+   * Build a Cloudinary URL with on-the-fly resizing and format optimisation.
+   *
+   * Constructs a Cloudinary delivery URL using the `image/upload` path
+   * with the specified transformations. Defaults to `crop: 'fill'`,
+   * `quality: 'auto'`, and `format: 'auto'` when not overridden.
+   *
+   * @param cloudName - Your Cloudinary cloud name (e.g. `'my-astro-cloud'`).
+   * @param publicId  - The image's public ID in your Cloudinary media
+   *                    library (e.g. `'nebulae/m42-mosaic'`).
+   * @param opts      - Transformation options. See {@link CloudinaryOptions}.
+   *
+   * @returns A fully-qualified Cloudinary delivery URL with transformations.
+   *
+   * @example
+   * ```ts
+   * const url = Media.cloudinaryUrl('my-astro-cloud', 'nebulae/m42-mosaic', {
+   *   w: 1280,
+   *   h: 720,
+   *   q: 80,
+   *   f: 'webp',
+   *   crop: 'fill',
+   * })
+   * // => 'https://res.cloudinary.com/my-astro-cloud/image/upload/c_fill,f_webp,q_80,w_1280,h_720/nebulae/m42-mosaic'
+   * ```
+   */
+  cloudinaryUrl(t, a, e = {}) {
+    const { w: o, h: i, q: r = "auto", f: s = "auto", crop: n = "fill" } = e, l = [
+      `c_${n}`,
+      `f_${s}`,
+      `q_${r}`,
+      o ? `w_${o}` : null,
+      i ? `h_${i}` : null
+    ].filter((c) => c !== null).join(",");
+    return `https://res.cloudinary.com/${t}/image/upload/${l}/${a}`;
+  },
+  /**
+   * Generate an HTML `srcset` attribute value for responsive images.
+   *
+   * Maps each width to a URL via the `transformer` callback and joins
+   * them into a comma-separated descriptor string suitable for use in
+   * an `<img srcset="...">` or `<source srcset="...">` attribute.
+   *
+   * @param widths      - Array of pixel widths to include (e.g.
+   *                      `[640, 1280, 1920]`).
+   * @param transformer - A function that receives a width in pixels and
+   *                      returns the corresponding image URL.
+   *
+   * @returns A `srcset`-formatted string (e.g.
+   *          `'https://cdn.example.com/img?w=640 640w, ...`).
+   *
+   * @example
+   * ```ts
+   * const set = Media.srcset([640, 1280, 1920], w =>
+   *   Media.cloudinaryUrl('my-cloud', 'galaxy/ngc1300', { w, f: 'webp' }),
+   * )
+   * // Use in an <img> tag:
+   * // <img srcset={set} sizes="100vw" />
+   * ```
+   */
+  srcset(t, a) {
+    return t.map((e) => `${a(e)} ${e}w`).join(", ");
+  },
+  /**
+   * Return the optimal image dimensions (in physical pixels) for a given
+   * container element, accounting for `window.devicePixelRatio`.
+   *
+   * Multiplies the element's CSS layout size by the device pixel ratio so
+   * that images are sharp on high-DPI (Retina) displays. Falls back to a
+   * ratio of `1` when `devicePixelRatio` is unavailable.
+   *
+   * @param element - The DOM element whose bounding box determines the
+   *                  target dimensions.
+   *
+   * @returns An object with `width` and `height` in physical (device)
+   *          pixels, rounded to the nearest integer.
+   *
+   * @example
+   * ```ts
+   * const container = document.getElementById('galaxy-viewer')!
+   * const { width, height } = Media.optimalSize(container)
+   * const url = Media.cloudinaryUrl('my-cloud', 'galaxy/ngc1300', {
+   *   w: width,
+   *   h: height,
+   * })
+   * ```
+   */
+  optimalSize(t) {
+    const a = t.getBoundingClientRect(), e = window.devicePixelRatio || 1;
+    return {
+      width: Math.round(a.width * e),
+      height: Math.round(a.height * e)
+    };
+  },
+  // ── Private ────────────────────────────────────────────────────────────────
+  /**
+   * Load a single image by URL using the DOM `Image` constructor.
+   *
+   * @internal This is an implementation detail used by {@link Media.chainLoad},
+   * {@link Media.progressive}, and {@link Media.preload}. It is not part of
+   * the public API and may change without notice.
+   *
+   * @param url - The image URL to load.
+   * @returns Resolves with the URL on successful load; rejects on error.
+   */
+  _loadImage(t) {
+    return new Promise((a, e) => {
+      const o = new Image();
+      o.onload = () => a(t), o.onerror = () => e(new Error(`Failed to load image: ${t}`)), o.src = t;
+    });
+  }
+};
+export {
+  d as M
+};

package/dist/media-DlE7RKBL.cjs

@@ -0,0 +1 @@
+"use strict";const d={chainLoad(t){return new Promise((a,e)=>{const o=r=>{const[i,...s]=r;if(i===void 0){e(new Error("All image URLs failed to load."));return}const n=new Image;n.onload=()=>a(i),n.onerror=()=>o(s),n.src=i};o([...t])})},async progressive(t,a){const{placeholder:e,src:o,srcHD:r}=a,i=(s,n)=>{t instanceof HTMLImageElement?t.src=s:t.style.backgroundImage=`url('${s}')`,t.style.filter=n?"blur(10px) saturate(0.6)":"",t.style.transition="filter 0.5s ease"};e&&i(e,!0);try{await this._loadImage(o),i(o,!1)}catch{}if(r)try{await this._loadImage(r),i(r,!1)}catch{}},async preload(t){return(await Promise.allSettled(t.map(e=>this._loadImage(e)))).filter(e=>e.status==="fulfilled").map(e=>e.value)},wikimediaUrl(t,a){const e=`https://commons.wikimedia.org/wiki/Special:FilePath/${encodeURIComponent(t)}`;return a?`${e}?width=${a}`:e},cloudinaryUrl(t,a,e={}){const{w:o,h:r,q:i="auto",f:s="auto",crop:n="fill"}=e,l=[`c_${n}`,`f_${s}`,`q_${i}`,o?`w_${o}`:null,r?`h_${r}`:null].filter(c=>c!==null).join(",");return`https://res.cloudinary.com/${t}/image/upload/${l}/${a}`},srcset(t,a){return t.map(e=>`${a(e)} ${e}w`).join(", ")},optimalSize(t){const a=t.getBoundingClientRect(),e=window.devicePixelRatio||1;return{width:Math.round(a.width*e),height:Math.round(a.height*e)}},_loadImage(t){return new Promise((a,e)=>{const o=new Image;o.onload=()=>a(t),o.onerror=()=>e(new Error(`Failed to load image: ${t}`)),o.src=t})}};exports.Media=d;

package/dist/media.d.ts

@@ -0,0 +1,217 @@
+import type { ProgressiveImageOptions, CloudinaryOptions } from './types.js';
+/**
+ * Browser-side utilities for loading, transforming, and optimising
+ * astronomical imagery.
+ *
+ * All methods that load images use the DOM `Image` constructor and are
+ * therefore intended for browser environments only.
+ *
+ * @example
+ * ```ts
+ * import { Media } from 'cosmos-lib'
+ *
+ * // Load the best available image from a priority list
+ * const url = await Media.chainLoad([
+ *   'https://cdn.example.com/nebula-hd.jpg',
+ *   'https://cdn.example.com/nebula-sd.jpg',
+ * ])
+ * document.querySelector('img')!.src = url
+ * ```
+ */
+export declare const Media: {
+    /**
+     * Try a list of image URLs in order and resolve with the first one
+     * that loads successfully.
+     *
+     * Each URL is attempted sequentially; when an image fires its `load`
+     * event the promise resolves immediately with that URL. If every URL
+     * fires an `error` event the promise is rejected.
+     *
+     * @param urls - Ordered array of image URLs to attempt, from most
+     *               preferred to least preferred.
+     *
+     * @returns The first URL that loaded successfully.
+     *
+     * @throws {Error} If every URL in the list fails to load.
+     *
+     * @example
+     * ```ts
+     * const url = await Media.chainLoad([
+     *   'https://esahubble.org/media/archives/images/original/heic0506a.tif',
+     *   'https://esahubble.org/media/archives/images/large/heic0506a.jpg',
+     *   'https://esahubble.org/media/archives/images/screen/heic0506a.jpg',
+     * ])
+     * ```
+     */
+    readonly chainLoad: (urls: string[]) => Promise<string>;
+    /**
+     * Progressive image loader that shows a blurred placeholder immediately,
+     * then upgrades through quality tiers as each resolves.
+     *
+     * Works on both `<img>` elements (sets `src`) and any other
+     * `HTMLElement` (sets `background-image`). A CSS blur filter is applied
+     * while the placeholder is shown, then removed with a smooth transition
+     * once the full-quality image is ready.
+     *
+     * @param target - The DOM element to receive the image. Can be an
+     *                 `HTMLImageElement` or any `HTMLElement` with a
+     *                 background-image style.
+     * @param opts   - Image source configuration. See
+     *                 {@link ProgressiveImageOptions}.
+     *
+     * @returns Resolves when the highest available quality tier has been
+     *          applied (or all tiers have been attempted).
+     *
+     * @example
+     * ```ts
+     * const hero = document.getElementById('hero-image')!
+     * await Media.progressive(hero, {
+     *   placeholder: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...',
+     *   src:   'https://cdn.example.com/andromeda-1280.jpg',
+     *   srcHD: 'https://cdn.example.com/andromeda-4k.jpg',
+     * })
+     * ```
+     */
+    readonly progressive: (target: HTMLImageElement | HTMLElement, opts: ProgressiveImageOptions) => Promise<void>;
+    /**
+     * Preload a list of images in the background using concurrent fetches.
+     *
+     * All URLs are loaded in parallel via `Promise.allSettled`. URLs that
+     * fail to load are silently dropped; only successfully loaded URLs are
+     * returned.
+     *
+     * @param urls - Array of image URLs to preload.
+     *
+     * @returns The subset of `urls` that loaded successfully, preserving
+     *          original order.
+     *
+     * @example
+     * ```ts
+     * const loaded = await Media.preload([
+     *   'https://cdn.example.com/m31-thumb.jpg',
+     *   'https://cdn.example.com/m42-thumb.jpg',
+     *   'https://cdn.example.com/m45-thumb.jpg',
+     * ])
+     * console.log(`${loaded.length} of 3 images cached`)
+     * ```
+     */
+    readonly preload: (urls: string[]) => Promise<string[]>;
+    /**
+     * Build a Wikimedia Commons URL for a given filename.
+     *
+     * Uses the `Special:FilePath` redirect, which resolves to the correct
+     * CDN path without requiring the internal MD5 hash. When a `width` is
+     * provided, the Wikimedia thumbnail API generates a resized version
+     * server-side.
+     *
+     * @param filename - The Wikimedia Commons filename, including extension
+     *                   (e.g. `'Orion_Nebula_-_Hubble_2006_mosaic_18000.jpg'`).
+     * @param width    - Optional pixel width for on-the-fly thumbnail
+     *                   generation. Omit to get the original-resolution file.
+     *
+     * @returns A fully-qualified Wikimedia Commons URL.
+     *
+     * @example
+     * ```ts
+     * // Original resolution
+     * Media.wikimediaUrl('Orion_Nebula_-_Hubble_2006_mosaic_18000.jpg')
+     * // => 'https://commons.wikimedia.org/wiki/Special:FilePath/Orion_Nebula...'
+     *
+     * // 800px thumbnail
+     * Media.wikimediaUrl('Crab_Nebula.jpg', 800)
+     * // => 'https://commons.wikimedia.org/wiki/Special:FilePath/Crab_Nebula.jpg?width=800'
+     * ```
+     */
+    readonly wikimediaUrl: (filename: string, width?: number) => string;
+    /**
+     * Build a Cloudinary URL with on-the-fly resizing and format optimisation.
+     *
+     * Constructs a Cloudinary delivery URL using the `image/upload` path
+     * with the specified transformations. Defaults to `crop: 'fill'`,
+     * `quality: 'auto'`, and `format: 'auto'` when not overridden.
+     *
+     * @param cloudName - Your Cloudinary cloud name (e.g. `'my-astro-cloud'`).
+     * @param publicId  - The image's public ID in your Cloudinary media
+     *                    library (e.g. `'nebulae/m42-mosaic'`).
+     * @param opts      - Transformation options. See {@link CloudinaryOptions}.
+     *
+     * @returns A fully-qualified Cloudinary delivery URL with transformations.
+     *
+     * @example
+     * ```ts
+     * const url = Media.cloudinaryUrl('my-astro-cloud', 'nebulae/m42-mosaic', {
+     *   w: 1280,
+     *   h: 720,
+     *   q: 80,
+     *   f: 'webp',
+     *   crop: 'fill',
+     * })
+     * // => 'https://res.cloudinary.com/my-astro-cloud/image/upload/c_fill,f_webp,q_80,w_1280,h_720/nebulae/m42-mosaic'
+     * ```
+     */
+    readonly cloudinaryUrl: (cloudName: string, publicId: string, opts?: CloudinaryOptions) => string;
+    /**
+     * Generate an HTML `srcset` attribute value for responsive images.
+     *
+     * Maps each width to a URL via the `transformer` callback and joins
+     * them into a comma-separated descriptor string suitable for use in
+     * an `<img srcset="...">` or `<source srcset="...">` attribute.
+     *
+     * @param widths      - Array of pixel widths to include (e.g.
+     *                      `[640, 1280, 1920]`).
+     * @param transformer - A function that receives a width in pixels and
+     *                      returns the corresponding image URL.
+     *
+     * @returns A `srcset`-formatted string (e.g.
+     *          `'https://cdn.example.com/img?w=640 640w, ...`).
+     *
+     * @example
+     * ```ts
+     * const set = Media.srcset([640, 1280, 1920], w =>
+     *   Media.cloudinaryUrl('my-cloud', 'galaxy/ngc1300', { w, f: 'webp' }),
+     * )
+     * // Use in an <img> tag:
+     * // <img srcset={set} sizes="100vw" />
+     * ```
+     */
+    readonly srcset: (widths: number[], transformer: (w: number) => string) => string;
+    /**
+     * Return the optimal image dimensions (in physical pixels) for a given
+     * container element, accounting for `window.devicePixelRatio`.
+     *
+     * Multiplies the element's CSS layout size by the device pixel ratio so
+     * that images are sharp on high-DPI (Retina) displays. Falls back to a
+     * ratio of `1` when `devicePixelRatio` is unavailable.
+     *
+     * @param element - The DOM element whose bounding box determines the
+     *                  target dimensions.
+     *
+     * @returns An object with `width` and `height` in physical (device)
+     *          pixels, rounded to the nearest integer.
+     *
+     * @example
+     * ```ts
+     * const container = document.getElementById('galaxy-viewer')!
+     * const { width, height } = Media.optimalSize(container)
+     * const url = Media.cloudinaryUrl('my-cloud', 'galaxy/ngc1300', {
+     *   w: width,
+     *   h: height,
+     * })
+     * ```
+     */
+    readonly optimalSize: (element: Element) => {
+        width: number;
+        height: number;
+    };
+    /**
+     * Load a single image by URL using the DOM `Image` constructor.
+     *
+     * @internal This is an implementation detail used by {@link Media.chainLoad},
+     * {@link Media.progressive}, and {@link Media.preload}. It is not part of
+     * the public API and may change without notice.
+     *
+     * @param url - The image URL to load.
+     * @returns Resolves with the URL on successful load; rejects on error.
+     */
+    readonly _loadImage: (url: string) => Promise<string>;
+};

package/dist/moon.d.ts

@@ -0,0 +1,170 @@
+import type { MoonPhase, MoonPosition, ObserverParams, RiseTransitSet } from './types.js';
+export declare const Moon: {
+    /**
+     * Geocentric equatorial and ecliptic position of the Moon.
+     *
+     * Computes the Moon's right ascension, declination, distance, ecliptic
+     * longitude/latitude, and horizontal parallax for the given date using
+     * Meeus' lunar theory with the ELP 2000-82 series truncated to the
+     * dominant terms.
+     *
+     * @remarks
+     * The algorithm computes five fundamental arguments (L', D, M, M', F) and
+     * evaluates trigonometric series from Meeus Tables 47.A (60 terms for
+     * longitude and distance) and 47.B (30 terms for latitude). Eccentricity
+     * corrections are applied to terms involving the Sun's mean anomaly M.
+     * Three additive corrections (A1, A2, A3) from Meeus p. 338 are included.
+     * Nutation is applied to the ecliptic longitude before converting to
+     * equatorial coordinates using the true obliquity.
+     *
+     * @param date - The date and time for which to compute the Moon's position. Defaults to the current date/time.
+     * @returns The Moon's geocentric position including RA (0-360°), declination, distance in km,
+     *   ecliptic longitude (0-360°), ecliptic latitude, and horizontal parallax in degrees.
+     *
+     * @example
+     * ```ts
+     * import { Moon } from '@motioncomplex/cosmos-lib'
+     *
+     * // Moon position at the 2024 vernal equinox
+     * const pos = Moon.position(new Date('2024-03-20T03:06:00Z'))
+     * console.log(`RA: ${pos.ra.toFixed(4)}°`)
+     * console.log(`Dec: ${pos.dec.toFixed(4)}°`)
+     * console.log(`Distance: ${pos.distance_km.toFixed(0)} km`)
+     * console.log(`Ecliptic Lon: ${pos.eclipticLon.toFixed(4)}°`)
+     * console.log(`Ecliptic Lat: ${pos.eclipticLat.toFixed(4)}°`)
+     * console.log(`Parallax: ${pos.parallax.toFixed(4)}°`)
+     * ```
+     */
+    readonly position: (date?: Date) => MoonPosition;
+    /**
+     * Moon phase information for a given date.
+     *
+     * Computes the lunar phase angle, illuminated fraction, age (days since
+     * new moon), and a human-readable phase name based on the difference
+     * in ecliptic longitude between the Moon and the Sun.
+     *
+     * @remarks
+     * The phase is determined from the elongation of the Moon from the Sun
+     * in ecliptic longitude. The illuminated fraction is derived using the
+     * cosine of the phase angle: `(1 - cos(phaseAngle)) / 2`. Phase names
+     * are divided into eight equal segments of 0.125 (45°) each, centered
+     * on the four principal phases.
+     *
+     * @param date - The date and time for which to compute the phase. Defaults to the current date/time.
+     * @returns An object containing the phase cycle position (0-1), illuminated fraction (0-1),
+     *   age in days (0-29.5), and the human-readable phase name.
+     *
+     * @example
+     * ```ts
+     * import { Moon } from '@motioncomplex/cosmos-lib'
+     *
+     * // Phase at vernal equinox 2024
+     * const p = Moon.phase(new Date('2024-03-20'))
+     * console.log(`Phase: ${p.name}`)                          // e.g. 'waxing-gibbous'
+     * console.log(`Illumination: ${(p.illumination * 100).toFixed(0)}%`)
+     * console.log(`Age: ${p.age.toFixed(1)} days`)
+     * console.log(`Cycle: ${(p.phase * 100).toFixed(1)}%`)     // 0% = new, 50% = full
+     * ```
+     */
+    readonly phase: (date?: Date) => MoonPhase;
+    /**
+     * Find the next occurrence of a specific phase after the given date.
+     *
+     * Uses an initial estimate based on the current phase position within the
+     * synodic month, then refines iteratively using bisection to achieve
+     * approximately 1-minute precision (up to 20 refinement iterations).
+     *
+     * @remarks
+     * The algorithm first estimates the time to the target phase from the current
+     * phase fraction, then iteratively corrects the estimate by measuring the
+     * phase error and adjusting by the proportional fraction of a synodic month.
+     * Wrap-around near the 0/1 boundary (new moon) is handled explicitly.
+     * Convergence threshold is 0.0001 phase units, corresponding to roughly
+     * 4 minutes of time.
+     *
+     * @param date - Start date from which to search forward. Defaults to the current date/time.
+     * @param targetPhase - The phase to find: `'new'`, `'first-quarter'`, `'full'`, or `'last-quarter'`. Defaults to `'full'`.
+     * @returns A `Date` representing the approximate moment of the next occurrence of the target phase.
+     *
+     * @example
+     * ```ts
+     * import { Moon } from '@motioncomplex/cosmos-lib'
+     *
+     * // Find the next full moon after the 2024 vernal equinox
+     * const fullMoon = Moon.nextPhase(new Date('2024-03-20'), 'full')
+     * console.log('Next full moon:', fullMoon.toISOString()) // 2024-03-25
+     *
+     * // Find the next new moon from today
+     * const newMoon = Moon.nextPhase(new Date('2024-03-20'), 'new')
+     * console.log('Next new moon:', newMoon.toISOString()) // 2024-04-08
+     * ```
+     */
+    readonly nextPhase: (date?: Date, targetPhase?: "new" | "first-quarter" | "full" | "last-quarter") => Date;
+    /**
+     * Rise, transit, and set times for the Moon.
+     *
+     * Computes the times at which the Moon rises above the horizon, transits
+     * the local meridian, and sets below the horizon for the given observer
+     * location and date.
+     *
+     * @remarks
+     * Uses the Moon's standard altitude of +0.125°, which accounts for the
+     * Moon's mean horizontal parallax (approximately 0.95°) minus atmospheric
+     * refraction (34 arc-minutes) minus the Moon's mean semi-diameter (about 16
+     * arc-minutes). Rise and set times will be `null` if the Moon is circumpolar
+     * (always above the horizon) or never rises at the given location and date.
+     *
+     * @param obs - Observer location and optional date. If `obs.date` is omitted, the current date/time is used.
+     * @returns An object with `rise`, `transit`, and `set` times. `rise` and `set` may be `null` at polar latitudes.
+     *
+     * @example
+     * ```ts
+     * import { Moon } from '@motioncomplex/cosmos-lib'
+     *
+     * // Moonrise and moonset in London
+     * const rts = Moon.riseTransitSet({ lat: 51.5, lng: -0.1, date: new Date('2024-03-20') })
+     * console.log('Moonrise:', rts.rise?.toISOString())
+     * console.log('Moon transit:', rts.transit.toISOString())
+     * console.log('Moonset:', rts.set?.toISOString())
+     * ```
+     */
+    readonly riseTransitSet: (obs: ObserverParams) => RiseTransitSet;
+    /**
+     * Optical libration angles (simplified).
+     *
+     * Returns the apparent tilt of the Moon's face as seen from Earth, caused
+     * by the geometry of the Moon's orbit relative to its rotational axis.
+     * Optical libration allows observers to see slightly more than 50% of
+     * the Moon's surface over time.
+     *
+     * @remarks
+     * This is a simplified calculation of the optical libration only (physical
+     * libration is not included). The mean inclination of the lunar equator to
+     * the ecliptic is taken as I = 1.5424°. The computation uses the Moon's
+     * argument of latitude (F), the longitude of the ascending node (Om), and
+     * the current ecliptic position. Based on Meeus, "Astronomical Algorithms",
+     * Chapter 53.
+     *
+     * Libration in longitude (`l`) reveals the eastern or western limb of the
+     * Moon, while libration in latitude (`b`) reveals the northern or southern
+     * limb. Both values are in degrees, with typical ranges of approximately
+     * +/-7.9° for longitude and +/-6.9° for latitude.
+     *
+     * @param date - The date and time for which to compute the libration. Defaults to the current date/time.
+     * @returns An object with `l` (libration in longitude, degrees) and `b` (libration in latitude, degrees).
+     *
+     * @example
+     * ```ts
+     * import { Moon } from '@motioncomplex/cosmos-lib'
+     *
+     * // Libration at the 2024 vernal equinox
+     * const lib = Moon.libration(new Date('2024-03-20'))
+     * console.log(`Libration in longitude: ${lib.l.toFixed(2)}°`)
+     * console.log(`Libration in latitude: ${lib.b.toFixed(2)}°`)
+     * ```
+     */
+    readonly libration: (date?: Date) => {
+        l: number;
+        b: number;
+    };
+};