caelus 0.11.0 → 0.13.0

package/README.md

@@ -100,4 +100,4 @@ test/golden.test.ts  conformance suite vs Python fixtures
 - caelus — this package
 - [caelus-birth](https://www.npmjs.com/package/caelus-birth) — local birth time + place → UT (charts take UT; use this)
 - [caelus-wheel](https://www.npmjs.com/package/caelus-wheel) — React SVG chart wheel
-- [caelus-mcp](https://www.npmjs.com/package/caelus-mcp) — MCP server, nine chart tools over stdio
+- [caelus-mcp](https://www.npmjs.com/package/caelus-mcp) — MCP server, eighteen chart tools over stdio

package/accuracy.json

@@ -273,7 +273,7 @@
   "counts": {
     "house_systems": 12,
     "sidereal_ayanamsas": 7,
-    "mcp_tools": 9,
+    "mcp_tools": 18,
     "default_bodies": 13
   }
 }

package/dist/src/chart.d.ts

@@ -17,51 +17,82 @@ export interface Observer {
     lonEast: number;
     altM?: number;
 }
+/** Options shared by the single-body calls ({@link Engine.position},
+ *  {@link Engine.longitude}) and by charts. */
 export interface CalcOptions {
+    /** Tropical (the default) or a sidereal ayanamsa, e.g. `"sidereal:lahiri"`. */
     zodiac?: Zodiac;
+    /** Apply topocentric parallax for `observer`. Defaults to `false`. */
     topocentric?: boolean;
+    /** Observer location; required when `topocentric` is set. */
     observer?: Observer;
 }
+/** Options for {@link Engine.chart} and {@link Engine.chartAt}, extending
+ *  {@link CalcOptions}. */
 export interface ChartOptions extends CalcOptions {
+    /** House system to compute. Defaults to `"placidus"`. */
     houseSystem?: HouseSystem;
+    /** Extra bodies to compute beyond the core chart set. */
     bodies?: BodyId[];
+    /** Per-aspect orb overrides in degrees, keyed by aspect name. */
     orbs?: Record<string, number>;
 }
+/** A body's full apparent position, as returned by {@link Engine.position}. */
 export interface Position {
+    /** Ecliptic longitude in degrees, `[0, 360)`. */
     lon: number;
+    /** Daily motion in longitude, degrees/day; negative when retrograde. */
     speed: number;
+    /** Whether the body is in apparent retrograde motion (`speed < 0`). */
     retrograde: boolean;
+    /** Zodiac sign containing `lon`, e.g. `"Leo"`. */
     sign: string;
+    /** Longitude within the sign, degrees `[0, 30)`. */
     signDeg: number;
     /** Ecliptic latitude, deg (0 for nodes). */
     lat: number;
     /** Geocentric distance in AU (Moon included); null for nodes and Lilith. */
     dist: number | null;
-    /** Equatorial coordinates, true equinox of date, deg. */
+    /** Equatorial right ascension, true equinox of date, degrees. */
     ra: number;
+    /** Equatorial declination, true equinox of date, degrees. */
     dec: number;
 }
+/** One aspect between two bodies in a {@link Chart}. */
 export interface Aspect {
+    /** First body id. */
     a: string;
+    /** Second body id. */
     b: string;
+    /** Aspect name, e.g. `"trine"`. */
     aspect: string;
+    /** Orb from exact, in degrees. */
     orb: number;
 }
+/** A full natal chart, as returned by {@link Engine.chart} and
+ *  {@link Engine.chartAt}. Longitudes are degrees in the chart's `zodiac`. */
 export interface Chart {
+    /** The instant, as a Julian Day (UT). */
     jdUt: number;
+    /** The zodiac the longitudes are expressed in. */
     zodiac: Zodiac;
     /** House system actually used. May differ from the request: Placidus and
      *  Koch are undefined above the polar circles and fall back to whole_sign. */
     houseSystem: HouseSystem;
+    /** The house system originally requested, before any polar fallback. */
     houseSystemRequested: HouseSystem;
+    /** Apparent {@link Position} per body, keyed by body id. */
     bodies: Record<string, Position>;
+    /** Chart angles in degrees: Ascendant, Midheaven, Vertex, East Point. */
     angles: {
         asc: number;
         mc: number;
         vertex: number;
         eastPoint: number;
     };
+    /** The twelve house cusp longitudes in degrees, house 1 first. */
     cusps: number[];
+    /** Aspects found among the bodies, within the active orbs. */
     aspects: Aspect[];
 }
 export declare class Engine {
@@ -72,15 +103,56 @@ export declare class Engine {
     constructor(data: EngineData);
     private pack;
     private moonInRange;
-    /** Body ids this engine can compute, given the data it was handed. */
+    /**
+     * The body ids this engine can compute, given the data pack it was
+     * constructed with. The core set is always present; extra asteroids and
+     * hypotheticals appear only when their Chebyshev or Kepler packs are loaded.
+     *
+     * @returns Body ids accepted by {@link Engine.position},
+     *   {@link Engine.longitude}, and {@link Engine.chart}.
+     * @example
+     * ```ts
+     * engine.bodies().includes("ceres"); // true only if the Ceres pack is loaded
+     * ```
+     */
     bodies(): BodyId[];
-    /** Apparent geocentric [lon rad, lat rad, dist AU | null] at TT jde.
-     *  Building block for the events module; chart consumers want
-     *  position() instead. */
+    /**
+     * Low-level apparent geocentric ecliptic coordinates at a **TT** Julian Day,
+     * in **radians**. This is the engine's internal building block for the events
+     * module; it takes TT (not UT) and does no zodiac shift. Most callers want
+     * {@link Engine.position} (full Position in degrees) or
+     * {@link Engine.longitude} (longitude in degrees) instead.
+     *
+     * @param body A body id from {@link Engine.bodies}.
+     * @param jde Julian Day in **TT** (Terrestrial Time), e.g. `jdTT(jdUt)`.
+     * @returns `[lon, lat, dist]` — longitude and latitude in **radians** (true
+     *   equinox of date), distance in AU, or `null` distance for nodes and
+     *   Lilith points.
+     * @throws Error if no data is loaded for `body`.
+     */
     ecliptic(body: BodyId, jde: number): [number, number, number | null];
     /** Degrees to subtract from a true-equinox tropical longitude. */
     private ayanShift;
-    /** Apparent place of a catalog star: lon/lat/ra/dec (deg), sign, mag. */
+    /**
+     * Apparent place of a catalog fixed star at a Julian Day (UT). Requires the
+     * fixed-star catalog to be present in the data pack; see
+     * {@link Engine.starNames} for the available names.
+     *
+     * @param name Catalog star name, e.g. `"Regulus"` (see
+     *   {@link Engine.starNames}).
+     * @param jdUt Julian Day in UT.
+     * @param opts Calculation options; only `zodiac` is meaningful here (tropical
+     *   by default, or a sidereal ayanamsa).
+     * @returns Ecliptic `lon`/`lat`, equatorial `ra`/`dec` (all degrees), the
+     *   zodiac `sign` and `signDeg`, and the star's visual magnitude `mag`.
+     * @throws Error if `name` is not in the loaded catalog.
+     * @example
+     * ```ts
+     * const regulus = engine.fixedStar("Regulus", julianDay(2025, 1, 1));
+     * regulus.sign;  // e.g. "Leo"
+     * regulus.mag;   // apparent magnitude
+     * ```
+     */
     fixedStar(name: string, jdUt: number, opts?: CalcOptions): {
         lon: number;
         lat: number;
@@ -90,23 +162,131 @@ export declare class Engine {
         sign: string;
         signDeg: number;
     };
-    /** Names in the loaded fixed-star catalog (sorted). */
+    /**
+     * The names in the loaded fixed-star catalog, sorted. Empty if no catalog is
+     * present in the data pack. Pass any of these to {@link Engine.fixedStar}.
+     *
+     * @returns Sorted catalog star names.
+     */
     starNames(): string[];
     private lonOnly;
-    /** Apparent geocentric ecliptic longitude (deg). Tropical: true equinox
-     *  of date. Sidereal: mean equinox minus ayanamsa. */
+    /**
+     * Apparent geocentric ecliptic longitude of a body, in degrees `[0, 360)`,
+     * at a Julian Day (UT). The fast path when you need only a longitude — a
+     * transit position, an aspect angle, a sign — without the full
+     * {@link Position}. In the tropical zodiac this is referred to the true
+     * equinox of date; sidereal subtracts the ayanamsa.
+     *
+     * @param body A body id from {@link Engine.bodies}.
+     * @param jdUt Julian Day in UT.
+     * @param opts Calculation options: `zodiac` (tropical or a sidereal
+     *   ayanamsa), and `topocentric` with an `observer` for a parallax-corrected
+     *   place.
+     * @returns Ecliptic longitude in degrees, `[0, 360)`.
+     * @example
+     * ```ts
+     * engine.longitude("mars", julianDay(2025, 6, 1));               // tropical
+     * engine.longitude("mars", julianDay(2025, 6, 1), { zodiac: "sidereal:lahiri" });
+     * ```
+     * @see {@link Engine.position} for speed, retrograde, latitude, and distance.
+     */
     longitude(body: BodyId, jdUt: number, opts?: CalcOptions): number;
-    /** Geometric heliocentric ecliptic of date (deg, deg, AU). */
+    /**
+     * Geometric heliocentric ecliptic position (Sun-centred) at a Julian Day
+     * (UT), referred to the ecliptic of date. Unlike {@link Engine.position},
+     * this is a geometric place — no light-time, aberration, or nutation — and is
+     * undefined for the Sun, the Moon, and the lunar nodes.
+     *
+     * @param body A Sun-orbiting body (planet or asteroid) from
+     *   {@link Engine.bodies}.
+     * @param jdUt Julian Day in UT.
+     * @returns Heliocentric `lon`/`lat` in degrees and `dist` in AU.
+     * @throws Error if `body` has no heliocentric solution (e.g. the Moon).
+     */
     heliocentric(body: BodyId, jdUt: number): {
         lon: number;
         lat: number;
         dist: number;
     };
-    /** Full position: lon/speed/retrograde/sign + lat, dist (AU), ra, dec. */
+    /**
+     * Full apparent position of a body at a Julian Day (UT): ecliptic longitude
+     * and daily speed (with a retrograde flag), the zodiac sign, ecliptic
+     * latitude, geocentric distance, and equatorial right ascension and
+     * declination. The general-purpose single-body call; use
+     * {@link Engine.longitude} when you need only the longitude.
+     *
+     * @param body A body id from {@link Engine.bodies}.
+     * @param jdUt Julian Day in UT.
+     * @param opts Calculation options: `zodiac` (tropical or a sidereal
+     *   ayanamsa), and `topocentric` with an `observer` for a parallax-corrected
+     *   place.
+     * @returns A {@link Position}: `lon`, `speed`, `retrograde`, `sign`,
+     *   `signDeg`, `lat`, `dist` (AU; `null` for nodes and Lilith), `ra`, `dec`.
+     * @example
+     * ```ts
+     * const mars = engine.position("mars", julianDay(2025, 6, 1));
+     * mars.retrograde; // boolean
+     * mars.speed;      // degrees/day (negative when retrograde)
+     * ```
+     */
     position(body: BodyId, jdUt: number, opts?: CalcOptions): Position;
-    /** Full natal chart. Time is UT. East longitude positive. The ninth
-     *  argument takes a house system name (0.2.x form) or a ChartOptions bag. */
+    /**
+     * Full natal chart: body positions, house cusps, angles, and aspects for one
+     * instant and place.
+     *
+     * The first six arguments are calendar fields in **UT** — not local civil
+     * time, and not a Julian Day. Passing a JD in `y` builds an instant far
+     * outside the fitted range and throws `RangeError`; use {@link Engine.chartAt}
+     * for a chart from a JD. For a birth time given in a local time zone, resolve
+     * it to UT first (see the `caelus-birth` package).
+     *
+     * @param y Year in UT, e.g. `1990` — a calendar year, not a Julian Day.
+     * @param mo Month, `1`–`12`.
+     * @param d Day of month, `1`–`31`.
+     * @param h Hour in UT, `0`–`23`.
+     * @param mi Minute, `0`–`59`.
+     * @param s Second, `0`–`59`.
+     * @param lat Geographic latitude in degrees, north positive.
+     * @param lonEast Geographic longitude in degrees, **east positive** (so
+     *   82.46° W is `-82.46`).
+     * @param opts A house-system name (e.g. `"placidus"`) or a
+     *   {@link ChartOptions} bag for zodiac, topocentric mode, extra bodies, and
+     *   custom orbs. Defaults to Placidus houses in the tropical zodiac.
+     * @returns A {@link Chart}: `bodies`, `cusps`, `angles`, and `aspects`, plus
+     *   `jdUt` and the house system actually used (Placidus and Koch fall back to
+     *   whole-sign above the polar circles).
+     * @throws RangeError if the instant lands outside the fitted range
+     *   (1800–2149) — most often from passing a Julian Day where a year belongs.
+     * @example
+     * ```ts
+     * // 1990-06-10 14:30 UT at Tampa, FL (27.95° N, 82.46° W), Placidus houses
+     * const chart = engine.chart(1990, 6, 10, 14, 30, 0, 27.95, -82.46, "placidus");
+     * chart.bodies.sun.lon; // Sun's ecliptic longitude, degrees
+     * chart.angles.asc;     // Ascendant, degrees
+     * ```
+     * @see {@link Engine.chartAt} to build the same chart from a Julian Day.
+     */
     chart(y: number, mo: number, d: number, h: number, mi: number, s: number, lat: number, lonEast: number, opts?: HouseSystem | ChartOptions): Chart;
+    /**
+     * Full natal chart from a Julian Day (UT) — identical output to
+     * {@link Engine.chart}, without the calendar round-trip. Reach for this when
+     * you already hold a JD: transit and event scans, `rankMoments` winners, or
+     * `position`/`longitude` workflows.
+     *
+     * @param jdUt Julian Day in UT, e.g. from {@link julianDay} or a scan.
+     * @param lat Geographic latitude in degrees, north positive.
+     * @param lonEast Geographic longitude in degrees, east positive.
+     * @param opts A house-system name or a {@link ChartOptions} bag. Defaults to
+     *   Placidus houses in the tropical zodiac.
+     * @returns The same {@link Chart} shape returned by {@link Engine.chart}.
+     * @example
+     * ```ts
+     * const jd = julianDay(1990, 6, 10, 14, 30, 0);
+     * const chart = engine.chartAt(jd, 27.95, -82.46, "placidus");
+     * ```
+     * @see {@link Engine.chart} for the calendar-field entry point.
+     */
+    chartAt(jdUt: number, lat: number, lonEast: number, opts?: HouseSystem | ChartOptions): Chart;
 }
 export declare function findAspects(bodies: Record<string, Position>, orbs?: Record<string, number>): Aspect[];
 export declare function fmtLon(deg: number): string;

package/dist/src/chart.js

@@ -73,7 +73,18 @@ export class Engine {
         return !!this.moonCheb
             && this.moonCheb.jd0 <= jde - 0.1 && jde + 0.1 <= this.moonCheb.jd1;
     }
-    /** Body ids this engine can compute, given the data it was handed. */
+    /**
+     * The body ids this engine can compute, given the data pack it was
+     * constructed with. The core set is always present; extra asteroids and
+     * hypotheticals appear only when their Chebyshev or Kepler packs are loaded.
+     *
+     * @returns Body ids accepted by {@link Engine.position},
+     *   {@link Engine.longitude}, and {@link Engine.chart}.
+     * @example
+     * ```ts
+     * engine.bodies().includes("ceres"); // true only if the Ceres pack is loaded
+     * ```
+     */
     bodies() {
         return [
             ...[...BODIES, ...EXTRA_BODIES].filter((b) => b !== "chiron" || this.chironCheb),
@@ -81,9 +92,20 @@ export class Engine {
             ...Object.keys(this.data.keplerPack?.bodies ?? {}),
         ];
     }
-    /** Apparent geocentric [lon rad, lat rad, dist AU | null] at TT jde.
-     *  Building block for the events module; chart consumers want
-     *  position() instead. */
+    /**
+     * Low-level apparent geocentric ecliptic coordinates at a **TT** Julian Day,
+     * in **radians**. This is the engine's internal building block for the events
+     * module; it takes TT (not UT) and does no zodiac shift. Most callers want
+     * {@link Engine.position} (full Position in degrees) or
+     * {@link Engine.longitude} (longitude in degrees) instead.
+     *
+     * @param body A body id from {@link Engine.bodies}.
+     * @param jde Julian Day in **TT** (Terrestrial Time), e.g. `jdTT(jdUt)`.
+     * @returns `[lon, lat, dist]` — longitude and latitude in **radians** (true
+     *   equinox of date), distance in AU, or `null` distance for nodes and
+     *   Lilith points.
+     * @throws Error if no data is loaded for `body`.
+     */
     ecliptic(body, jde) {
         if (body === "sun")
             return sunApparent(this.data, jde);
@@ -140,7 +162,26 @@ export class Engine {
         }
         return mod(nutation(this.data, jde)[0] / DEG + ayanamsa(jde, mode), 360);
     }
-    /** Apparent place of a catalog star: lon/lat/ra/dec (deg), sign, mag. */
+    /**
+     * Apparent place of a catalog fixed star at a Julian Day (UT). Requires the
+     * fixed-star catalog to be present in the data pack; see
+     * {@link Engine.starNames} for the available names.
+     *
+     * @param name Catalog star name, e.g. `"Regulus"` (see
+     *   {@link Engine.starNames}).
+     * @param jdUt Julian Day in UT.
+     * @param opts Calculation options; only `zodiac` is meaningful here (tropical
+     *   by default, or a sidereal ayanamsa).
+     * @returns Ecliptic `lon`/`lat`, equatorial `ra`/`dec` (all degrees), the
+     *   zodiac `sign` and `signDeg`, and the star's visual magnitude `mag`.
+     * @throws Error if `name` is not in the loaded catalog.
+     * @example
+     * ```ts
+     * const regulus = engine.fixedStar("Regulus", julianDay(2025, 1, 1));
+     * regulus.sign;  // e.g. "Leo"
+     * regulus.mag;   // apparent magnitude
+     * ```
+     */
     fixedStar(name, jdUt, opts = {}) {
         const s = this.data.fixedStars?.stars[name];
         if (!s)
@@ -157,7 +198,12 @@ export class Engine {
             sign: SIGNS[Math.floor(lon / 30)], signDeg: mod(lon, 30),
         };
     }
-    /** Names in the loaded fixed-star catalog (sorted). */
+    /**
+     * The names in the loaded fixed-star catalog, sorted. Empty if no catalog is
+     * present in the data pack. Pass any of these to {@link Engine.fixedStar}.
+     *
+     * @returns Sorted catalog star names.
+     */
     starNames() {
         return Object.keys(this.data.fixedStars?.stars ?? {}).sort();
     }
@@ -173,14 +219,43 @@ export class Engine {
             lonDeg = mod(lonDeg - this.ayanShift(jde, mode), 360);
         return lonDeg;
     }
-    /** Apparent geocentric ecliptic longitude (deg). Tropical: true equinox
-     *  of date. Sidereal: mean equinox minus ayanamsa. */
+    /**
+     * Apparent geocentric ecliptic longitude of a body, in degrees `[0, 360)`,
+     * at a Julian Day (UT). The fast path when you need only a longitude — a
+     * transit position, an aspect angle, a sign — without the full
+     * {@link Position}. In the tropical zodiac this is referred to the true
+     * equinox of date; sidereal subtracts the ayanamsa.
+     *
+     * @param body A body id from {@link Engine.bodies}.
+     * @param jdUt Julian Day in UT.
+     * @param opts Calculation options: `zodiac` (tropical or a sidereal
+     *   ayanamsa), and `topocentric` with an `observer` for a parallax-corrected
+     *   place.
+     * @returns Ecliptic longitude in degrees, `[0, 360)`.
+     * @example
+     * ```ts
+     * engine.longitude("mars", julianDay(2025, 6, 1));               // tropical
+     * engine.longitude("mars", julianDay(2025, 6, 1), { zodiac: "sidereal:lahiri" });
+     * ```
+     * @see {@link Engine.position} for speed, retrograde, latitude, and distance.
+     */
     longitude(body, jdUt, opts = {}) {
         const mode = parseZodiac(opts.zodiac ?? "tropical");
         const topo = opts.topocentric ? opts.observer ?? null : null;
         return this.lonOnly(body, jdUt, mode, topo);
     }
-    /** Geometric heliocentric ecliptic of date (deg, deg, AU). */
+    /**
+     * Geometric heliocentric ecliptic position (Sun-centred) at a Julian Day
+     * (UT), referred to the ecliptic of date. Unlike {@link Engine.position},
+     * this is a geometric place — no light-time, aberration, or nutation — and is
+     * undefined for the Sun, the Moon, and the lunar nodes.
+     *
+     * @param body A Sun-orbiting body (planet or asteroid) from
+     *   {@link Engine.bodies}.
+     * @param jdUt Julian Day in UT.
+     * @returns Heliocentric `lon`/`lat` in degrees and `dist` in AU.
+     * @throws Error if `body` has no heliocentric solution (e.g. the Moon).
+     */
     heliocentric(body, jdUt) {
         const jde = jdTT(jdUt);
         let l;
@@ -214,7 +289,27 @@ export class Engine {
         }
         return { lon: l / DEG, lat: b / DEG, dist: r };
     }
-    /** Full position: lon/speed/retrograde/sign + lat, dist (AU), ra, dec. */
+    /**
+     * Full apparent position of a body at a Julian Day (UT): ecliptic longitude
+     * and daily speed (with a retrograde flag), the zodiac sign, ecliptic
+     * latitude, geocentric distance, and equatorial right ascension and
+     * declination. The general-purpose single-body call; use
+     * {@link Engine.longitude} when you need only the longitude.
+     *
+     * @param body A body id from {@link Engine.bodies}.
+     * @param jdUt Julian Day in UT.
+     * @param opts Calculation options: `zodiac` (tropical or a sidereal
+     *   ayanamsa), and `topocentric` with an `observer` for a parallax-corrected
+     *   place.
+     * @returns A {@link Position}: `lon`, `speed`, `retrograde`, `sign`,
+     *   `signDeg`, `lat`, `dist` (AU; `null` for nodes and Lilith), `ra`, `dec`.
+     * @example
+     * ```ts
+     * const mars = engine.position("mars", julianDay(2025, 6, 1));
+     * mars.retrograde; // boolean
+     * mars.speed;      // degrees/day (negative when retrograde)
+     * ```
+     */
     position(body, jdUt, opts = {}) {
         const mode = parseZodiac(opts.zodiac ?? "tropical");
         const topo = opts.topocentric ? opts.observer ?? null : null;
@@ -239,14 +334,69 @@ export class Engine {
             ra: ra / DEG, dec: dec / DEG,
         };
     }
-    /** Full natal chart. Time is UT. East longitude positive. The ninth
-     *  argument takes a house system name (0.2.x form) or a ChartOptions bag. */
+    /**
+     * Full natal chart: body positions, house cusps, angles, and aspects for one
+     * instant and place.
+     *
+     * The first six arguments are calendar fields in **UT** — not local civil
+     * time, and not a Julian Day. Passing a JD in `y` builds an instant far
+     * outside the fitted range and throws `RangeError`; use {@link Engine.chartAt}
+     * for a chart from a JD. For a birth time given in a local time zone, resolve
+     * it to UT first (see the `caelus-birth` package).
+     *
+     * @param y Year in UT, e.g. `1990` — a calendar year, not a Julian Day.
+     * @param mo Month, `1`–`12`.
+     * @param d Day of month, `1`–`31`.
+     * @param h Hour in UT, `0`–`23`.
+     * @param mi Minute, `0`–`59`.
+     * @param s Second, `0`–`59`.
+     * @param lat Geographic latitude in degrees, north positive.
+     * @param lonEast Geographic longitude in degrees, **east positive** (so
+     *   82.46° W is `-82.46`).
+     * @param opts A house-system name (e.g. `"placidus"`) or a
+     *   {@link ChartOptions} bag for zodiac, topocentric mode, extra bodies, and
+     *   custom orbs. Defaults to Placidus houses in the tropical zodiac.
+     * @returns A {@link Chart}: `bodies`, `cusps`, `angles`, and `aspects`, plus
+     *   `jdUt` and the house system actually used (Placidus and Koch fall back to
+     *   whole-sign above the polar circles).
+     * @throws RangeError if the instant lands outside the fitted range
+     *   (1800–2149) — most often from passing a Julian Day where a year belongs.
+     * @example
+     * ```ts
+     * // 1990-06-10 14:30 UT at Tampa, FL (27.95° N, 82.46° W), Placidus houses
+     * const chart = engine.chart(1990, 6, 10, 14, 30, 0, 27.95, -82.46, "placidus");
+     * chart.bodies.sun.lon; // Sun's ecliptic longitude, degrees
+     * chart.angles.asc;     // Ascendant, degrees
+     * ```
+     * @see {@link Engine.chartAt} to build the same chart from a Julian Day.
+     */
     chart(y, mo, d, h, mi, s, lat, lonEast, opts = "placidus") {
+        return this.chartAt(julianDay(y, mo, d, h, mi, s), lat, lonEast, opts);
+    }
+    /**
+     * Full natal chart from a Julian Day (UT) — identical output to
+     * {@link Engine.chart}, without the calendar round-trip. Reach for this when
+     * you already hold a JD: transit and event scans, `rankMoments` winners, or
+     * `position`/`longitude` workflows.
+     *
+     * @param jdUt Julian Day in UT, e.g. from {@link julianDay} or a scan.
+     * @param lat Geographic latitude in degrees, north positive.
+     * @param lonEast Geographic longitude in degrees, east positive.
+     * @param opts A house-system name or a {@link ChartOptions} bag. Defaults to
+     *   Placidus houses in the tropical zodiac.
+     * @returns The same {@link Chart} shape returned by {@link Engine.chart}.
+     * @example
+     * ```ts
+     * const jd = julianDay(1990, 6, 10, 14, 30, 0);
+     * const chart = engine.chartAt(jd, 27.95, -82.46, "placidus");
+     * ```
+     * @see {@link Engine.chart} for the calendar-field entry point.
+     */
+    chartAt(jdUt, lat, lonEast, opts = "placidus") {
         const o = typeof opts === "string" ? { houseSystem: opts } : opts;
         const houseSystem = o.houseSystem ?? "placidus";
         const zodiac = o.zodiac ?? "tropical";
         const mode = parseZodiac(zodiac);
-        const jdUt = julianDay(y, mo, d, h, mi, s);
         const calc = {
             zodiac,
             topocentric: o.topocentric,

package/dist/src/compiler.d.ts

@@ -15,9 +15,25 @@ export type Constraint = {
     degree: number;
     weight?: number;
 };
-/** Degrees by which a single constraint is unmet given the longitudes. */
+/**
+ * Degrees by which a single {@link Constraint} is unmet for a set of body
+ * longitudes — `0` when satisfied. The pure building block of {@link formLoss}
+ * and {@link compileForm}.
+ *
+ * @param lons Body longitudes in degrees, keyed by body id.
+ * @param c The constraint to score.
+ * @returns The unmet amount in degrees (`0` = satisfied).
+ */
 export declare function constraintLoss(lons: Record<string, number>, c: Constraint): number;
-/** Total weighted constraint loss for a set of body longitudes. */
+/**
+ * Total weighted loss for a set of body longitudes — the sum of each
+ * constraint's {@link constraintLoss} times its weight. The objective
+ * {@link compileForm} minimizes.
+ *
+ * @param lons Body longitudes in degrees, keyed by body id.
+ * @param constraints The constraints to score.
+ * @returns The total weighted loss in degrees (`0` = all satisfied).
+ */
 export declare function formLoss(lons: Record<string, number>, constraints: Constraint[]): number;
 export interface CompiledForm {
     longitudes: Record<string, number>;
@@ -34,5 +50,30 @@ export interface CompileOptions {
     /** A form is impossible when its worst constraint exceeds this (degrees). */
     impossibleDeg?: number;
 }
-/** Find body longitudes minimizing the weighted constraint loss. */
+/**
+ * Synthesize a chart form from geometric constraints — the inverse of
+ * (time, place) → chart. Given weighted {@link Constraint}s (aspects between
+ * bodies, sign placements, exact degrees), find the body longitudes that best
+ * satisfy them via deterministic coordinate descent, and report how well they
+ * can be met. When even the best fit is poor, the form is flagged `impossible`
+ * — a valid, informative result.
+ *
+ * @param constraints The geometric constraints to satisfy; each may carry a
+ *   `weight` (default `1`).
+ * @param opts `restarts` and `iters` tune the optimizer (more = slower, more
+ *   thorough); `impossibleDeg` is the worst-constraint threshold in degrees
+ *   above which the form is impossible. Defaults: `12`, `8`, `5`.
+ * @returns A {@link CompiledForm}: solved `longitudes`, total `residual`,
+ *   `maxConstraintLoss`, the `impossible` flag, and each constraint annotated
+ *   with its `loss`.
+ * @example
+ * ```ts
+ * const form = compileForm([
+ *   { kind: "aspect", a: "sun", b: "moon", angle: 120 }, // trine
+ *   { kind: "sign", body: "sun", sign: 0 },              // Aries
+ * ]);
+ * form.impossible;     // false
+ * form.longitudes.sun; // a degree within Aries
+ * ```
+ */
 export declare function compileForm(constraints: Constraint[], opts?: CompileOptions): CompiledForm;

package/dist/src/compiler.js

@@ -21,7 +21,15 @@ function signLoss(lon, sign) {
         return 0.0;
     return Math.min(d - 30.0, 360.0 - d);
 }
-/** Degrees by which a single constraint is unmet given the longitudes. */
+/**
+ * Degrees by which a single {@link Constraint} is unmet for a set of body
+ * longitudes — `0` when satisfied. The pure building block of {@link formLoss}
+ * and {@link compileForm}.
+ *
+ * @param lons Body longitudes in degrees, keyed by body id.
+ * @param c The constraint to score.
+ * @returns The unmet amount in degrees (`0` = satisfied).
+ */
 export function constraintLoss(lons, c) {
     if (c.kind === "aspect")
         return Math.abs(angDist(lons[c.a], lons[c.b]) - c.angle);
@@ -29,7 +37,15 @@ export function constraintLoss(lons, c) {
         return signLoss(lons[c.body], c.sign);
     return angDist(lons[c.body], c.degree);
 }
-/** Total weighted constraint loss for a set of body longitudes. */
+/**
+ * Total weighted loss for a set of body longitudes — the sum of each
+ * constraint's {@link constraintLoss} times its weight. The objective
+ * {@link compileForm} minimizes.
+ *
+ * @param lons Body longitudes in degrees, keyed by body id.
+ * @param constraints The constraints to score.
+ * @returns The total weighted loss in degrees (`0` = all satisfied).
+ */
 export function formLoss(lons, constraints) {
     let total = 0;
     for (const c of constraints)
@@ -58,7 +74,32 @@ function bodyLoss(lons, body, constraints) {
             total += (c.weight ?? 1.0) * constraintLoss(lons, c);
     return total;
 }
-/** Find body longitudes minimizing the weighted constraint loss. */
+/**
+ * Synthesize a chart form from geometric constraints — the inverse of
+ * (time, place) → chart. Given weighted {@link Constraint}s (aspects between
+ * bodies, sign placements, exact degrees), find the body longitudes that best
+ * satisfy them via deterministic coordinate descent, and report how well they
+ * can be met. When even the best fit is poor, the form is flagged `impossible`
+ * — a valid, informative result.
+ *
+ * @param constraints The geometric constraints to satisfy; each may carry a
+ *   `weight` (default `1`).
+ * @param opts `restarts` and `iters` tune the optimizer (more = slower, more
+ *   thorough); `impossibleDeg` is the worst-constraint threshold in degrees
+ *   above which the form is impossible. Defaults: `12`, `8`, `5`.
+ * @returns A {@link CompiledForm}: solved `longitudes`, total `residual`,
+ *   `maxConstraintLoss`, the `impossible` flag, and each constraint annotated
+ *   with its `loss`.
+ * @example
+ * ```ts
+ * const form = compileForm([
+ *   { kind: "aspect", a: "sun", b: "moon", angle: 120 }, // trine
+ *   { kind: "sign", body: "sun", sign: 0 },              // Aries
+ * ]);
+ * form.impossible;     // false
+ * form.longitudes.sun; // a degree within Aries
+ * ```
+ */
 export function compileForm(constraints, opts = {}) {
     const restarts = opts.restarts ?? 12;
     const iters = opts.iters ?? 8;