caelus 0.11.0 → 0.13.0

package/dist/src/features.d.ts

@@ -1,19 +1,63 @@
 import { Engine, BodyId, Zodiac } from "./chart.js";
 import { RankedMoment } from "./scan.js";
 export declare const DEFAULT_BODIES: string[];
-/** Flat vector [w*cos(lon), w*sin(lon), ...] for the given (longitude, weight)
- *  pairs, in order. */
+/**
+ * Build a feature vector from explicit `(longitude, weight)` pairs: each pair
+ * contributes a weighted unit-circle point `[w·cos(lon), w·sin(lon)]`. The
+ * low-level primitive behind {@link chartFeatures}; most callers want that.
+ *
+ * @param weightedLons `[longitudeDeg, weight]` pairs, in the order they should
+ *   appear in the vector.
+ * @returns A flat vector, two entries per pair.
+ */
 export declare function featureVector(weightedLons: [number, number][]): number[];
-/** Cosine similarity of two feature vectors, in [-1, 1]. */
+/**
+ * Cosine similarity of two feature vectors, in `[-1, 1]`. For vectors from
+ * {@link chartFeatures} this is a weighted mean of `cos(Δlongitude)` per body:
+ * `1` when the configurations coincide, falling off as bodies diverge.
+ *
+ * @param a First feature vector.
+ * @param b Second feature vector (compared over the shorter length).
+ * @returns Similarity in `[-1, 1]`; `0` if either vector is all zeros.
+ */
 export declare function cosineSimilarity(a: number[], b: number[]): number;
 export interface FeatureOptions {
     bodies?: BodyId[];
     weights?: Record<string, number>;
     zodiac?: Zodiac;
 }
-/** Feature vector for the sky at jdUt over an ordered set of bodies. */
+/**
+ * Encode the sky at an instant as a feature vector: each body's ecliptic
+ * longitude becomes a weighted unit-circle point. The deterministic substrate
+ * for matching and searching chart configurations — compare two with
+ * {@link cosineSimilarity}, or rank a time range against one with
+ * {@link searchConfigurations}.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jdUt Julian Day in UT.
+ * @param opts `bodies` (ordered; defaults to the ten major bodies), per-body
+ *   `weights`, and `zodiac` (tropical by default).
+ * @returns A flat vector `[w·cos(lon), w·sin(lon), ...]`, two entries per body
+ *   in `bodies` order.
+ * @example
+ * ```ts
+ * const target = chartFeatures(engine, julianDay(2000, 1, 1));
+ * const now = chartFeatures(engine, julianDay(2025, 6, 1));
+ * cosineSimilarity(now, target); // 1 = identical configuration
+ * ```
+ */
 export declare function chartFeatures(engine: Engine, jdUt: number, opts?: FeatureOptions): number[];
