@motioncomplex/cosmos-lib 1.0.9

package/dist/skymap-interactive.d.ts

@@ -0,0 +1,153 @@
+import type { CelestialObject, EquatorialCoord, InteractiveSkyMapOptions, ObserverParams, FOVOverlayOptions, SkyMapEventMap, SkyMapViewState } from './types.js';
+/**
+ * Interactive sky map that wraps a `<canvas>` element with pan, zoom,
+ * click-to-identify, hover detection, FOV overlays, a configurable HUD,
+ * and optional real-time sidereal tracking.
+ *
+ * Renders via the existing {@link renderSkyMap} for the base layer, then
+ * overlays interactive highlights and HUD elements on top.
+ *
+ * @example
+ * ```ts
+ * import { createInteractiveSkyMap, Data } from '@motioncomplex/cosmos-lib'
+ *
+ * const skymap = createInteractiveSkyMap(canvas, Data.all(), {
+ *   projection: 'stereographic',
+ *   center: { ra: 83.8, dec: -5.4 },
+ *   scale: 400,
+ *   panEnabled: true,
+ *   zoomEnabled: true,
+ *   fov: { radiusDeg: 5, label: 'Telescope' },
+ * })
+ *
+ * skymap.on('select', ({ object }) => console.log(object.name))
+ * skymap.on('viewchange', ({ center, scale }) => updateURL(center, scale))
+ *
+ * // Later:
+ * skymap.dispose()
+ * ```
+ */
+export declare class InteractiveSkyMap {
+    private _canvas;
+    private _ctx;
+    private _objects;
+    private _opts;
+    private _view;
+    private _projectedCache;
+    private _selectedObject;
+    private _hoveredObject;
+    private _listeners;
+    private _rafId;
+    private _dirty;
+    private _realTimeTimer;
+    private _pointers;
+    private _abortController;
+    private _disposed;
+    private _panAnimId;
+    constructor(canvas: HTMLCanvasElement, objects: CelestialObject[], opts?: InteractiveSkyMapOptions);
+    /**
+     * Subscribe to an interaction event.
+     *
+     * @param event   - Event name (`'select'`, `'hover'`, or `'viewchange'`).
+     * @param handler - Callback invoked when the event fires.
+     */
+    on<K extends keyof SkyMapEventMap>(event: K, handler: (data: SkyMapEventMap[K]) => void): void;
+    /**
+     * Unsubscribe from an interaction event.
+     */
+    off<K extends keyof SkyMapEventMap>(event: K, handler: (data: SkyMapEventMap[K]) => void): void;
+    private _emit;
+    /** Get the current view state. */
+    getView(): Readonly<SkyMapViewState>;
+    /**
+     * Programmatically set the view centre, scale, and/or projection.
+     * Triggers a re-render and emits `'viewchange'`.
+     */
+    setView(view: Partial<SkyMapViewState>): void;
+    /**
+     * Animate the view to a new centre and/or scale.
+     *
+     * @param center     - Target centre in equatorial coordinates.
+     * @param opts.scale - Target scale (optional, defaults to current).
+     * @param opts.durationMs - Animation duration in ms (default 800).
+     */
+    panTo(center: EquatorialCoord, opts?: {
+        scale?: number;
+        durationMs?: number;
+    }): void;
+    /** The currently selected object, or `null`. */
+    get selectedObject(): CelestialObject | null;
+    /** The currently hovered object, or `null`. */
+    get hoveredObject(): CelestialObject | null;
+    /**
+     * Programmatically select an object by its `id`. Pass `null` to clear.
+     */
+    select(objectId: string | null): void;
+    /**
+     * Return the celestial object at a given canvas pixel position, or `null`.
+     */
+    objectAt(canvasX: number, canvasY: number): CelestialObject | null;
+    /** Replace the objects array and re-render. */
+    setObjects(objects: CelestialObject[]): void;
+    /** Merge new options and re-render. */
+    setOptions(opts: Partial<InteractiveSkyMapOptions>): void;
+    /** Set or clear the FOV indicator overlay(s). */
+    setFOV(fov: FOVOverlayOptions | FOVOverlayOptions[] | null): void;
+    /**
+     * Start real-time sidereal tracking. The view centre follows the local
+     * sidereal time so the sky drifts naturally.
+     *
+     * @param observer - Observer parameters. If omitted, uses the value from
+     *                   {@link InteractiveSkyMapOptions.observer}.
+     * @throws If no observer parameters are available.
+     */
+    startRealTime(observer?: ObserverParams): void;
+    /** Stop real-time sidereal tracking. */
+    stopRealTime(): void;
+    /**
+     * Force an immediate re-render. Normally renders happen automatically
+     * via the dirty-flag mechanism; call this only if you need a synchronous
+     * update.
+     */
+    render(): void;
+    /**
+     * Remove all event listeners, cancel animations, and release resources.
+     * The instance should not be used after calling `dispose()`.
+     */
+    dispose(): void;
+    /** Convert a pointer event to canvas-space coordinates (DPI-aware). */
+    private _canvasCoords;
+    private _onPointerDown;
+    private _onPointerMove;
+    private _onPointerUp;
+    private _onWheel;
+    private _markDirty;
+    private _clampScale;
+    private _emitViewChange;
+    /**
+     * Unified forward-project helper (same logic as renderSkyMap's internal
+     * `project` function) returning absolute canvas coordinates.
+     */
+    private _project;
+    /** Rebuild the projected-object cache used for hit-testing and highlights. */
+    private _rebuildProjectedCache;
+    /** Draw a highlight ring around a specific object. */
+    private _drawHighlight;
+    /** Draw FOV indicator overlay(s). */
+    private _drawFOV;
+    /** Draw HUD elements (cardinal labels, horizon line, zenith marker). */
+    private _drawHUD;
+    private _realTimeLoop;
+}
+/**
+ * Create an {@link InteractiveSkyMap} on the given canvas.
+ *
+ * This is a convenience wrapper around the class constructor for consumers
+ * who prefer a functional style.
+ *
+ * @param canvas  - Target `<canvas>` element.
+ * @param objects - Celestial objects to render (e.g. `Data.all()`).
+ * @param opts    - Interactive sky map options.
+ * @returns A new {@link InteractiveSkyMap} instance.
+ */
+export declare function createInteractiveSkyMap(canvas: HTMLCanvasElement, objects: CelestialObject[], opts?: InteractiveSkyMapOptions): InteractiveSkyMap;

