@interstellar-tools/types 0.60.0 → 0.61.0

package/README.md

@@ -1,5 +1,19 @@
 # @interstellar-tools/types
 
+Shared TypeScript types (3D tuples, branded radians, unit-carrying values,
+celestial body interfaces) used across the monorepo to keep APIs predictable and
+safe.
+
+## Documentation
+
+The full documentation lives at
+**[phun-ky.net/interstellar-tools](https://phun-ky.net/interstellar-tools/)**:
+
+- [Getting started](https://phun-ky.net/interstellar-tools/guide/introduction/):
+  installation, unit conventions and recommended practices
+- [API reference for `@interstellar-tools/types`](https://phun-ky.net/interstellar-tools/api/@interstellar-tools/types/):
+  every export, with formulas, parameters and examples
+
 ## Installation
 
 - [Node.js](https://nodejs.org/) version 22.9.0 or higher

package/dist/celestial-bodies/asteroid-belts.d.ts

@@ -11,8 +11,12 @@ import { CartesianCoordinatesInterface } from './planets.js';
  * @group Celestial Bodies
  */
 export interface AsteroidBeltInterface {
+    /** Stable identifier. Never translated. */
+    id: string;
     /** Name of the asteroid belt. */
     name: string;
+    /** Id of the star the belt orbits (e.g., `'sun'`). */
+    parent: string;
     /** Inner radius of the belt in Astronomical Units (AU). */
     innerRadius: number;
     /** Outer radius of the belt in Astronomical Units (AU). */
@@ -32,8 +36,10 @@ export interface AsteroidBeltInterface {
  * @typedef {AsteroidBeltInterface[]} AsteroidBeltsType
  * @example
  * ```ts
- * const asteroidBelt: AsteroidBeltInterface = [{
+ * const asteroidBelts: AsteroidBeltsType = [{
+ *   id: 'main-asteroid-belt',
  *   name: 'Main Belt',
+ *   parent: 'sun',
  *   innerRadius: 2.1,
  *   outerRadius: 3.3,
  *   color: '#888888',

package/dist/celestial-bodies/asteroid-belts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"asteroid-belts.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/asteroid-belts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACpC,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,6BAA6B,EAAE,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,iBAAiB,GAAG,qBAAqB,EAAE,CAAC"}
+{"version":3,"file":"asteroid-belts.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/asteroid-belts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,6BAA6B,EAAE,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,iBAAiB,GAAG,qBAAqB,EAAE,CAAC"}

package/dist/celestial-bodies/asteroids.d.ts

@@ -1,6 +1,5 @@
-import { DistanceInterface, MeasureInterface } from '../distance.js';
-import type { Radians } from '../numeric.js';
-import { TemporalInterface } from '../temporal.js';
+import { DistanceInterface } from '../distance.js';
+import type { OrbitInterface } from '../orbits.js';
 import { CartesianCoordinatesInterface } from './planets.js';
 /**
  * High-level **orbital class** of an asteroid (by dynamical region).
@@ -58,9 +57,9 @@ export type AsteroidSpectralType = 'c-type' | 's-type' | 'v-type' | 'm-type' | '
  *
  * ::: info
  *
- * **Orbital elements (angles & distances):**
+ * **Orbital elements (angles & distances)**, all in `orbit`:
  *
- * - Semi-major axis `a` should be in **astronomical units (au)** via {@link MeasureInterface}.
+ * - Semi-major axis `a` should be in **astronomical units (au)**.
  * - Eccentricity `e` for bound ellipses typically satisfies \(0 \le e < 1\).
  * - Inclination `i`, argument of perihelion `w` (ω), and longitude of ascending node `om` (Ω)
  *   are given in **degrees**.
@@ -71,7 +70,7 @@ export type AsteroidSpectralType = 'c-type' | 's-type' | 'v-type' | 'm-type' | '
  * q \;=\; a\,(1 - e)
  * $$
  *
- * **Period convention:** `period` is a duration (e.g., in **days**) using {@link TemporalInterface}.
+ * **Period convention:** `period` is a duration (e.g., in **days**).
  * If you encode direction, a **negative value** indicates **counter-clockwise** in your display
  * convention (visualization-specific; not a physical requirement).
  *
@@ -83,6 +82,8 @@ export type AsteroidSpectralType = 'c-type' | 's-type' | 'v-type' | 'm-type' | '
  * @group Celestial Bodies
  */
 export interface AsteroidInterface {
+    /** Stable identifier, used by `parent` references. Never translated. */
+    id: string;
     /** Name of the asteroid (e.g., `"Ceres"`, `"Vesta"`). */
     name: string;
     /** General dynamical region (e.g., main-belt, NEO, Trojan). */
@@ -91,49 +92,10 @@ export interface AsteroidInterface {
     category: AsteroidCategory;
     /** Spectral/taxonomic class (composition & albedo proxy). */
     spectralType: AsteroidSpectralType;
-    /** Star system identifier (e.g., `"Solar System"`). */
-    system: string;
-    /**
-     * **Semi-major axis** (typically in **au**).
-     *
-     * @example
-     * ```ts
-     * a: { value: 2.77, unit: 'au' }
-     * ```
-     */
-    a: MeasureInterface;
-    /**
-     * **Eccentricity** of the orbit.
-     * ::: info
-     *
-     * Elliptical orbits: \(0 \le e < 1\). Parabolic: \(e=1\). Hyperbolic: \(e>1\).
-     *
-     * :::
-     */
-    e: number;
-    /** **Inclination** \(i\) in **degrees**. */
-    i: number;
-    /** **Argument of perihelion** \( \omega \) in **degrees**. */
-    w: number;
-    /** **Longitude of ascending node** \( \Omega \) in **degrees**. */
-    om: number;
-    /** **True anomaly** \( \nu \) (current orbital position) in **radians**. */
-    angle: Radians;
-    /**
-     * **Orbital period** as a duration (e.g., in **days**).
-     * ::: info
-     *
-     * A **negative** value may be used to flag **counter-clockwise** drawing direction in UIs.
-     *
-     * :::
-     */
-    period: TemporalInterface;
-    /**
-     * **Perihelion distance** \( q = a(1-e) \) (typically in **au**).
-     * @see a
-     * @see e
-     */
-    q: number;
+    /** Id of the star the asteroid orbits (e.g., `'sun'`). */
+    parent: string;
+    /** Orbit around the parent, with all elements including `i`, `w`, `om` and `q`. */
+    orbit: Required<OrbitInterface>;
     /**
      * Optional **Cartesian coordinates** (distance values) in a specified frame.
      * ::: info

package/dist/celestial-bodies/asteroids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"asteroids.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/asteroids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAE7D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,GACpB,oBAAoB,GACpB,qBAAqB,GACrB,iBAAiB,GACjB,SAAS,GACT,wBAAwB,CAAC;AAE7B;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,gBAAgB,GAChB,YAAY,GACZ,cAAc,GACd,YAAY,GACZ,aAAa,GACb,cAAc,GACd,aAAa,GACb,gBAAgB,GAChB,SAAS,GACT,UAAU,GACV,uBAAuB,CAAC;AAE5B;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,oBAAoB,GAC5B,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,OAAO,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IAEb,+DAA+D;IAC/D,IAAI,EAAE,YAAY,CAAC;IAEnB,0EAA0E;IAC1E,QAAQ,EAAE,gBAAgB,CAAC;IAE3B,6DAA6D;IAC7D,YAAY,EAAE,oBAAoB,CAAC;IAEnC,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;;OAOG;IACH,CAAC,EAAE,gBAAgB,CAAC;IAEpB;;;;;;;OAOG;IACH,CAAC,EAAE,MAAM,CAAC;IAEV,4CAA4C;IAC5C,CAAC,EAAE,MAAM,CAAC;IAEV,8DAA8D;IAC9D,CAAC,EAAE,MAAM,CAAC;IAEV,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IAEX,4EAA4E;IAC5E,KAAK,EAAE,OAAO,CAAC;IAEf;;;;;;;OAOG;IACH,MAAM,EAAE,iBAAiB,CAAC;IAE1B;;;;OAIG;IACH,CAAC,EAAE,MAAM,CAAC;IAEV;;;;;;;OAOG;IACH,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,qBAAqB;IACrB,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,qBAAqB;IACrB,CAAC,CAAC,EAAE,iBAAiB,CAAC;IAEtB;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,4EAA4E;IAC5E,MAAM,EAAE,iBAAiB,CAAC;IAE1B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,6BAA6B,EAAE,CAAC;IAE5C,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IAEd,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"asteroids.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/asteroids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAE7D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,GACpB,oBAAoB,GACpB,qBAAqB,GACrB,iBAAiB,GACjB,SAAS,GACT,wBAAwB,CAAC;AAE7B;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,gBAAgB,GAChB,YAAY,GACZ,cAAc,GACd,YAAY,GACZ,aAAa,GACb,cAAc,GACd,aAAa,GACb,gBAAgB,GAChB,SAAS,GACT,UAAU,GACV,uBAAuB,CAAC;AAE5B;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,oBAAoB,GAC5B,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,OAAO,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IAEX,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IAEb,+DAA+D;IAC/D,IAAI,EAAE,YAAY,CAAC;IAEnB,0EAA0E;IAC1E,QAAQ,EAAE,gBAAgB,CAAC;IAE3B,6DAA6D;IAC7D,YAAY,EAAE,oBAAoB,CAAC;IAEnC,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IAEf,mFAAmF;IACnF,KAAK,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAEhC;;;;;;;OAOG;IACH,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,qBAAqB;IACrB,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,qBAAqB;IACrB,CAAC,CAAC,EAAE,iBAAiB,CAAC;IAEtB;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,4EAA4E;IAC5E,MAAM,EAAE,iBAAiB,CAAC;IAE1B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,6BAA6B,EAAE,CAAC;IAE5C,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IAEd,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,iBAAiB,EAAE,CAAC"}

package/dist/celestial-bodies/comets.d.ts

@@ -1,17 +1,17 @@
-import { DistanceInterface, MeasureInterface } from '../distance.js';
-import type { Radians } from '../numeric.js';
-import { TemporalInterface } from '../temporal.js';
+import { DistanceInterface } from '../distance.js';
+import type { OrbitInterface } from '../orbits.js';
 import { CartesianCoordinatesInterface } from './planets.js';
 /**
  * Represents a **comet** in the solar system simulation.
  *
- * **Cometary Orbital Parameters:**
+ * **Cometary Orbital Parameters**, all in `orbit`:
  * - **Semi-major axis (`a`)**: Defines the **size** of the comet’s orbit in **Astronomical Units (AU)**.
  * - **Orbital eccentricity (`e`)**: Determines how **elliptical** the orbit is ($0 = $ circular, closer to $1$ = highly elliptical).
  * - **Inclination (`i`)**: The tilt of the orbit relative to the **ecliptic plane**, measured in **degrees**.
  * - **Argument of perihelion (`w`)**: The angle from the **ascending node** to the **perihelion**.
  * - **Longitude of the ascending node (`om`)**: Defines where the orbit crosses the ecliptic.
  * - **Perihelion distance (`q`)**: The closest approach to the Sun in **AU**.
+ * - **Angle (`angle`)**: For comets this is the **mean anomaly** at J2000, as in the source data.
  *
  * **Visualization Parameters:**
  * - **Orbit Path (`orbitPath`)**: Precomputed trajectory for rendering.
@@ -21,30 +21,18 @@ import { CartesianCoordinatesInterface } from './planets.js';
  * @group Celestial Bodies
  */
 export interface CometInterface {
+    /** Stable identifier, used by `parent` references. Never translated. */
+    id: string;
     /** Name of the comet (e.g., "Halley", "Hale-Bopp"). */
     name: string;
     /** Type of comet based on its orbital characteristics. */
     type: 'periodic comet' | 'oort cloud comet' | 'short-period comet';
     /** Category classification of the comet. */
     category: 'halley-type comet' | 'long-period comet' | 'jupiter-family comet';
-    /** The star system where the comet is located. */
-    system: string;
-    /** Semi-major axis of the orbit in AU. */
-    a: MeasureInterface;
-    /** Orbital eccentricity (0 = circular, closer to 1 = highly elliptical). */
-    e: number;
-    /** Orbital inclination in degrees. */
-    i: number;
-    /** Argument of perihelion in degrees. */
-    w: number;
-    /** Longitude of the ascending node in degrees. */
-    om: number;
-    /** Mean anomaly at epoch in radians. */
-    angle: Radians;
-    /** Orbital period in Earth days. Negative values indicate counter clockwise orbit */
-    period: TemporalInterface;
-    /** Perihelion distance in AU. */
-    q: number;
+    /** Id of the star the comet orbits (e.g., `'sun'`). */
+    parent: string;
+    /** Orbit around the parent, with all elements including `i`, `w`, `om` and `q`. */
+    orbit: Required<OrbitInterface>;
     /** X-coordinate in a distance-based system (optional). */
     x?: DistanceInterface;
     /** Y-coordinate in a distance-based system (optional). */
@@ -70,19 +58,22 @@ export interface CometInterface {
  * @typedef {CometInterface[]} CometsType
  * @example
  * ```ts
- * const halley: CometInterface = [{
+ * const halley: CometsType = [{
+ *   id: '1p-halley',
  *   name: 'Halley',
  *   type: 'periodic comet',
  *   category: 'halley-type comet',
- *   system: 'Sun,
- *   a: { value: 17.8, unit: 'au' },
- *   e: 0.967,
- *   i: 162.26,
- *   w: 111.33,
- *   om: 58.42,
- *   angle: 0,
- *   period: { value: 76, unit: 'years' },
- *   q: 0.586,
+ *   parent: 'sun',
+ *   orbit: {
+ *     a: { value: 17.834, unit: 'au' },
+ *     e: 0.96714,
+ *     i: 162.26,
+ *     w: 111.33,
+ *     om: 58.42,
+ *     angle: 0.669857 as Radians,
+ *     period: { value: 27576, unit: 'd' },
+ *     q: 0.586
+ *   },
  *   radius: { value: 11, unit: 'km' },
  *   color: '#ffffff',
  *   size: 1.2

package/dist/celestial-bodies/comets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"comets.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/comets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAE7D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;IACnE,4CAA4C;IAC5C,QAAQ,EAAE,mBAAmB,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;IAC7E,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,CAAC,EAAE,gBAAgB,CAAC;IACpB,4EAA4E;IAC5E,CAAC,EAAE,MAAM,CAAC;IACV,sCAAsC;IACtC,CAAC,EAAE,MAAM,CAAC;IACV,yCAAyC;IACzC,CAAC,EAAE,MAAM,CAAC;IACV,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,KAAK,EAAE,OAAO,CAAC;IACf,qFAAqF;IACrF,MAAM,EAAE,iBAAiB,CAAC;IAC1B,iCAAiC;IACjC,CAAC,EAAE,MAAM,CAAC;IACV,0DAA0D;IAC1D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,0DAA0D;IAC1D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,0DAA0D;IAC1D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,oEAAoE;IACpE,SAAS,CAAC,EAAE,6BAA6B,EAAE,CAAC;IAC5C,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,UAAU,GAAG,cAAc,EAAE,CAAC"}
+{"version":3,"file":"comets.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/comets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAE7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;IACnE,4CAA4C;IAC5C,QAAQ,EAAE,mBAAmB,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;IAC7E,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,KAAK,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAChC,0DAA0D;IAC1D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,0DAA0D;IAC1D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,0DAA0D;IAC1D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,oEAAoE;IACpE,SAAS,CAAC,EAAE,6BAA6B,EAAE,CAAC;IAC5C,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,UAAU,GAAG,cAAc,EAAE,CAAC"}

package/dist/celestial-bodies/galaxies.d.ts

@@ -44,6 +44,7 @@ export interface BlackHoleInterface {
  * @example
  * ```ts
  * const milkyWay: GalaxyInterface = {
+ *   id: 'milky-way',
  *   name: 'Milky Way',
  *   type: 'Spiral',
  *   diameter: { value: 105700, unit: 'lightyears' },
@@ -54,6 +55,8 @@ export interface BlackHoleInterface {
  * @group Celestial Bodies
  */
 export interface GalaxyInterface {
+    /** Stable identifier, used by `parent` references. Never translated. */
+    id: string;
     /** Name of the galaxy. */
     name: string;
     /** Morphological classification of the galaxy. */

package/dist/celestial-bodies/galaxies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"galaxies.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/galaxies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,wDAAwD;IACxD,CAAC,EAAE,iBAAiB,CAAC;IACrB,wDAAwD;IACxD,CAAC,EAAE,iBAAiB,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,wCAAwC;IACxC,SAAS,EAAE,kBAAkB,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"galaxies.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/galaxies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,wDAAwD;IACxD,CAAC,EAAE,iBAAiB,CAAC;IACrB,wDAAwD;IACxD,CAAC,EAAE,iBAAiB,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,wCAAwC;IACxC,SAAS,EAAE,kBAAkB,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,kBAAkB,EAAE,CAAC"}

package/dist/celestial-bodies/moons.d.ts

@@ -1,15 +1,11 @@
-import { DistanceInterface, MeasureInterface } from '../distance.js';
-import type { Radians } from '../numeric.js';
-import { TemporalInterface } from '../temporal.js';
+import { DistanceInterface } from '../distance.js';
+import type { OrbitInterface } from '../orbits.js';
 import { CartesianCoordinatesInterface } from './planets.js';
 /**
  * Represents a **moon** (natural satellite) orbiting a planet.
  *
- * **Orbital Properties:**
- * - **Semi-major axis (`a`)**: Defines the moon’s orbit size in **Astronomical Units (AU)**.
- * - **Orbital eccentricity (`e`)**: Determines how elliptical the orbit is ($0 =$ circular, closer to $1 =$ highly elliptical).
- * - **Orbital period (`period`)**: Time taken for one full orbit in **Earth days**. Negative values indicate counter clockwise direction.
- * - **True anomaly (`angle`)**: The moon’s current position in its orbit (in **radians**).
+ * A moon always has a `parent` (its planet) and an `orbit` around it; see
+ * {@link OrbitInterface}.
  *
  * **Visualization Properties:**
  * - **Orbit Path (`orbitPath`)**: Precomputed trajectory for rendering.
@@ -19,43 +15,42 @@ import { CartesianCoordinatesInterface } from './planets.js';
  * @example
  * ```ts
  * const europa: MoonInterface = {
+ *   id: 'europa',
  *   name: 'Europa',
  *   category: 'natural satellite',
- *   system: 'Jupiter',
- *   a: { value: 0.00448, unit: 'au' },
- *   e: 0.009,
- *   period: { value: 3.55, unit: 'd' },
+ *   parent: 'jupiter',
+ *   orbit: {
+ *     a: { value: 0.00448, unit: 'au' },
+ *     e: 0.009,
+ *     period: { value: -3.551, unit: 'd' },
+ *     angle: 0 as Radians
+ *   },
  *   radius: { value: 1560.8, unit: 'km' },
- *   color: '#a6a6a6',
- *   angle: 0,
+ *   color: '#a6a6a6'
  * };
  * ```
  * @group Celestial Bodies
  */
 export interface MoonInterface {
+    /** Stable identifier, used by `parent` references. Never translated. */
+    id: string;
     /** Name of the moon (e.g., "Io", "Europa", "Titan"). */
     name: string;
     type?: undefined;
     /** Classification of the moon. */
     category: 'natural satellite' | 'irregular satellite' | 'retrograde satellite';
-    /** The planetary system where the moon is located (e.g., "Jupiter"). */
-    system: string;
-    /** Semi-major axis of the orbit in AU. */
-    a: MeasureInterface;
-    /** Orbital eccentricity (0 = circular, closer to 1 = highly elliptical). */
-    e: number;
+    /** Id of the planet the moon orbits (e.g., `'jupiter'`). */
+    parent: string;
+    /** Orbit around the parent planet. */
+    orbit: OrbitInterface;
     /** Semi-minor axis converted to pixels (calculated from `a` and `e`). */
     miA?: number;
     /** X-offset for the ellipse focus (accounts for eccentricity). */
     focus_x?: number;
-    /** Orbital period in Earth days. Negative values indicate counter clockwise orbit */
-    period: TemporalInterface;
     /** Physical radius of the moon in kilometres. */
     radius: DistanceInterface;
     /** Visual representation color. */
     color: string;
-    /** Current orbital position in radians (True Anomaly). */
-    angle: Radians;
     /** X-coordinate in a distance-based system (optional). */
     x?: DistanceInterface;
     /** Y-coordinate in a distance-based system (optional). */

package/dist/celestial-bodies/moons.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moons.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/moons.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,kCAAkC;IAClC,QAAQ,EACN,mBAAmB,GAAG,qBAAqB,GAAG,sBAAsB,CAAC;IACvE,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,CAAC,EAAE,gBAAgB,CAAC;IACpB,4EAA4E;IAC5E,CAAC,EAAE,MAAM,CAAC;IACV,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,MAAM,EAAE,iBAAiB,CAAC;IAC1B,iDAAiD;IACjD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,KAAK,EAAE,OAAO,CAAC;IACf,0DAA0D;IAC1D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,0DAA0D;IAC1D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,0DAA0D;IAC1D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,oEAAoE;IACpE,SAAS,CAAC,EAAE,6BAA6B,EAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,aAAa,EAAE,CAAC"}
+{"version":3,"file":"moons.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/moons.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,kCAAkC;IAClC,QAAQ,EACN,mBAAmB,GAAG,qBAAqB,GAAG,sBAAsB,CAAC;IACvE,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,KAAK,EAAE,cAAc,CAAC;IACtB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,0DAA0D;IAC1D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,0DAA0D;IAC1D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,oEAAoE;IACpE,SAAS,CAAC,EAAE,6BAA6B,EAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,aAAa,EAAE,CAAC"}

package/dist/celestial-bodies/planets.d.ts

@@ -1,6 +1,5 @@
-import { DistanceInterface, MeasureInterface } from '../distance.js';
-import type { Radians } from '../numeric.js';
-import { TemporalInterface } from '../temporal.js';
+import { DistanceInterface } from '../distance.js';
+import type { OrbitInterface } from '../orbits.js';
 /**
  * Represents **2D coordinates** for planetary positioning.
  *
@@ -18,13 +17,11 @@ export interface CartesianCoordinatesInterface {
     y: number;
 }
 /**
- * Represents a **planet** in the solar system simulation.
+ * Represents a **planet** or **planetoid**.
  *
- * **Orbital Properties:**
- * - **Semi-major axis (`a`)**: Defines the planet’s orbit size in **Astronomical Units (AU)**.
- * - **Orbital eccentricity (`e`)**: Determines how elliptical the orbit is ($0 =$ circular, closer to $1 =$ highly elliptical).
- * - **Orbital period (`period`)**: Time taken for one full orbit in **Earth days**.
- * - **True anomaly (`angle`)**: The planet’s current position in its orbit (in **radians**).
+ * A planet is bound to one `parent`: usually a star, a binary system for a
+ * circumbinary planet, or the galaxy for a rogue planet. Its `orbit` describes
+ * the motion around that parent; see {@link OrbitInterface}.
  *
  * **Classification & Visualization:**
  * - **Type (`type`)**: Scientific classification of the planet (e.g., **terrestrial, gas giant, ice planet**).
@@ -35,16 +32,19 @@ export interface CartesianCoordinatesInterface {
  * @example
  * ```ts
  * const earth: PlanetInterface = {
+ *   id: 'earth',
  *   name: 'Earth',
  *   type: 'terrestrial planet',
  *   category: 'planet',
  *   color: '#4287f5',
- *   system: 'Sun',
+ *   parent: 'sun',
+ *   orbit: {
+ *     a: { value: 1.0, unit: 'au' },
+ *     e: 0.0167,
+ *     period: { value: -365.256, unit: 'd' },
+ *     angle: 1.753 as Radians
+ *   },
  *   radius: { value: 6371, unit: 'km' },
- *   a: { value: 1.0, unit: 'au' },
- *   e: 0.0167,
- *   period: { value: 365.25, unit: 'd' },
- *   angle: 0,
  *   x: { value: 0, unit: 'au' },
  *   y: { value: 1, unit: 'au' },
  *   z: { value: 0, unit: 'au' }
@@ -53,6 +53,8 @@ export interface CartesianCoordinatesInterface {
  * @group Celestial Bodies
  */
 export interface PlanetInterface {
+    /** Stable identifier, used by `parent` references. Never translated. */
+    id: string;
     /** Name of the planet (e.g., "Earth", "Mars"). */
     name: string;
     /** Type classification of the planet. */
@@ -61,28 +63,22 @@ export interface PlanetInterface {
     category: 'planet' | 'planetoid';
     /** Visual representation color. */
     color: string;
-    /** The planetary system in which the planet exists. */
-    system: string;
+    /** Id of the star, system or galaxy the planet is bound to. */
+    parent?: string;
+    /** Orbit around the parent. */
+    orbit?: OrbitInterface;
     /** Physical radius of the planet in kilometres. */
     radius: DistanceInterface;
-    /** Semi-major axis of the orbit in AU. */
-    a: MeasureInterface;
-    /** Orbital eccentricity (0 = circular, closer to 1 = highly elliptical). */
-    e: number;
     /** Semi-minor axis of the orbit (calculated from `a` and `e`). */
     miA?: number;
     /** X-offset for the ellipse focus (accounts for eccentricity). */
     focus_x?: number;
-    /** Current orbital position in radians (True Anomaly). */
-    angle: Radians;
-    /** X-coordinate in a distance-based system. */
+    /** X-coordinate in the parent's frame. */
     x: DistanceInterface;
-    /** Y-coordinate in a distance-based system. */
+    /** Y-coordinate in the parent's frame. */
     y: DistanceInterface;
-    /** Z-coordinate in a distance-based system. */
+    /** Z-coordinate in the parent's frame. */
     z: DistanceInterface;
-    /** Orbital period in Earth days. Negative values indicate counter clockwise orbit */
-    period: TemporalInterface;
     /** Precomputed orbital path points for visualization (optional). */
     orbitPath?: CartesianCoordinatesInterface[];
 }

package/dist/celestial-bodies/planets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"planets.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/planets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,6BAA6B;IAC5C,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,IAAI,EACA,kBAAkB,GAClB,eAAe,GACf,iBAAiB,GACjB,eAAe,GACf,WAAW,GACX,WAAW,GACX,eAAe,GACf,eAAe,GACf,WAAW,GACX,YAAY,GACZ,aAAa,GACb,aAAa,GACb,cAAc,GACd,cAAc,GACd,cAAc,GACd,YAAY,GACZ,iBAAiB,GACjB,oBAAoB,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC;IACjC,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,0CAA0C;IAC1C,CAAC,EAAE,gBAAgB,CAAC;IACpB,4EAA4E;IAC5E,CAAC,EAAE,MAAM,CAAC;IACV,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,KAAK,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,CAAC,EAAE,iBAAiB,CAAC;IACrB,+CAA+C;IAC/C,CAAC,EAAE,iBAAiB,CAAC;IACrB,+CAA+C;IAC/C,CAAC,EAAE,iBAAiB,CAAC;IACrB,qFAAqF;IACrF,MAAM,EAAE,iBAAiB,CAAC;IAC1B,oEAAoE;IACpE,SAAS,CAAC,EAAE,6BAA6B,EAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,eAAe,EAAE,CAAC"}
+{"version":3,"file":"planets.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/planets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,6BAA6B;IAC5C,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,IAAI,EACA,kBAAkB,GAClB,eAAe,GACf,iBAAiB,GACjB,eAAe,GACf,WAAW,GACX,WAAW,GACX,eAAe,GACf,eAAe,GACf,WAAW,GACX,YAAY,GACZ,aAAa,GACb,aAAa,GACb,cAAc,GACd,cAAc,GACd,cAAc,GACd,YAAY,GACZ,iBAAiB,GACjB,oBAAoB,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC;IACjC,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,mDAAmD;IACnD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,CAAC,EAAE,iBAAiB,CAAC;IACrB,0CAA0C;IAC1C,CAAC,EAAE,iBAAiB,CAAC;IACrB,0CAA0C;IAC1C,CAAC,EAAE,iBAAiB,CAAC;IACrB,oEAAoE;IACpE,SAAS,CAAC,EAAE,6BAA6B,EAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,eAAe,EAAE,CAAC"}

package/dist/celestial-bodies/stars.d.ts

@@ -1,92 +1,68 @@
-import { DistanceInterface, MeasureInterface } from '../distance.js';
-import type { Radians } from '../numeric.js';
-import { TemporalInterface } from '../temporal.js';
+import { DistanceInterface } from '../distance.js';
+import type { OrbitInterface } from '../orbits.js';
 import { CartesianCoordinatesInterface } from './planets.js';
 /**
- * Represents a **star system**, which can be a planetary system or a stellar system.
+ * Represents a **star**.
  *
- * @property {string} name - Name of the star system.
- * @property {'planetary system' | 'stellar system'} type - Specifies if it is a **planetary system** or a **stellar system**.
- *
- * @example
- * ```ts
- * const solarSystem: StarSystemInterface = {
- *   name: 'Solar System',
- *   type: 'planetary system'
- * };
- * ```
- * @group Celestial Bodies
- */
-export interface StarSystemInterface {
-    name: string;
-    type: 'planetary system' | 'stellar system';
-}
-/**
- * Represents a **star** in a planetary or stellar system.
- *
- * **Orbital & Physical Properties:**
- * - **Semi-major axis (`a`)**: Defines the star’s orbit size (AU or light-years).
- * - **Orbital eccentricity (`e`)**: Determines how elliptical the orbit is.
- * - **Orbital period (`period`)**: Time taken for one full orbit. Negative values indicates counter clockwise direction.
- * - **True anomaly (`angle`)**: The star’s current position in its orbit (in **radians**).
- * - **Radius (`radius`)**: Physical size of the star.
+ * A star is bound to one `parent`: a galaxy for a single star like Vega, or a
+ * system barycenter for a star in a planetary, binary or multiple system. Its
+ * `orbit` describes the motion around that parent. A star without a `parent`
+ * is unbound, like a hypervelocity star leaving its galaxy.
  *
  * **Classification & Visualization:**
- * - **Type (`type`)**: Classification of the star (e.g., **main-sequence star, white dwarf**).
+ * - **Type (`type`)**: Spectral classification of the star (e.g., `'G2V'`).
  * - **Category (`category`)**: Defined as `'star'`.
  * - **Color (`color`)**: Used for visual representation.
  *
  * @example
  * ```ts
- * const sun: StarInterface = {
- *   name: 'Sun',
- *   type: 'G-type main-sequence',
+ * const vega: StarInterface = {
+ *   id: 'vega',
+ *   name: 'Vega',
+ *   type: 'A0V',
  *   category: 'star',
- *   system: solarSystem,
- *   radius: { value: 695700, unit: 'km' },
- *   color: '#ffcc00',
- *   a: { value: 0, unit: 'au' },
- *   e: 0,
- *   period: { value: 0, unit: 'years' },
- *   angle: 0,
- *   x: { value: 0, unit: 'au' },
- *   y: { value: 0, unit: 'au' },
- *   z: { value: 0, unit: 'au' }
+ *   parent: 'milky-way',
+ *   orbit: {
+ *     a: { value: 27230, unit: 'ly' },
+ *     e: 0.005,
+ *     period: { value: -480, unit: 'Myr' },
+ *     angle: 1.5699 as Radians
+ *   },
+ *   radius: { value: 2600000, unit: 'km' },
+ *   color: 'blue'
  * };
  * ```
  * @group Celestial Bodies
  */
 export interface StarInterface {
+    /** Stable identifier, used by `parent` references. Never translated. */
+    id: string;
     /** Name of the star. */
     name: string;
-    /** Classification of the star (e.g., main-sequence, red giant, white dwarf). */
+    /** Spectral classification of the star (e.g., `'G2V'`). */
     type: string;
     /** Defines the category as a star. */
     category: 'star';
-    /** The system in which the star exists. */
-    system: StarSystemInterface;
+    /** Id of the galaxy or system the star is bound to. */
+    parent?: string;
+    /** Orbit around the parent. */
+    orbit?: OrbitInterface;
+    /** Mass in solar masses ($M_\odot$). */
+    mass?: number;
     /** Physical radius of the star. */
     radius: DistanceInterface;
     /** Visual representation color. */
     color: string;
-    /** Semi-major axis of the orbit (AU or light-years). */
-    a: MeasureInterface;
-    /** Orbital eccentricity (0 = circular, closer to 1 = highly elliptical). */
-    e: number;
     /** Semi-minor axis of the orbit (calculated from `a` and `e`). */
     miA?: number;
     /** X-offset for the ellipse focus (accounts for eccentricity). */
     focus_x?: number;
-    /** Current orbital position in radians (True Anomaly). */
-    angle: Radians;
-    /** X-coordinate in a distance-based system. */
-    x: DistanceInterface;
-    /** Y-coordinate in a distance-based system. */
-    y: DistanceInterface;
-    /** Z-coordinate in a distance-based system. */
-    z: DistanceInterface;
-    /** Orbital period of the star. Negative values indicate counter clockwise direction. */
-    period: TemporalInterface;
+    /** X-coordinate in the parent's frame. */
+    x?: DistanceInterface;
+    /** Y-coordinate in the parent's frame. */
+    y?: DistanceInterface;
+    /** Z-coordinate in the parent's frame. */
+    z?: DistanceInterface;
     /** Precomputed orbital path points for visualization (optional). */
     orbitPath?: CartesianCoordinatesInterface[];
 }

package/dist/celestial-bodies/stars.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stars.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/stars.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAE7D;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,kBAAkB,GAAG,gBAAgB,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,aAAa;IAC5B,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,MAAM,EAAE,mBAAmB,CAAC;IAC5B,mCAAmC;IACnC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,CAAC,EAAE,gBAAgB,CAAC;IACpB,4EAA4E;IAC5E,CAAC,EAAE,MAAM,CAAC;IACV,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,KAAK,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,CAAC,EAAE,iBAAiB,CAAC;IACrB,+CAA+C;IAC/C,CAAC,EAAE,iBAAiB,CAAC;IACrB,+CAA+C;IAC/C,CAAC,EAAE,iBAAiB,CAAC;IACrB,wFAAwF;IACxF,MAAM,EAAE,iBAAiB,CAAC;IAC1B,oEAAoE;IACpE,SAAS,CAAC,EAAE,6BAA6B,EAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,aAAa,EAAE,CAAC"}
+{"version":3,"file":"stars.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/stars.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,0CAA0C;IAC1C,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,0CAA0C;IAC1C,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,oEAAoE;IACpE,SAAS,CAAC,EAAE,6BAA6B,EAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,aAAa,EAAE,CAAC"}

package/dist/celestial-bodies/systems.d.ts

@@ -1,17 +1,68 @@
+import { DistanceInterface } from '../distance.js';
+import type { OrbitInterface } from '../orbits.js';
 /**
- * Represents a star system within the space visualization.
+ * Kind of system a barycenter holds together.
+ *
+ * - `'planetary'`: one star with planets, like the Solar System.
+ * - `'binary'`: two stars orbiting a shared barycenter.
+ * - `'multiple'`: three or more stars, nested as pairs (Alpha Centauri).
+ * - `'cluster'`: a loosely bound group whose members have a parent but no orbit.
+ *
+ * @group Celestial Bodies
+ */
+export type SystemKindType = 'planetary' | 'binary' | 'multiple' | 'cluster';
+/**
+ * Represents a **system**: the barycenter (centre of mass) that its members
+ * orbit.
+ *
+ * A system does not list its members. Each member names the system as its
+ * `parent`, so the member list is derived and there is one source of truth.
+ * Systems nest: the Alpha Centauri AB pair is a system whose parent is the
+ * Alpha Centauri system.
+ *
+ * - `parent` and `orbit` set: the system orbits its parent as one body.
+ * - `parent` without `orbit`: bound to the parent, but not on a Kepler orbit.
+ * - Neither: unbound.
+ *
+ * @example
+ * ```ts
+ * const alphaCentauriAB: SystemInterface = {
+ *   id: 'alpha-centauri-ab',
+ *   name: 'Alpha Centauri AB',
+ *   kind: 'binary',
+ *   parent: 'alpha-centauri',
+ *   orbit: {
+ *     a: { value: 503, unit: 'au' },
+ *     e: 0.5,
+ *     period: { value: -547, unit: 'kyr' },
+ *     angle: Math.PI as Radians
+ *   }
+ * };
+ * ```
  * @group Celestial Bodies
  */
 export interface SystemInterface {
-    /** Name of the star system. */
+    /** Stable identifier, used by `parent` references. Never translated. */
+    id: string;
+    /** Display name of the system. */
     name: string;
-    /** List of star names in the system. */
-    stars: string[];
-    /** Distance from the Sun in light-years. */
-    distance: number;
+    /** What kind of system the barycenter holds together. */
+    kind: SystemKindType;
+    /** Id of the galaxy or system this system is bound to. */
+    parent?: string;
+    /** Orbit of the system's barycenter around its parent. */
+    orbit?: OrbitInterface;
+    /** Distance from the Sun. */
+    distance?: DistanceInterface;
+    /** X-coordinate of the barycenter in the parent's frame. */
+    x?: DistanceInterface;
+    /** Y-coordinate of the barycenter in the parent's frame. */
+    y?: DistanceInterface;
+    /** Z-coordinate of the barycenter in the parent's frame. */
+    z?: DistanceInterface;
 }
 /**
- * Type alias for a collection of star systems.
+ * Type alias for a collection of systems.
  * @group Celestial Bodies
  */
 export type SystemsType = SystemInterface[];

package/dist/celestial-bodies/systems.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"systems.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/systems.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,eAAe,EAAE,CAAC"}
+{"version":3,"file":"systems.d.ts","sourceRoot":"","sources":["../../src/celestial-bodies/systems.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,cAAc,CAAC;IACrB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,4DAA4D;IAC5D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,4DAA4D;IAC5D,CAAC,CAAC,EAAE,iBAAiB,CAAC;IACtB,4DAA4D;IAC5D,CAAC,CAAC,EAAE,iBAAiB,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,eAAe,EAAE,CAAC"}

package/dist/orbits.d.ts

@@ -1,3 +1,6 @@
+import type { MeasureInterface } from './distance.js';
+import type { Radians } from './numeric.js';
+import type { TemporalInterface } from './temporal.js';
 /**
  * Clohessy–Wiltshire / Hill relative-motion **state vector** in the LVLH frame.
  *
@@ -85,4 +88,53 @@ export type CwStateDerivative = readonly [
     /** Time derivative of `zDot` (cross-track relative acceleration). */
     zDDot: number
 ];
+/**
+ * Kepler **orbital elements** of one body around its parent.
+ *
+ * The parent is whatever the body is gravitationally bound to: a star, a
+ * planet, a barycenter or a galaxy. It is named by the `parent` id on the body
+ * or system that carries this orbit, and the elements always describe the
+ * motion **around that parent**, never around anything further up.
+ *
+ * ::: info
+ *
+ * - **Pairs**: when two bodies orbit a shared barycenter (Alpha Centauri A and
+ *   B), each carries its own orbit. Both share `e`, `period` and `angle`, their
+ *   periapses point in opposite directions, and their semi-major axes split by
+ *   mass ratio: $a_1 = a \, m_2 / (m_1 + m_2)$, where $a$ is their separation.
+ * - **Direction**: a negative `period` indicates a counter-clockwise orbit.
+ * - `i`, `w`, `om` and `q` are only given where the dataset has them (comets and
+ *   asteroids).
+ *
+ * :::
+ *
+ * @example
+ * ```ts
+ * const earthOrbit: OrbitInterface = {
+ *   a: { value: 1.0, unit: 'au' },
+ *   e: 0.0167,
+ *   period: { value: -365.256, unit: 'd' },
+ *   angle: 1.753 as Radians
+ * };
+ * ```
+ * @group Orbits
+ */
+export interface OrbitInterface {
+    /** Semi-major axis of this body's orbit around the parent's centre of mass. */
+    a: MeasureInterface;
+    /** Orbital eccentricity (0 = circular, closer to 1 = highly elliptical). */
+    e: number;
+    /** Orbital period. Negative values indicate counter clockwise direction. */
+    period: TemporalInterface;
+    /** Current orbital position at J2000 in radians (true anomaly). */
+    angle: Radians;
+    /** Orbital inclination in degrees. */
+    i?: number;
+    /** Argument of periapsis in degrees. */
+    w?: number;
+    /** Longitude of the ascending node in degrees. */
+    om?: number;
+    /** Periapsis distance $q = a(1 - e)$ in the unit of `a`. */
+    q?: number;
+}
 //# sourceMappingURL=orbits.d.ts.map

package/dist/orbits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orbits.d.ts","sourceRoot":"","sources":["../src/orbits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,OAAO,GAAG,SAAS;IAC7B,0CAA0C;IAC1C,CAAC,EAAE,MAAM;IACT,kDAAkD;IAClD,CAAC,EAAE,MAAM;IACT,oDAAoD;IACpD,CAAC,EAAE,MAAM;IACT,yDAAyD;IACzD,IAAI,EAAE,MAAM;IACZ,8DAA8D;IAC9D,IAAI,EAAE,MAAM;IACZ,8DAA8D;IAC9D,IAAI,EAAE,MAAM;CACb,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS;IACvC,yDAAyD;IACzD,IAAI,EAAE,MAAM;IACZ,8DAA8D;IAC9D,IAAI,EAAE,MAAM;IACZ,8DAA8D;IAC9D,IAAI,EAAE,MAAM;IACZ,gEAAgE;IAChE,KAAK,EAAE,MAAM;IACb,qEAAqE;IACrE,KAAK,EAAE,MAAM;IACb,qEAAqE;IACrE,KAAK,EAAE,MAAM;CACd,CAAC"}
+{"version":3,"file":"orbits.d.ts","sourceRoot":"","sources":["../src/orbits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,OAAO,GAAG,SAAS;IAC7B,0CAA0C;IAC1C,CAAC,EAAE,MAAM;IACT,kDAAkD;IAClD,CAAC,EAAE,MAAM;IACT,oDAAoD;IACpD,CAAC,EAAE,MAAM;IACT,yDAAyD;IACzD,IAAI,EAAE,MAAM;IACZ,8DAA8D;IAC9D,IAAI,EAAE,MAAM;IACZ,8DAA8D;IAC9D,IAAI,EAAE,MAAM;CACb,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS;IACvC,yDAAyD;IACzD,IAAI,EAAE,MAAM;IACZ,8DAA8D;IAC9D,IAAI,EAAE,MAAM;IACZ,8DAA8D;IAC9D,IAAI,EAAE,MAAM;IACZ,gEAAgE;IAChE,KAAK,EAAE,MAAM;IACb,qEAAqE;IACrE,KAAK,EAAE,MAAM;IACb,qEAAqE;IACrE,KAAK,EAAE,MAAM;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,CAAC,EAAE,gBAAgB,CAAC;IACpB,4EAA4E;IAC5E,CAAC,EAAE,MAAM,CAAC;IACV,4EAA4E;IAC5E,MAAM,EAAE,iBAAiB,CAAC;IAC1B,mEAAmE;IACnE,KAAK,EAAE,OAAO,CAAC;IACf,sCAAsC;IACtC,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interstellar-tools/types",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "description": "Shared TypeScript types (e.g., 3D tuples, equation result interfaces) used across the monorepo to keep APIs predictable and safe.",
   "keywords": [
     "types",
@@ -78,7 +78,7 @@
     "geo",
     "earth-sun"
   ],
-  "homepage": "https://phun-ky.net/projects/interstellar-tools",
+  "homepage": "https://phun-ky.net/interstellar-tools/",
   "bugs": {
     "url": "https://github.com/phun-ky/interstellar-tools/issues"
   },
@@ -111,10 +111,8 @@
     "test:ci": "glob-bin -c \"node --import tsx --test --no-warnings --experimental-test-coverage --test-reporter=cobertura --test-reporter-destination=coverage/cobertura-coverage.xml --test-reporter=spec --test-reporter-destination=stdout\" \"**/__tests__/**/*.spec.ts\""
   },
   "devDependencies": {
-    "@types/node": "^24.19.1",
-    "eslint": "^9.27.0",
-    "eslint-config-phun-ky": "^1.0.3",
-    "prettier": "^3.8.3",
+    "@types/node": "^24.19.2",
+    "prettier": "^3.9.10",
     "typescript": "^6.0.3"
   },
   "engines": {