-/** Similarity between the sky at jdUt and a target feature vector. */
+/**
+ * Similarity between the sky at `jdUt` and a target feature vector — shorthand
+ * for `cosineSimilarity(chartFeatures(engine, jdUt, opts), target)`. The scoring
+ * function {@link searchConfigurations} maximizes.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jdUt Julian Day in UT.
+ * @param target A target feature vector from {@link chartFeatures}.
+ * @param opts {@link FeatureOptions} — must match those used to build `target`.
+ * @returns Cosine similarity in `[-1, 1]`.
+ */
 export declare function configurationFit(engine: Engine, jdUt: number, target: number[], opts?: FeatureOptions): number;
 export interface SearchConfigOptions extends FeatureOptions {
     start: number;
@@ -21,6 +65,24 @@ export interface SearchConfigOptions extends FeatureOptions {
     step: number;
     limit?: number;
 }
-/** Rank the instants in [start, end] by how closely the sky resembles `target`
- *  (a feature vector), best first. Realization search over the feature space. */
+/**
+ * Rank the instants in `[start, end]` by how closely the sky resembles a
+ * `target` feature vector, best first — a realization search over the feature
+ * space. Build `target` with {@link chartFeatures} (e.g. from a natal chart).
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param target A target feature vector from {@link chartFeatures}.
+ * @param opts `start`/`end` (Julian Days, UT) and `step` (days) define the
+ *   scan, `limit` caps the results, plus the {@link FeatureOptions} (`bodies`,
+ *   `weights`, `zodiac`) — which must match those used to build `target`.
+ * @returns Ranked `{ jd, score }` moments, highest similarity first.
+ * @example
+ * ```ts
+ * const natal = chartFeatures(engine, julianDay(1990, 6, 10, 14, 30));
+ * const matches = searchConfigurations(engine, natal, {
+ *   start: julianDay(2025, 1, 1), end: julianDay(2026, 1, 1), step: 1, limit: 5,
+ * });
+ * matches[0].jd; // best-matching instant
+ * ```
+ */
 export declare function searchConfigurations(engine: Engine, target: number[], opts: SearchConfigOptions): RankedMoment[];

package/dist/src/features.js

@@ -13,8 +13,15 @@ import { DEG } from "./core.js";
 import { rankMoments } from "./scan.js";
 export const DEFAULT_BODIES = ["sun", "moon", "mercury", "venus", "mars",
     "jupiter", "saturn", "uranus", "neptune", "pluto"];
-/** Flat vector [w*cos(lon), w*sin(lon), ...] for the given (longitude, weight)
- *  pairs, in order. */
+/**
+ * Build a feature vector from explicit `(longitude, weight)` pairs: each pair
+ * contributes a weighted unit-circle point `[w·cos(lon), w·sin(lon)]`. The
+ * low-level primitive behind {@link chartFeatures}; most callers want that.
+ *
+ * @param weightedLons `[longitudeDeg, weight]` pairs, in the order they should
+ *   appear in the vector.
+ * @returns A flat vector, two entries per pair.
+ */
 export function featureVector(weightedLons) {
     const out = [];
     for (const [lon, w] of weightedLons) {
@@ -23,7 +30,15 @@ export function featureVector(weightedLons) {
     }
     return out;
 }
-/** Cosine similarity of two feature vectors, in [-1, 1]. */
+/**
+ * Cosine similarity of two feature vectors, in `[-1, 1]`. For vectors from
+ * {@link chartFeatures} this is a weighted mean of `cos(Δlongitude)` per body:
+ * `1` when the configurations coincide, falling off as bodies diverge.
+ *
+ * @param a First feature vector.
+ * @param b Second feature vector (compared over the shorter length).
+ * @returns Similarity in `[-1, 1]`; `0` if either vector is all zeros.
+ */
 export function cosineSimilarity(a, b) {
     let dot = 0, na = 0, nb = 0;
     const n = Math.min(a.length, b.length);
@@ -36,7 +51,26 @@ export function cosineSimilarity(a, b) {
         return 0;
     return dot / (Math.sqrt(na) * Math.sqrt(nb));
 }
-/** Feature vector for the sky at jdUt over an ordered set of bodies. */
+/**
+ * Encode the sky at an instant as a feature vector: each body's ecliptic
+ * longitude becomes a weighted unit-circle point. The deterministic substrate
+ * for matching and searching chart configurations — compare two with
+ * {@link cosineSimilarity}, or rank a time range against one with
+ * {@link searchConfigurations}.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jdUt Julian Day in UT.
+ * @param opts `bodies` (ordered; defaults to the ten major bodies), per-body
+ *   `weights`, and `zodiac` (tropical by default).
+ * @returns A flat vector `[w·cos(lon), w·sin(lon), ...]`, two entries per body
+ *   in `bodies` order.
+ * @example
+ * ```ts
+ * const target = chartFeatures(engine, julianDay(2000, 1, 1));
+ * const now = chartFeatures(engine, julianDay(2025, 6, 1));
+ * cosineSimilarity(now, target); // 1 = identical configuration
+ * ```
+ */
 export function chartFeatures(engine, jdUt, opts = {}) {
     const bodies = opts.bodies ?? DEFAULT_BODIES;
     const zodiac = opts.zodiac ?? "tropical";
@@ -46,12 +80,40 @@ export function chartFeatures(engine, jdUt, opts = {}) {
     ]);
     return featureVector(wl);
 }
-/** Similarity between the sky at jdUt and a target feature vector. */
+/**
+ * Similarity between the sky at `jdUt` and a target feature vector — shorthand
+ * for `cosineSimilarity(chartFeatures(engine, jdUt, opts), target)`. The scoring
+ * function {@link searchConfigurations} maximizes.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param jdUt Julian Day in UT.
+ * @param target A target feature vector from {@link chartFeatures}.
+ * @param opts {@link FeatureOptions} — must match those used to build `target`.
+ * @returns Cosine similarity in `[-1, 1]`.
+ */
 export function configurationFit(engine, jdUt, target, opts = {}) {
     return cosineSimilarity(chartFeatures(engine, jdUt, opts), target);
 }
-/** Rank the instants in [start, end] by how closely the sky resembles `target`
- *  (a feature vector), best first. Realization search over the feature space. */
+/**
+ * Rank the instants in `[start, end]` by how closely the sky resembles a
+ * `target` feature vector, best first — a realization search over the feature
+ * space. Build `target` with {@link chartFeatures} (e.g. from a natal chart).
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param target A target feature vector from {@link chartFeatures}.
+ * @param opts `start`/`end` (Julian Days, UT) and `step` (days) define the
+ *   scan, `limit` caps the results, plus the {@link FeatureOptions} (`bodies`,
+ *   `weights`, `zodiac`) — which must match those used to build `target`.
+ * @returns Ranked `{ jd, score }` moments, highest similarity first.
+ * @example
+ * ```ts
+ * const natal = chartFeatures(engine, julianDay(1990, 6, 10, 14, 30));
+ * const matches = searchConfigurations(engine, natal, {
+ *   start: julianDay(2025, 1, 1), end: julianDay(2026, 1, 1), step: 1, limit: 5,
+ * });
+ * matches[0].jd; // best-matching instant
+ * ```
+ */
 export function searchConfigurations(engine, target, opts) {
     return rankMoments({ start: opts.start, end: opts.end, step: opts.step, limit: opts.limit }, (jd) => configurationFit(engine, jd, target, opts));
 }

package/dist/src/firdaria.d.ts

@@ -0,0 +1,49 @@
+/**
+ * astroengine firdaria -- the Persian/medieval system of planetary time-lord
+ * periods (firdariyyat).
+ *
+ * Life divides into nine periods totalling 75 years: the seven planets in the
+ * firdaria order, then the two lunar nodes. A day chart begins with the Sun, a
+ * night chart with the Moon; both follow the same cycle (Sun, Venus, Mercury,
+ * Moon, Saturn, Jupiter, Mars) and close with the North and South Nodes. Each
+ * planetary period splits into seven equal sub-periods led by the seven planets
+ * from that period's lord; node periods have no sub-divisions. Pure time
+ * arithmetic on the natal moment and the chart's sect. Mirrors the Python
+ * reference (astroengine/firdaria.py); the golden fixtures pin the two together.
+ */
+import { Engine } from "./chart.js";
+/** The firdaria cycle of the seven planets. */
+export declare const FIRDARIA_ORDER: readonly ["sun", "venus", "mercury", "moon", "saturn", "jupiter", "mars"];
+/** Period length in years for each of the seven planets. */
+export declare const FIRDARIA_YEARS: Record<(typeof FIRDARIA_ORDER)[number], number>;
+/** The two nodes close the sequence with no sub-periods (70 + 5 = 75 years). */
+export declare const NODE_PERIODS: ReadonlyArray<readonly [string, number]>;
+/** The nine major firdaria periods in order, as `[lord, years]` pairs. */
+export declare function firdariaSequence(day: boolean): Array<[string, number]>;
+export interface FirdariaSub {
+    lord: string;
+    start: number;
+    end: number;
+}
+export interface FirdariaPeriod {
+    lord: string;
+    years: number;
+    start: number;
+    end: number;
+    sub: FirdariaSub[];
+}
+/** The full firdaria timeline from birth. */
+export declare function firdaria(day: boolean, natalJd: number, yearLength?: number): FirdariaPeriod[];
+/** The major and sub firdar lord active at `targetJd`; both null outside the
+ *  75-year span. */
+export declare function firdariaActive(day: boolean, natalJd: number, targetJd: number, yearLength?: number): {
+    major: string | null;
+    sub: string | null;
+};
+/** The active firdar at `targetJd`, taking the chart's sect from the natal
+ *  moment and place. */
+export declare function firdariaAt(engine: Engine, natalJd: number, targetJd: number, lat: number, lonEast: number, yearLength?: number): {
+    day: boolean;
+    major: string | null;
+    sub: string | null;
+};

package/dist/src/firdaria.js

@@ -0,0 +1,62 @@
+import { TROPICAL_YEAR, isDayChart } from "./derived.js";
+/** The firdaria cycle of the seven planets. */
+export const FIRDARIA_ORDER = [
+    "sun", "venus", "mercury", "moon", "saturn", "jupiter", "mars",
+];
+/** Period length in years for each of the seven planets. */
+export const FIRDARIA_YEARS = {
+    sun: 10, venus: 8, mercury: 13, moon: 9, saturn: 11, jupiter: 12, mars: 7,
+};
+/** The two nodes close the sequence with no sub-periods (70 + 5 = 75 years). */
+export const NODE_PERIODS = [
+    ["north_node", 3], ["south_node", 2],
+];
+/** The nine major firdaria periods in order, as `[lord, years]` pairs. */
+export function firdariaSequence(day) {
+    const start = day ? 0 : FIRDARIA_ORDER.indexOf("moon");
+    const planets = [];
+    for (let i = 0; i < 7; i++) {
+        const lord = FIRDARIA_ORDER[(start + i) % 7];
+        planets.push([lord, FIRDARIA_YEARS[lord]]);
+    }
+    return [...planets, ...NODE_PERIODS.map((p) => [p[0], p[1]])];
+}
+/** The full firdaria timeline from birth. */
+export function firdaria(day, natalJd, yearLength = TROPICAL_YEAR) {
+    const out = [];
+    let t = natalJd;
+    for (const [lord, years] of firdariaSequence(day)) {
+        const span = years * yearLength;
+        const major = { lord, years, start: t, end: t + span, sub: [] };
+        const li = FIRDARIA_ORDER.indexOf(lord);
+        if (li >= 0) {
+            const subSpan = span / 7;
+            let st = t;
+            for (let k = 0; k < 7; k++) {
+                const sl = FIRDARIA_ORDER[(li + k) % 7];
+                major.sub.push({ lord: sl, start: st, end: st + subSpan });
+                st += subSpan;
+            }
+        }
+        out.push(major);
+        t += span;
+    }
+    return out;
+}
+/** The major and sub firdar lord active at `targetJd`; both null outside the
+ *  75-year span. */
+export function firdariaActive(day, natalJd, targetJd, yearLength = TROPICAL_YEAR) {
+    for (const major of firdaria(day, natalJd, yearLength)) {
+        if (major.start <= targetJd && targetJd < major.end) {
+            const sub = major.sub.find((s) => s.start <= targetJd && targetJd < s.end);
+            return { major: major.lord, sub: sub ? sub.lord : null };
+        }
+    }
+    return { major: null, sub: null };
+}
+/** The active firdar at `targetJd`, taking the chart's sect from the natal
+ *  moment and place. */
+export function firdariaAt(engine, natalJd, targetJd, lat, lonEast, yearLength = TROPICAL_YEAR) {
+    const day = isDayChart(engine, natalJd, lat, lonEast);
+    return { day, ...firdariaActive(day, natalJd, targetJd, yearLength) };
+}

package/dist/src/houses.d.ts

@@ -41,9 +41,18 @@ export declare function housesPolichPage(armc: number, phi: number, eps: number)
 /** Vehlow: equal houses with the ASC at the middle of house 1. */
 export declare function housesVehlow(armc: number, phi: number, eps: number): number[];
 /**
- * Placidus cusps via the classic iterative scheme. Semi-arc derivation:
- * for ALL four intermediate cusps RA = ARMC + offset + f*AD with
- * AD = asin(tan(phi) tan(dec)); offsets 30/60/120/150, f = 1/3,2/3,2/3,1/3.
- * Undefined above the polar circles (as Placidus itself is).
+ * Placidus house cusps via the classic iterative semi-arc scheme: for all four
+ * intermediate cusps RA = ARMC + offset + f·AD with AD = asin(tan φ · tan δ);
+ * offsets 30/60/120/150, f = 1/3, 2/3, 2/3, 1/3. Undefined above the polar
+ * circles, as Placidus itself is.
+ *
+ * Low-level: {@link Engine.chart} calls this for you when the house system is
+ * `"placidus"`, falling back to whole-sign near the poles. Inputs and outputs
+ * are in **radians**.
+ *
+ * @param armc Right ascension of the MC, in radians.
+ * @param phi Geographic latitude, in radians.
+ * @param eps Obliquity of the ecliptic, in radians.
+ * @returns The twelve cusp longitudes in radians, house 1 (Ascendant) first.
  */
 export declare function housesPlacidus(armc: number, phi: number, eps: number): number[];

package/dist/src/houses.js

@@ -257,10 +257,19 @@ export function housesVehlow(armc, phi, eps) {
     return Array.from({ length: 12 }, (_, i) => mod(asc - 15 * DEG + i * 30 * DEG, TWO_PI));
 }
 /**
- * Placidus cusps via the classic iterative scheme. Semi-arc derivation:
- * for ALL four intermediate cusps RA = ARMC + offset + f*AD with
- * AD = asin(tan(phi) tan(dec)); offsets 30/60/120/150, f = 1/3,2/3,2/3,1/3.
- * Undefined above the polar circles (as Placidus itself is).
+ * Placidus house cusps via the classic iterative semi-arc scheme: for all four
+ * intermediate cusps RA = ARMC + offset + f·AD with AD = asin(tan φ · tan δ);
+ * offsets 30/60/120/150, f = 1/3, 2/3, 2/3, 1/3. Undefined above the polar
+ * circles, as Placidus itself is.
+ *
+ * Low-level: {@link Engine.chart} calls this for you when the house system is
+ * `"placidus"`, falling back to whole-sign near the poles. Inputs and outputs
+ * are in **radians**.
+ *
+ * @param armc Right ascension of the MC, in radians.
+ * @param phi Geographic latitude, in radians.
+ * @param eps Obliquity of the ecliptic, in radians.
+ * @returns The twelve cusp longitudes in radians, house 1 (Ascendant) first.
  */
 export function housesPlacidus(armc, phi, eps) {
     const cusp = (offsetDeg, f) => {

package/dist/src/index.d.ts

@@ -15,3 +15,12 @@ export * from "./astrocartography.js";
 export * from "./ephemeris.js";
 export * from "./features.js";
 export * from "./compiler.js";
+export * from "./lots.js";
+export * from "./profections.js";
+export * from "./firdaria.js";
+export * from "./releasing.js";
+export * from "./vedic.js";
+export * from "./directions.js";
+export * from "./vargas.js";
+export * from "./yogini.js";
+export * from "./yogas.js";

package/dist/src/index.js

@@ -15,3 +15,12 @@ export * from "./astrocartography.js";
 export * from "./ephemeris.js";
 export * from "./features.js";
 export * from "./compiler.js";
+export * from "./lots.js";
+export * from "./profections.js";
+export * from "./firdaria.js";
+export * from "./releasing.js";
+export * from "./vedic.js";
+export * from "./directions.js";
+export * from "./vargas.js";
+export * from "./yogini.js";
+export * from "./yogas.js";

package/dist/src/lots.d.ts

@@ -0,0 +1,18 @@
+import { Engine, Zodiac } from "./chart.js";
+/** The seven Hermetic lots, in their conventional order. */
+export declare const HERMETIC_LOTS: readonly ["fortune", "spirit", "eros", "necessity", "courage", "victory", "nemesis"];
+export type HermeticLot = (typeof HERMETIC_LOTS)[number];
+/** Lot of Fortune: Asc + Moon - Sun by day, Asc + Sun - Moon by night. */
+export declare function lotFortune(asc: number, sun: number, moon: number, day: boolean): number;
+/** Lot of Spirit (the reverse of Fortune): Asc + Sun - Moon by day. */
+export declare function lotSpirit(asc: number, sun: number, moon: number, day: boolean): number;
+/** The seven Hermetic lots from the Ascendant, sect, and the seven planets'
+ *  longitudes (degrees). Pure arithmetic. */
+export declare function hermeticLots(asc: number, day: boolean, sun: number, moon: number, mercury: number, venus: number, mars: number, jupiter: number, saturn: number): Record<HermeticLot, number>;
+export interface ChartLots extends Record<HermeticLot, number> {
+    /** True when the Sun is above the horizon (a diurnal chart). */
+    day: boolean;
+}
+/** The seven Hermetic lots of a chart: compute the Ascendant and sect, then the
+ *  lots from the seven planets' longitudes. */
+export declare function lots(engine: Engine, jdUt: number, lat: number, lonEast: number, zodiac?: Zodiac): ChartLots;

package/dist/src/lots.js

@@ -0,0 +1,52 @@
+/**
+ * astroengine lots -- Hellenistic lots (Arabic parts), sect-aware.
+ *
+ * A lot is an arc cast from the Ascendant equal to the arc between two chart
+ * points, reversing direction between a day and a night chart. Arithmetic on
+ * apparent longitudes already checked against Swiss Ephemeris. Mirrors the
+ * Python reference (astroengine/lots.py); the golden fixtures pin the two
+ * together. Fortune and Spirit are symmetric about the Ascendant, so
+ * `(fortune + spirit) === 2 * asc` (mod 360).
+ */
+import { mod } from "./core.js";
+import { isDayChart } from "./derived.js";
+/** The seven Hermetic lots, in their conventional order. */
+export const HERMETIC_LOTS = [
+    "fortune", "spirit", "eros", "necessity", "courage", "victory", "nemesis",
+];
+/** Asc + (a - b) by day, Asc + (b - a) by night, wrapped to [0, 360). */
+function lot(asc, a, b, day) {
+    return mod(asc + (day ? a - b : b - a), 360);
+}
+/** Lot of Fortune: Asc + Moon - Sun by day, Asc + Sun - Moon by night. */
+export function lotFortune(asc, sun, moon, day) {
+    return lot(asc, moon, sun, day);
+}
+/** Lot of Spirit (the reverse of Fortune): Asc + Sun - Moon by day. */
+export function lotSpirit(asc, sun, moon, day) {
+    return lot(asc, sun, moon, day);
+}
+/** The seven Hermetic lots from the Ascendant, sect, and the seven planets'
+ *  longitudes (degrees). Pure arithmetic. */
+export function hermeticLots(asc, day, sun, moon, mercury, venus, mars, jupiter, saturn) {
+    const fortune = lotFortune(asc, sun, moon, day);
+    const spirit = lotSpirit(asc, sun, moon, day);
+    return {
+        fortune,
+        spirit,
+        eros: lot(asc, venus, spirit, day),
+        necessity: lot(asc, fortune, mercury, day),
+        courage: lot(asc, fortune, mars, day),
+        victory: lot(asc, jupiter, spirit, day),
+        nemesis: lot(asc, fortune, saturn, day),
+    };
+}
+/** The seven Hermetic lots of a chart: compute the Ascendant and sect, then the
+ *  lots from the seven planets' longitudes. */
+export function lots(engine, jdUt, lat, lonEast, zodiac = "tropical") {
+    const asc = engine.chartAt(jdUt, lat, lonEast, { zodiac }).angles.asc;
+    const day = isDayChart(engine, jdUt, lat, lonEast);
+    const lon = (b) => engine.longitude(b, jdUt, { zodiac });
+    const h = hermeticLots(asc, day, lon("sun"), lon("moon"), lon("mercury"), lon("venus"), lon("mars"), lon("jupiter"), lon("saturn"));
+    return { day, ...h };
+}

package/dist/src/pheno.d.ts

@@ -19,8 +19,22 @@ export interface Pheno {
     diameter: number;
     magnitude: number;
 }
-/** Phase angle (deg), illuminated fraction, elongation (deg), apparent
- *  diameter (deg), apparent magnitude. */
+/**
+ * Photometric and apparent-geometry quantities for a body at an instant: its
+ * phase angle, illuminated fraction, elongation from the Sun, apparent disc
+ * diameter, and apparent visual magnitude.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param body A body with known physical dimensions (Sun, Moon, the planets).
+ * @param jdUt Julian Day (UT).
+ * @returns A {@link Pheno}: `phaseAngle` (deg), `phase` (lit fraction `0`–`1`),
+ *   `elongation` (deg), `diameter` (deg), and `magnitude`.
+ * @throws Error if `body` has no photometric data.
+ * @example
+ * ```ts
+ * pheno(engine, "venus", julianDay(2025, 6, 1)).phase; // illuminated fraction
+ * ```
+ */
 export declare function pheno(engine: Engine, body: BodyId, jdUt: number): Pheno;
 /** Apparent minus mean solar time, minutes (Meeus ch. 28). */
 export declare function equationOfTime(engine: Engine, jdUt: number): number;

package/dist/src/pheno.js

@@ -66,8 +66,22 @@ function magnitude(body, a, r, dlt, jde, lonDeg, latDeg) {
             return x - 1.01;
     }
 }
-/** Phase angle (deg), illuminated fraction, elongation (deg), apparent
- *  diameter (deg), apparent magnitude. */
+/**
+ * Photometric and apparent-geometry quantities for a body at an instant: its
+ * phase angle, illuminated fraction, elongation from the Sun, apparent disc
+ * diameter, and apparent visual magnitude.
+ *
+ * @param engine The engine used to evaluate positions.
+ * @param body A body with known physical dimensions (Sun, Moon, the planets).
+ * @param jdUt Julian Day (UT).
+ * @returns A {@link Pheno}: `phaseAngle` (deg), `phase` (lit fraction `0`–`1`),
+ *   `elongation` (deg), `diameter` (deg), and `magnitude`.
+ * @throws Error if `body` has no photometric data.
+ * @example
+ * ```ts
+ * pheno(engine, "venus", julianDay(2025, 6, 1)).phase; // illuminated fraction
+ * ```
+ */
 export function pheno(engine, body, jdUt) {
     if (DIAMETER_KM[body] === undefined) {
         throw new Error(`pheno not available for '${body}'`);

package/dist/src/profections.d.ts

@@ -0,0 +1,27 @@
+import { Engine, Zodiac } from "./chart.js";
+/** Traditional (domicile) ruler of each sign, Aries..Pisces. */
+export declare const SIGN_RULERS: readonly ["mars", "venus", "mercury", "moon", "sun", "mercury", "venus", "mars", "jupiter", "saturn", "saturn", "jupiter"];
+/** Traditional (domicile) ruler of a sign index (0 = Aries). */
+export declare function signRuler(sign: number): string;
+export interface ProfectedSign {
+    sign: string;
+    sign_index: number;
+    /** 1-based whole-sign house from the natal Ascendant. */
+    house: number;
+    /** Traditional (domicile) lord of the profected sign. */
+    lord: string;
+}
+/** The whole-sign profection `steps` signs after the Ascendant sign. */
+export declare function profectedSign(ascSign: number, steps: number): ProfectedSign;
+export interface Profection {
+    age_years: number;
+    /** 1-based month within the profection year. */
+    month: number;
+    annual: ProfectedSign;
+    monthly: ProfectedSign;
+}
+/** Annual and monthly profection at `targetJd` for a natal Ascendant sign. */
+export declare function profection(ascSign: number, natalJd: number, targetJd: number, yearLength?: number): Profection;
+/** Profection from a natal chart: take the Ascendant sign from the natal chart,
+ *  then profect to `targetJd`. */
+export declare function profectionAt(engine: Engine, natalJd: number, targetJd: number, lat: number, lonEast: number, zodiac?: Zodiac, yearLength?: number): Profection;

package/dist/src/profections.js

@@ -0,0 +1,49 @@
+/**
+ * astroengine profections -- annual and monthly profections, a Hellenistic
+ * time-lord technique.
+ *
+ * The Ascendant advances one whole sign per year of life; the profected sign's
+ * traditional (domicile) ruler is the lord of the year. Within the year the
+ * monthly profection advances one further sign per 1/12 of the year. Pure
+ * arithmetic on a date difference and the natal Ascendant sign. Mirrors the
+ * Python reference (astroengine/profections.py); the golden fixtures pin the
+ * two together. Whole-sign frame: the sign N signs after the Ascendant is the
+ * (N+1)th house. The profection year is a fixed length (the tropical year by
+ * default); birthday-exact profections would key off the solar return.
+ */
+import { mod } from "./core.js";
+import { SIGNS } from "./chart.js";
+import { TROPICAL_YEAR } from "./derived.js";
+/** Traditional (domicile) ruler of each sign, Aries..Pisces. */
+export const SIGN_RULERS = [
+    "mars", "venus", "mercury", "moon", "sun", "mercury",
+    "venus", "mars", "jupiter", "saturn", "saturn", "jupiter",
+];
+/** Traditional (domicile) ruler of a sign index (0 = Aries). */
+export function signRuler(sign) {
+    return SIGN_RULERS[mod(sign, 12)];
+}
+/** The whole-sign profection `steps` signs after the Ascendant sign. */
+export function profectedSign(ascSign, steps) {
+    const sign = mod(ascSign + steps, 12);
+    return { sign: SIGNS[sign], sign_index: sign, house: mod(steps, 12) + 1, lord: signRuler(sign) };
+}
+/** Annual and monthly profection at `targetJd` for a natal Ascendant sign. */
+export function profection(ascSign, natalJd, targetJd, yearLength = TROPICAL_YEAR) {
+    const age = (targetJd - natalJd) / yearLength;
+    const years = Math.floor(age);
+    const month = Math.floor((age - years) * 12); // 0..11
+    return {
+        age_years: years,
+        month: month + 1,
+        annual: profectedSign(ascSign, years),
+        monthly: profectedSign(ascSign, years + month),
+    };
+}
+/** Profection from a natal chart: take the Ascendant sign from the natal chart,
+ *  then profect to `targetJd`. */
+export function profectionAt(engine, natalJd, targetJd, lat, lonEast, zodiac = "tropical", yearLength = TROPICAL_YEAR) {
+    const asc = engine.chartAt(natalJd, lat, lonEast, { zodiac }).angles.asc;
+    const ascSign = mod(Math.floor(asc / 30), 12);
+    return profection(ascSign, natalJd, targetJd, yearLength);
+}