package/dist/skymap.d.ts

@@ -0,0 +1,172 @@
+import type { EquatorialCoord, ProjectedPoint, SkyMapRenderOptions } from './types.js';
+import type { CelestialObject } from './types.js';
+/**
+ * Stereographic projection centred on `center`.
+ *
+ * Good for detailed star charts around a specific point. Preserves angles
+ * (conformal) but distorts areas away from the centre. Returns offsets in
+ * pixels relative to the canvas centre.
+ *
+ * @param coord  - Equatorial coordinates (RA/Dec in degrees) of the point to project.
+ * @param center - Equatorial coordinates of the projection centre.
+ * @param scale  - Pixel scale factor applied to the projection. Higher values zoom in.
+ *                 Defaults to `500`.
+ * @returns A {@link ProjectedPoint} with `x`/`y` offsets from canvas centre and a
+ *          `visible` flag (`false` when the point is on the far side of the sphere).
+ *
+ * @example
+ * ```ts
+ * import { stereographic } from '@motioncomplex/cosmos-lib'
+ *
+ * // Project Betelgeuse relative to the centre of Orion
+ * const orionCenter = { ra: 83.8, dec: 1.2 }
+ * const betelgeuse  = { ra: 88.79, dec: 7.41 }
+ * const pt = stereographic(betelgeuse, orionCenter, 600)
+ * // pt.x / pt.y are pixel offsets; pt.visible === true
+ * ```
+ */
+export declare function stereographic(coord: EquatorialCoord, center: EquatorialCoord, scale?: number): ProjectedPoint;
+/**
+ * Mollweide (equal-area) projection.
+ *
+ * Suited to full-sky maps where preserving relative area is important.
+ * Unlike the stereographic and gnomonic projections, this returns
+ * **absolute** pixel coordinates rather than offsets from centre.
+ * Internally solves the auxiliary angle with Newton-Raphson iteration.
+ *
+ * @param coord  - Equatorial coordinates (RA/Dec in degrees) of the point to project.
+ * @param canvas - Dimensions of the target canvas (`{ width, height }` in pixels).
+ * @returns A {@link ProjectedPoint} with absolute `x`/`y` pixel coordinates.
+ *          The `visible` flag is always `true` for Mollweide (full-sky coverage).
+ *
+ * @example
+ * ```ts
+ * import { mollweide } from '@motioncomplex/cosmos-lib'
+ *
+ * // Project Polaris onto an 800x400 all-sky canvas
+ * const polaris = { ra: 37.95, dec: 89.26 }
+ * const pt = mollweide(polaris, { width: 800, height: 400 })
+ * ctx.fillRect(pt.x - 2, pt.y - 2, 4, 4)
+ * ```
+ */
+export declare function mollweide(coord: EquatorialCoord, canvas: {
+    width: number;
+    height: number;
+}): ProjectedPoint;
+/**
+ * Gnomonic (tangent-plane) projection.
+ *
+ * Minimal distortion near the centre; commonly used for telescope
+ * field-of-view charts and narrow-field imaging. Great circles are
+ * projected as straight lines, but the usable area is limited to
+ * roughly a hemisphere. Returns offsets in pixels relative to the
+ * canvas centre.
+ *
+ * @param coord  - Equatorial coordinates (RA/Dec in degrees) of the point to project.
+ * @param center - Equatorial coordinates of the tangent point (projection centre).
+ * @param scale  - Pixel scale factor applied to the projection. Defaults to `400`.
+ * @returns A {@link ProjectedPoint} with `x`/`y` offsets from canvas centre.
+ *          `visible` is `false` when the point falls behind the tangent plane.
+ *
+ * @example
+ * ```ts
+ * import { gnomonic } from '@motioncomplex/cosmos-lib'
+ *
+ * // Project the Orion Nebula (M42) relative to Orion's belt centre
+ * const beltCenter = { ra: 84.05, dec: -1.2 }
+ * const m42        = { ra: 83.82, dec: -5.39 }
+ * const pt = gnomonic(m42, beltCenter, 500)
+ * if (pt.visible) {
+ *   ctx.arc(cx + pt.x, cy - pt.y, 4, 0, Math.PI * 2)
+ * }
+ * ```
+ */
+export declare function gnomonic(coord: EquatorialCoord, center: EquatorialCoord, scale?: number): ProjectedPoint;
+/**
+ * Map a {@link CelestialObject} to a CSS colour string based on its spectral
+ * class (for stars) or object type (nebula, galaxy, cluster, black hole).
+ *
+ * @internal Not part of the public API -- used by {@link renderSkyMap}.
+ * @param obj - The celestial object to colour.
+ * @returns A CSS hex colour string (e.g. `'#9bb0ff'` for an O-type star).
+ */
+export declare function spectralColor(obj: CelestialObject): string;
+/**
+ * Render an interactive sky chart onto a `<canvas>` element.
+ *
+ * Draws a coordinate grid (RA/Dec), constellation stick-figure lines and
+ * labels, and all supplied celestial objects -- each rendered with a shape
+ * and colour appropriate to its type (star glow, galaxy ellipse, nebula
+ * square, cluster circle). Stars brighter than magnitude 3.5 are labelled
+ * automatically when `showLabels` is enabled.
+ *
+ * Supports three projection modes via {@link SkyMapRenderOptions.projection}:
+ * `'stereographic'` (default), `'mollweide'`, and `'gnomonic'`.
+ *
+ * @param canvas  - The target `HTMLCanvasElement` to draw on. Must support a
+ *                  2D rendering context.
+ * @param objects - Array of {@link CelestialObject} entries to plot (e.g. from
+ *                  `Data.all()` or `Data.search()`). Objects with `null` RA/Dec
+ *                  or magnitudes above `showMagnitudeLimit` are skipped.
+ * @param opts    - Render options controlling projection, grid, labels,
+ *                  magnitude limit, colours, and constellation overlays.
+ *                  See {@link SkyMapRenderOptions} for defaults.
+ * @throws If the canvas does not support a 2D context.
+ *
+ * @example
+ * ```ts
+ * import { renderSkyMap } from '@motioncomplex/cosmos-lib'
+ * import { Data } from '@motioncomplex/cosmos-lib'
+ *
+ * const canvas = document.querySelector<HTMLCanvasElement>('#sky')!
+ * canvas.width = 1200
+ * canvas.height = 800
+ *
+ * // Render the Orion region with a stereographic projection
+ * renderSkyMap(canvas, Data.all(), {
+ *   projection: 'stereographic',
+ *   center: { ra: 83.8, dec: 1.2 },   // centre of Orion
+ *   scale: 400,
+ *   showGrid: true,
+ *   showLabels: true,
+ *   showMagnitudeLimit: 6,
+ *   background: '#0a0a18',
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Full-sky Mollweide map
+ * renderSkyMap(canvas, Data.all(), {
+ *   projection: 'mollweide',
+ *   showGrid: true,
+ *   showLabels: true,
+ *   showMagnitudeLimit: 5,
+ * })
+ * ```
+ */
+export declare function renderSkyMap(canvas: HTMLCanvasElement, objects: CelestialObject[], opts?: SkyMapRenderOptions): void;
+/**
+ * Legacy namespace re-exporting all sky-map functions.
+ *
+ * @deprecated Use the named exports `stereographic`, `mollweide`, `gnomonic`,
+ * and `renderSkyMap` directly instead. This object is retained solely for
+ * backwards compatibility and will be removed in a future major release.
+ *
+ * @example
+ * ```ts
+ * // Before (deprecated)
+ * import { SkyMap } from '@motioncomplex/cosmos-lib'
+ * SkyMap.render(canvas, objects)
+ *
+ * // After (preferred)
+ * import { renderSkyMap } from '@motioncomplex/cosmos-lib'
+ * renderSkyMap(canvas, objects)
+ * ```
+ */
+export declare const SkyMap: {
+    stereographic: typeof stereographic;
+    mollweide: typeof mollweide;
+    gnomonic: typeof gnomonic;
+    render: typeof renderSkyMap;
+};

package/dist/sun.d.ts

@@ -0,0 +1,119 @@
+import type { ObserverParams, SunPosition, TwilightTimes } from './types.js';
+export declare const Sun: {
+    /**
+     * Geocentric equatorial position of the Sun.
+     *
+     * Computes the Sun's right ascension, declination, distance, and ecliptic longitude
+     * for the given date. The position includes nutation corrections and uses the true
+     * obliquity of the ecliptic for the equatorial conversion.
+     *
+     * @remarks
+     * Accuracy is approximately 0.01° for dates within a few centuries of J2000.0 (2000-01-01 12:00 TT).
+     * The algorithm derives geocentric solar coordinates by inverting the heliocentric Earth
+     * position from VSOP87 theory.
+     *
+     * @param date - The date and time for which to compute the Sun's position. Defaults to the current date/time.
+     * @returns The Sun's geocentric equatorial position including RA (0-360°), declination, distance in AU, and ecliptic longitude.
+     *
+     * @example
+     * ```ts
+     * import { Sun } from '@motioncomplex/cosmos-lib'
+     *
+     * // Sun position at the 2024 vernal equinox
+     * const pos = Sun.position(new Date('2024-03-20T03:06:00Z'))
+     * console.log(`RA: ${pos.ra.toFixed(4)}°`)        // ~0° (vernal equinox point)
+     * console.log(`Dec: ${pos.dec.toFixed(4)}°`)       // ~0° at equinox
+     * console.log(`Distance: ${pos.distance_AU} AU`)   // ~0.996 AU
+     * console.log(`Ecliptic Lon: ${pos.eclipticLon.toFixed(4)}°`) // ~0° at equinox
+     * ```
+     */
+    readonly position: (date?: Date) => SunPosition;
+    /**
+     * Solar noon (transit) for a given observer.
+     *
+     * Computes the time at which the Sun crosses the observer's local meridian,
+     * reaching its highest altitude for the day.
+     *
+     * @remarks
+     * Uses the standard solar altitude of -0.8333° which accounts for atmospheric
+     * refraction (34 arc-minutes) and the Sun's mean semi-diameter (16 arc-minutes).
+     *
+     * @param obs - Observer location and optional date. If `obs.date` is omitted, the current date/time is used.
+     * @returns A `Date` representing the moment of solar noon (local meridian transit).
+     *
+     * @example
+     * ```ts
+     * import { Sun } from '@motioncomplex/cosmos-lib'
+     *
+     * // Solar noon in London on the vernal equinox
+     * const noon = Sun.solarNoon({ lat: 51.5, lng: -0.1, date: new Date('2024-03-20') })
+     * console.log('Solar noon:', noon.toISOString()) // ~12:10 UTC
+     * ```
+     */
+    readonly solarNoon: (obs: ObserverParams) => Date;
+    /**
+     * Equation of time in minutes.
+     *
+     * Computes the difference between apparent solar time and mean solar time.
+     * A positive value means the true Sun is ahead of the mean Sun (sundial reads
+     * later than clock time), and a negative value means it trails behind.
+     *
+     * @remarks
+     * The equation of time arises from the eccentricity of Earth's orbit and
+     * the obliquity of the ecliptic. It varies between approximately -14 and +16 minutes
+     * over the course of a year. The computation uses the Sun's mean longitude (L0)
+     * and apparent right ascension, converting the angular difference to minutes of time
+     * at 4 minutes per degree.
+     *
+     * @param date - The date and time for the calculation. Defaults to the current date/time.
+     * @returns The equation of time in minutes. Positive means the apparent Sun is ahead of mean time.
+     *
+     * @example
+     * ```ts
+     * import { Sun } from '@motioncomplex/cosmos-lib'
+     *
+     * // EoT at the vernal equinox 2024 (should be near -7 minutes)
+     * const eot = Sun.equationOfTime(new Date('2024-03-20'))
+     * console.log(`Equation of Time: ${eot.toFixed(2)} minutes`)
+     *
+     * // EoT varies through the year; check the November maximum
+     * const eotNov = Sun.equationOfTime(new Date('2024-11-03'))
+     * console.log(`EoT in November: ${eotNov.toFixed(2)} minutes`) // ~+16 min
+     * ```
+     */
+    readonly equationOfTime: (date?: Date) => number;
+    /**
+     * Complete twilight times for an observer.
+     *
+     * Returns sunrise/sunset plus civil, nautical, and astronomical twilight
+     * boundaries for the given observer location and date. Each twilight boundary
+     * corresponds to the Sun's centre reaching a specific altitude below the horizon.
+     *
+     * @remarks
+     * Standard solar altitudes used for each twilight type:
+     * - **Sunrise/Sunset**: -0.8333° (accounts for refraction and solar semi-diameter)
+     * - **Civil twilight**: -6° (sufficient light for outdoor activities without artificial lighting)
+     * - **Nautical twilight**: -12° (horizon still discernible at sea)
+     * - **Astronomical twilight**: -18° (sky fully dark for astronomical observations)
+     *
+     * At polar latitudes, some or all twilight phases may not occur on a given date.
+     * In such cases the corresponding fields will be `null`.
+     *
+     * @param obs - Observer location and optional date. If `obs.date` is omitted, the current date/time is used.
+     * @returns An object containing all nine twilight timestamps, from astronomical dawn through astronomical dusk.
+     *
+     * @example
+     * ```ts
+     * import { Sun } from '@motioncomplex/cosmos-lib'
+     *
+     * // Twilight times in London on the 2024 vernal equinox
+     * const tw = Sun.twilight({ lat: 51.5, lng: -0.1, date: new Date('2024-03-20') })
+     * console.log('Astronomical dawn:', tw.astronomicalDawn?.toISOString())
+     * console.log('Sunrise:', tw.sunrise?.toISOString())
+     * console.log('Solar noon:', tw.solarNoon.toISOString())
+     * console.log('Sunset:', tw.sunset?.toISOString())
+     * console.log('Astronomical dusk:', tw.astronomicalDusk?.toISOString())
+     * ```
+     */
+    readonly twilight: (obs: ObserverParams) => TwilightTimes;
+};

package/dist/three/factories.d.ts

@@ -0,0 +1,160 @@
+import type * as THREE from 'three';
+import type { PlanetOptions, PlanetResult, NebulaOptions, NebulaResult, StarFieldOptions, OrbitOptions } from './types.js';
+/**
+ * Create a planet or star mesh with optional textures, bump maps,
+ * atmospheric glow, and ring systems.
+ *
+ * The returned group contains the sphere mesh and any extras (atmosphere shell,
+ * ring geometry). Call `dispose()` on the result when removing the planet from
+ * the scene to free all GPU resources.
+ *
+ * @param opts  - Planet configuration (radius, textures, atmosphere, rings, etc.).
+ * @param THREE - The Three.js module, passed at runtime to avoid a hard dependency
+ *                on `three` in the library bundle.
+ * @returns A {@link PlanetResult} containing the `group`, the surface `mesh`, and
+ *          a `dispose` function.
+ *
+ * @example
+ * ```ts
+ * import * as THREE from 'three'
+ * import { createPlanet } from '@motioncomplex/cosmos-lib/three'
+ *
+ * const { group, mesh, dispose } = createPlanet({
+ *   radius: 6.5,
+ *   textureUrl: '/textures/earth-bluemarble-4k.jpg',
+ *   bumpUrl: '/textures/earth-bump.jpg',
+ *   atmosphere: { color: 0x4488ff, intensity: 1.3 },
+ *   rings: { inner: 1.2, outer: 2.0, color: 0xaaaaaa, opacity: 0.6 },
+ * }, THREE)
+ *
+ * scene.add(group)
+ * // later, when removing:
+ * scene.remove(group)
+ * dispose()
+ * ```
+ */
+export declare function createPlanet(opts: PlanetOptions, THREE: typeof import('three')): PlanetResult;
+/**
+ * Create a nebula or galaxy sprite using additive blending.
+ *
+ * Attempts each URL in `textureUrls` in order via {@link Media.chainLoad},
+ * applying the first texture that loads successfully. An invisible hit-mesh
+ * is added alongside the sprite so the nebula can be raycasted for click
+ * detection despite being a billboard.
+ *
+ * @param opts  - Nebula configuration (radius, texture URLs, opacity, aspect ratio).
+ * @param THREE - The Three.js module, passed at runtime to avoid a hard dependency
+ *                on `three` in the library bundle.
+ * @returns A {@link NebulaResult} containing the `group`, the `sprite`, an invisible
+ *          `hitMesh` for raycasting, and a `dispose` function.
+ *
+ * @example
+ * ```ts
+ * import * as THREE from 'three'
+ * import { createNebula } from '@motioncomplex/cosmos-lib/three'
+ *
+ * const { group, hitMesh, dispose } = createNebula({
+ *   radius: 3000,
+ *   textureUrls: [
+ *     'https://cdn.example.com/orion-hubble.jpg',
+ *     '/fallback/orion-low.jpg',
+ *   ],
+ *   opacity: 0.9,
+ * }, THREE)
+ *
+ * scene.add(group)
+ *
+ * // Use hitMesh for raycasting
+ * raycaster.intersectObject(hitMesh)
+ * ```
+ */
+export declare function createNebula(opts: NebulaOptions, THREE: typeof import('three')): NebulaResult;
+/**
+ * Create an atmospheric glow rim around a sphere.
+ *
+ * Renders a slightly larger back-face sphere with a custom Fresnel-based shader
+ * and additive blending, producing a soft halo effect. Typically called
+ * internally by {@link createPlanet} when `atmosphere` is specified, but can
+ * also be used standalone.
+ *
+ * The mesh stores its disposable resources in `mesh.userData._toDispose`.
+ *
+ * @param radius   - Radius of the parent sphere. The atmosphere shell is
+ *                   generated at `radius * 1.06`.
+ * @param colorHex - Glow colour as a hex number (e.g. `0x4488ff`).
+ * @param THREE    - The Three.js module, passed at runtime to avoid a hard
+ *                   dependency on `three` in the library bundle.
+ * @param intensity - Glow intensity multiplier.
+ * @returns A `THREE.Mesh` with the atmospheric glow shader applied.
+ *
+ * @example
+ * ```ts
+ * import * as THREE from 'three'
+ * import { createAtmosphere } from '@motioncomplex/cosmos-lib/three'
+ *
+ * const atm = createAtmosphere(6.5, 0x4488ff, THREE, 1.4)
+ * scene.add(atm)
+ * ```
+ */
+export declare function createAtmosphere(radius: number, colorHex: number, THREE: typeof import('three'), intensity?: number): THREE.Mesh;
+/**
+ * Create a randomised star-field point cloud.
+ *
+ * Generates `count` points distributed uniformly on a spherical shell between
+ * `minRadius` and `maxRadius`. Each star is given a randomised colour
+ * (warm white, cool blue, or neutral) and brightness for a natural look.
+ *
+ * Call `points.userData.dispose()` when removing the star field to free the
+ * underlying buffer geometry and material.
+ *
+ * @param opts  - Star-field configuration (count, radius range, point size, opacity).
+ *                All properties are optional and have sensible defaults.
+ * @param THREE - The Three.js module, passed at runtime to avoid a hard dependency
+ *                on `three` in the library bundle.
+ * @returns A `THREE.Points` object ready to be added to the scene.
+ *
+ * @example
+ * ```ts
+ * import * as THREE from 'three'
+ * import { createStarField } from '@motioncomplex/cosmos-lib/three'
+ *
+ * const stars = createStarField({
+ *   count: 50_000,
+ *   minRadius: 30_000,
+ *   maxRadius: 150_000,
+ * }, THREE)
+ *
+ * scene.add(stars)
+ * // later:
+ * scene.remove(stars)
+ * stars.userData.dispose()
+ * ```
+ */
+export declare function createStarField(opts: StarFieldOptions | undefined, THREE: typeof import('three')): THREE.Points;
+/**
+ * Create a circular orbit line lying on the XZ plane.
+ *
+ * Generates a closed circle of `segments` line segments at the given
+ * `distance` from the origin. Useful for visualising planetary orbits
+ * or other radial guides.
+ *
+ * Call `line.userData.dispose()` when removing the orbit to free the
+ * underlying buffer geometry and material.
+ *
+ * @param distance - Orbit radius in scene units.
+ * @param opts     - Visual options (colour, opacity, segment count).
+ * @param THREE    - The Three.js module, passed at runtime to avoid a hard
+ *                   dependency on `three` in the library bundle.
+ * @returns A `THREE.Line` representing the circular orbit.
+ *
+ * @example
+ * ```ts
+ * import * as THREE from 'three'
+ * import { createOrbit } from '@motioncomplex/cosmos-lib/three'
+ *
+ * // Draw Earth's orbit at 150 scene units
+ * const orbit = createOrbit(150, { color: 0x4488ff, opacity: 0.3 }, THREE)
+ * scene.add(orbit)
+ * ```
+ */
+export declare function createOrbit(distance: number, opts: OrbitOptions | undefined, THREE: typeof import('three')): THREE.Line;