caelus 0.15.0 → 0.17.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, twenty-two chart tools over stdio
+- [caelus-mcp](https://www.npmjs.com/package/caelus-mcp) — MCP server, twenty-seven chart tools over stdio

package/accuracy.json

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

package/dist/src/chart.d.ts

@@ -6,6 +6,8 @@ export type Body = (typeof BODIES)[number];
 export declare const EXTRA_BODIES: readonly ["mean_lilith", "true_lilith"];
 /** Core names keep autocomplete; any string id is accepted (data packs). */
 export type BodyId = Body | (typeof EXTRA_BODIES)[number] | (string & {});
+/** Points: excluded from aspect search by default. */
+export declare const NOT_ASPECTABLE: Set<string>;
 export declare const SIGNS: string[];
 export declare const ASPECTS: Record<string, number>;
 export declare const DEFAULT_ORBS: Record<string, number>;
@@ -25,6 +27,8 @@ export declare function element(sign: number | string): Element;
 export declare function modality(sign: number | string): Modality;
 /** 1-based quadrant (I–IV) of a 1-based house number: houses 1–3 -> 1, etc. */
 export declare function quadrant(house: number): number;
+export declare const DOMICILE: Record<string, number[]>;
+export declare const EXALTATION: Record<string, number>;
 /**
  * Essential dignities a body holds in a sign: any of `"domicile"`,
  * `"exaltation"`, `"detriment"`, `"fall"` (the last two are the signs opposite

package/dist/src/chart.js

@@ -10,7 +10,7 @@ export const BODIES = [
 /** Computable on request (not in the default chart set). */
 export const EXTRA_BODIES = ["mean_lilith", "true_lilith"];
 /** Points: excluded from aspect search by default. */
-const NOT_ASPECTABLE = new Set([
+export const NOT_ASPECTABLE = new Set([
     "mean_node", "true_node", "mean_lilith", "true_lilith",
 ]);
 export const SIGNS = [
@@ -67,11 +67,11 @@ export function quadrant(house) {
     return Math.floor(mod(house - 1, 12) / 3) + 1;
 }
 // ----------------------------------------------------------- essential dignities
-const DOMICILE = {
+export const DOMICILE = {
     sun: [4], moon: [3], mercury: [2, 5], venus: [1, 6],
     mars: [0, 7], jupiter: [8, 11], saturn: [9, 10],
 };
-const EXALTATION = {
+export const EXALTATION = {
     sun: 0, moon: 1, mercury: 5, venus: 11, mars: 9, jupiter: 3, saturn: 6,
 };
 /**

package/dist/src/dignity-score.d.ts

@@ -0,0 +1,50 @@
+export declare const PLANETS: string[];
+export declare const DIGNITY_WEIGHTS: Record<string, number>;
+/** Dorothean triplicity rulers by element (sign%4), as [day, night, participating]. */
+export declare const TRIPLICITY: string[][];
+/** Egyptian terms (Ptolemy I.21): per sign, [ruler, upper-degree] segments. */
+export declare const TERMS_EGYPTIAN: Array<Array<[string, number]>>;
+/** Faces (decans): Chaldean order from Mars at 0 Aries; floor(lon/10) selects. */
+export declare const FACE_CYCLE: string[];
+export type Sect = "day" | "night";
+export declare function termRuler(sign: number, degInSign: number, terms?: [string, number][][]): string;
+export declare function faceRuler(lon: number): string;
+/** The essential-dignity breakdown of a planet at a longitude. */
+export interface DignityScore {
+    planet: string;
+    rulership: number;
+    exaltation: number;
+    triplicity: number;
+    term: number;
+    face: number;
+    detriment: number;
+    fall: number;
+    /** Pure dignity sum (peregrine is not auto-scored). */
+    total: number;
+    /** True when none of the five dignities is held. */
+    peregrine: boolean;
+    term_ruler: string;
+    face_ruler: string;
+}
+/**
+ * The weighted essential dignities of `planet` at ecliptic longitude `lon`
+ * (degrees) in a day or night chart. Only the seven classical planets score.
+ *
+ * @param planet One of {@link PLANETS}.
+ * @param lon Ecliptic longitude in degrees.
+ * @param sect `"day"` or `"night"`, selecting the triplicity ruler.
+ * @param terms A term table; defaults to the Egyptian bounds.
+ * @returns A {@link DignityScore}.
+ */
+export declare function dignityScore(planet: string, lon: number, sect?: Sect, terms?: [string, number][][]): DignityScore;
+/**
+ * The almuten of a degree: the classical planet with the greatest positive
+ * essential dignity (rulership + exaltation + triplicity + term + face) at `lon`.
+ * Ties broken by the canonical planet order.
+ *
+ * @returns `{ planet, score }`.
+ */
+export declare function almuten(lon: number, sect?: Sect, terms?: [string, number][][]): {
+    planet: string;
+    score: number;
+};

package/dist/src/dignity-score.js

@@ -0,0 +1,122 @@
+/**
+ * Weighted essential dignities (Ptolemaic / Lilly).
+ *
+ * Extends the qualitative {@link dignities} to the five-fold essential-dignity
+ * scoring of traditional astrology, with William Lilly's classical weights
+ * (*Christian Astrology*, 1647): rulership +5, exaltation +4, triplicity +3,
+ * term +2, face +1; detriment -5, fall -4.
+ *
+ * Tables, each pinned to a named authority and selectable where they vary:
+ * triplicity by the Dorothean rulers (day / night / participating); terms by the
+ * Egyptian bounds (Ptolemy, *Tetrabiblos* I.21); faces by the Chaldean order
+ * from 0 Aries. Peregrine (none of the five dignities present) is reported as a
+ * flag, not auto-scored, so `total` is a pure dignity sum. Port of the Python
+ * reference `astroengine.dignity_score`, pinned by `dignity-golden`.
+ */
+import { mod } from "./core.js";
+import { DOMICILE, EXALTATION } from "./chart.js";
+export const PLANETS = ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn"];
+export const DIGNITY_WEIGHTS = {
+    rulership: 5, exaltation: 4, triplicity: 3, term: 2, face: 1, detriment: -5, fall: -4,
+};
+/** Dorothean triplicity rulers by element (sign%4), as [day, night, participating]. */
+export const TRIPLICITY = [
+    ["sun", "jupiter", "saturn"], // fire
+    ["venus", "moon", "mars"], // earth
+    ["saturn", "mercury", "jupiter"], // air
+    ["venus", "mars", "moon"], // water
+];
+/** Egyptian terms (Ptolemy I.21): per sign, [ruler, upper-degree] segments. */
+export const TERMS_EGYPTIAN = [
+    [["jupiter", 6], ["venus", 12], ["mercury", 20], ["mars", 25], ["saturn", 30]], // Aries
+    [["venus", 8], ["mercury", 14], ["jupiter", 22], ["saturn", 27], ["mars", 30]], // Taurus
+    [["mercury", 6], ["jupiter", 12], ["venus", 17], ["mars", 24], ["saturn", 30]], // Gemini
+    [["mars", 7], ["venus", 13], ["mercury", 19], ["jupiter", 26], ["saturn", 30]], // Cancer
+    [["jupiter", 6], ["venus", 11], ["saturn", 18], ["mercury", 24], ["mars", 30]], // Leo
+    [["mercury", 7], ["venus", 17], ["jupiter", 21], ["mars", 28], ["saturn", 30]], // Virgo
+    [["saturn", 6], ["mercury", 14], ["jupiter", 21], ["venus", 28], ["mars", 30]], // Libra
+    [["mars", 7], ["venus", 11], ["mercury", 19], ["jupiter", 24], ["saturn", 30]], // Scorpio
+    [["jupiter", 12], ["venus", 17], ["mercury", 21], ["saturn", 26], ["mars", 30]], // Sagittarius
+    [["mercury", 7], ["jupiter", 14], ["venus", 22], ["saturn", 26], ["mars", 30]], // Capricorn
+    [["mercury", 7], ["venus", 13], ["jupiter", 20], ["mars", 25], ["saturn", 30]], // Aquarius
+    [["venus", 12], ["jupiter", 16], ["mercury", 19], ["mars", 28], ["saturn", 30]], // Pisces
+];
+/** Faces (decans): Chaldean order from Mars at 0 Aries; floor(lon/10) selects. */
+export const FACE_CYCLE = ["mars", "sun", "venus", "mercury", "moon", "saturn", "jupiter"];
+export function termRuler(sign, degInSign, terms = TERMS_EGYPTIAN) {
+    for (const [ruler, upper] of terms[sign])
+        if (degInSign < upper)
+            return ruler;
+    return terms[sign][terms[sign].length - 1][0];
+}
+export function faceRuler(lon) {
+    return FACE_CYCLE[Math.floor(mod(lon, 360) / 10) % 7];
+}
+/**
+ * The weighted essential dignities of `planet` at ecliptic longitude `lon`
+ * (degrees) in a day or night chart. Only the seven classical planets score.
+ *
+ * @param planet One of {@link PLANETS}.
+ * @param lon Ecliptic longitude in degrees.
+ * @param sect `"day"` or `"night"`, selecting the triplicity ruler.
+ * @param terms A term table; defaults to the Egyptian bounds.
+ * @returns A {@link DignityScore}.
+ */
+export function dignityScore(planet, lon, sect = "day", terms = TERMS_EGYPTIAN) {
+    const L = mod(lon, 360);
+    const sign = Math.floor(L / 30) % 12;
+    const deg = L - sign * 30;
+    const held = {};
+    if (DOMICILE[planet]?.includes(sign))
+        held.rulership = DIGNITY_WEIGHTS.rulership;
+    if (EXALTATION[planet] === sign)
+        held.exaltation = DIGNITY_WEIGHTS.exaltation;
+    const trip = TRIPLICITY[sign % 4][sect === "day" ? 0 : 1];
+    if (planet === trip)
+        held.triplicity = DIGNITY_WEIGHTS.triplicity;
+    const tr = termRuler(sign, deg, terms);
+    if (planet === tr)
+        held.term = DIGNITY_WEIGHTS.term;
+    const fr = faceRuler(L);
+    if (planet === fr)
+        held.face = DIGNITY_WEIGHTS.face;
+    if (DOMICILE[planet]?.some((d) => (d + 6) % 12 === sign))
+        held.detriment = DIGNITY_WEIGHTS.detriment;
+    if (planet in EXALTATION && (EXALTATION[planet] + 6) % 12 === sign)
+        held.fall = DIGNITY_WEIGHTS.fall;
+    const positive = ["rulership", "exaltation", "triplicity", "term", "face"].some((k) => k in held);
+    return {
+        planet,
+        rulership: held.rulership ?? 0,
+        exaltation: held.exaltation ?? 0,
+        triplicity: held.triplicity ?? 0,
+        term: held.term ?? 0,
+        face: held.face ?? 0,
+        detriment: held.detriment ?? 0,
+        fall: held.fall ?? 0,
+        total: Object.values(held).reduce((a, b) => a + b, 0),
+        peregrine: !positive,
+        term_ruler: tr,
+        face_ruler: fr,
+    };
+}
+/**
+ * The almuten of a degree: the classical planet with the greatest positive
+ * essential dignity (rulership + exaltation + triplicity + term + face) at `lon`.
+ * Ties broken by the canonical planet order.
+ *
+ * @returns `{ planet, score }`.
+ */
+export function almuten(lon, sect = "day", terms = TERMS_EGYPTIAN) {
+    let best = null;
+    let bestScore = -1;
+    for (const p of PLANETS) {
+        const d = dignityScore(p, lon, sect, terms);
+        const score = d.rulership + d.exaltation + d.triplicity + d.term + d.face;
+        if (score > bestScore) {
+            bestScore = score;
+            best = p;
+        }
+    }
+    return { planet: best, score: bestScore };
+}

package/dist/src/index.d.ts

@@ -26,3 +26,7 @@ export * from "./yogini.js";
 export * from "./yogas.js";
 export * from "./ashtottari.js";
 export * from "./rajayoga.js";
+export * from "./patterns.js";
+export * from "./signature.js";
+export * from "./dignity-score.js";
+export * from "./parans.js";

package/dist/src/index.js

@@ -26,3 +26,7 @@ export * from "./yogini.js";
 export * from "./yogas.js";
 export * from "./ashtottari.js";
 export * from "./rajayoga.js";
+export * from "./patterns.js";
+export * from "./signature.js";
+export * from "./dignity-score.js";
+export * from "./parans.js";

package/dist/src/parans.d.ts

@@ -0,0 +1,55 @@
+import type { Engine } from "./chart.js";
+export declare const PARAN_ANGLES: readonly ["rise", "mtransit", "set", "itransit"];
+export declare const DEFAULT_PARAN_BODIES: string[];
+/** One co-angular pair: bodies `a` and `b` on the named angles at ~the same time. */
+export interface Paran {
+    a: string;
+    a_angle: string;
+    b: string;
+    b_angle: string;
+    /** Midpoint instant of the two angle crossings, Julian Day (UT). */
+    jd: number;
+    /** Gap between the two crossings, minutes. */
+    gap_min: number;
+}
+/**
+ * Co-angular pairs over the 24 hours from `jd` (UT) at latitude `lat`: every
+ * pair of different bodies whose angle crossings fall within `toleranceMin`
+ * minutes. Ordered by (a, b, jd), with `a` < `b` by name.
+ *
+ * @param engine The engine used to evaluate rise/set/transit times.
+ * @param jd Julian Day in UT (the 24-hour window starts here).
+ * @param lat Geographic latitude in degrees, north positive.
+ * @param bodies Bodies to consider; defaults to the seven classical planets.
+ * @param toleranceMin The paran window in minutes (default 30).
+ * @returns The co-angular pairs as {@link Paran} objects.
+ */
+export declare function parans(engine: Engine, jd: number, lat: number, bodies?: string[], toleranceMin?: number): Paran[];
+/**
+ * The four angle crossings of a fixed `star` over the day from `jd` at latitude
+ * `lat`: the meridian transits always occur; `rise`/`set` are absent when the
+ * star is circumpolar or never rises.
+ */
+export declare function starAngleTimes(engine: Engine, star: string, jd: number, lat: number): Record<string, number>;
+/** One star-to-body paran: a fixed star and a body on angles at ~the same time. */
+export interface StarParan {
+    star: string;
+    star_angle: string;
+    body: string;
+    body_angle: string;
+    jd: number;
+    gap_min: number;
+}
+/**
+ * Star-to-body parans over the day from `jd` (UT) at latitude `lat`: a fixed
+ * star and a moving body simultaneously on angles within `toleranceMin`
+ * minutes — Brady's fixed-star parans. Ordered by (star, body, jd).
+ *
+ * @param engine An engine whose data pack includes the fixed-star catalog.
+ * @param jd Julian Day in UT (the 24-hour window starts here).
+ * @param lat Geographic latitude in degrees, north positive.
+ * @param stars Catalog star names to test (see {@link Engine.starNames}).
+ * @param bodies Bodies to consider; defaults to the seven classical planets.
+ * @param toleranceMin The paran window in minutes (default 30).
+ */
+export declare function starParans(engine: Engine, jd: number, lat: number, stars: string[], bodies?: string[], toleranceMin?: number): StarParan[];

package/dist/src/parans.js

@@ -0,0 +1,143 @@
+/**
+ * Paranatellonta (parans): co-angular bodies.
+ *
+ * Two bodies are in paran on a given day at a given latitude when both are
+ * simultaneously on one of the four angles: rising, culminating (upper
+ * meridian), setting, or anti-culminating (lower meridian) — the relationship
+ * behind the fixed-star parans of Brady's tradition, computed here for the
+ * moving bodies.
+ *
+ * Pure positional astronomy over the validated rise/set/transit times, with a
+ * stated tolerance (not a hidden convention). Longitude-independent, so latitude
+ * alone is needed. Port of the Python reference `astroengine.parans`, pinned by
+ * `parans-golden`.
+ */
+import { riseSet } from "./events.js";
+import { gast } from "./houses.js";
+import { DEG, mod } from "./core.js";
+export const PARAN_ANGLES = ["rise", "mtransit", "set", "itransit"];
+export const DEFAULT_PARAN_BODIES = ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn"];
+const TWO_PI = 2 * Math.PI;
+// Local sidereal time advances one turn per sidereal day.
+const SID_RATE = 360.98564736629 * DEG;
+// Standard rise/set: the geometric horizon lifted by ~34' of refraction.
+const RISE_ALT = -0.5667 * DEG;
+/**
+ * Co-angular pairs over the 24 hours from `jd` (UT) at latitude `lat`: every
+ * pair of different bodies whose angle crossings fall within `toleranceMin`
+ * minutes. Ordered by (a, b, jd), with `a` < `b` by name.
+ *
+ * @param engine The engine used to evaluate rise/set/transit times.
+ * @param jd Julian Day in UT (the 24-hour window starts here).
+ * @param lat Geographic latitude in degrees, north positive.
+ * @param bodies Bodies to consider; defaults to the seven classical planets.
+ * @param toleranceMin The paran window in minutes (default 30).
+ * @returns The co-angular pairs as {@link Paran} objects.
+ */
+export function parans(engine, jd, lat, bodies = DEFAULT_PARAN_BODIES, toleranceMin = 30) {
+    const events = [];
+    for (const b of bodies) {
+        for (const kind of PARAN_ANGLES) {
+            const t = riseSet(engine, b, jd, lat, 0, kind);
+            if (t !== null && t < jd + 1)
+                events.push([b, kind, t]);
+        }
+    }
+    const out = [];
+    for (let i = 0; i < events.length; i++) {
+        for (let j = i + 1; j < events.length; j++) {
+            const [ab, aa, ta] = events[i];
+            const [bb, ba, tb] = events[j];
+            if (ab === bb)
+                continue;
+            const gap = Math.abs(ta - tb) * 1440;
+            if (gap > toleranceMin)
+                continue;
+            const [pa, paa, pb, pba] = ab <= bb ? [ab, aa, bb, ba] : [bb, ba, ab, aa];
+            out.push({
+                a: pa, a_angle: paa, b: pb, b_angle: pba,
+                jd: Math.round(((ta + tb) / 2) * 1e6) / 1e6,
+                gap_min: Math.round(gap * 1e4) / 1e4,
+            });
+        }
+    }
+    out.sort((x, y) => (x.a < y.a ? -1 : x.a > y.a ? 1 : x.b < y.b ? -1 : x.b > y.b ? 1 : x.jd - y.jd));
+    return out;
+}
+/** The UT instant in `[jd, jd+1)` when apparent sidereal time = `target` (rad). */
+function timeAtLst(engine, jd, target) {
+    const dlst = mod(target - gast(engine.data, jd), TWO_PI);
+    let t = jd + dlst / SID_RATE;
+    for (let i = 0; i < 2; i++) {
+        const err = mod(gast(engine.data, t) - target + Math.PI, TWO_PI) - Math.PI;
+        t -= err / SID_RATE;
+    }
+    return t;
+}
+/**
+ * The four angle crossings of a fixed `star` over the day from `jd` at latitude
+ * `lat`: the meridian transits always occur; `rise`/`set` are absent when the
+ * star is circumpolar or never rises.
+ */
+export function starAngleTimes(engine, star, jd, lat) {
+    const fs = engine.fixedStar(star, jd);
+    const alpha = mod(fs.ra * DEG, TWO_PI);
+    const delta = fs.dec * DEG;
+    const phi = lat * DEG;
+    const out = {
+        mtransit: timeAtLst(engine, jd, alpha),
+        itransit: timeAtLst(engine, jd, mod(alpha + Math.PI, TWO_PI)),
+    };
+    const denom = Math.cos(phi) * Math.cos(delta);
+    if (denom !== 0) {
+        const cosH0 = (Math.sin(RISE_ALT) - Math.sin(phi) * Math.sin(delta)) / denom;
+        if (cosH0 >= -1 && cosH0 <= 1) {
+            const h0 = Math.acos(cosH0);
+            out.rise = timeAtLst(engine, jd, mod(alpha - h0, TWO_PI));
+            out.set = timeAtLst(engine, jd, mod(alpha + h0, TWO_PI));
+        }
+    }
+    return out;
+}
+/**
+ * Star-to-body parans over the day from `jd` (UT) at latitude `lat`: a fixed
+ * star and a moving body simultaneously on angles within `toleranceMin`
+ * minutes — Brady's fixed-star parans. Ordered by (star, body, jd).
+ *
+ * @param engine An engine whose data pack includes the fixed-star catalog.
+ * @param jd Julian Day in UT (the 24-hour window starts here).
+ * @param lat Geographic latitude in degrees, north positive.
+ * @param stars Catalog star names to test (see {@link Engine.starNames}).
+ * @param bodies Bodies to consider; defaults to the seven classical planets.
+ * @param toleranceMin The paran window in minutes (default 30).
+ */
+export function starParans(engine, jd, lat, stars, bodies = DEFAULT_PARAN_BODIES, toleranceMin = 30) {
+    const bodyEvents = [];
+    for (const b of bodies) {
+        for (const kind of PARAN_ANGLES) {
+            const t = riseSet(engine, b, jd, lat, 0, kind);
+            if (t !== null && t < jd + 1)
+                bodyEvents.push([b, kind, t]);
+        }
+    }
+    const out = [];
+    for (const s of stars) {
+        const at = starAngleTimes(engine, s, jd, lat);
+        for (const [sa, ts] of Object.entries(at)) {
+            if (!(ts >= jd && ts < jd + 1))
+                continue;
+            for (const [b, ba, tb] of bodyEvents) {
+                const gap = Math.abs(ts - tb) * 1440;
+                if (gap <= toleranceMin) {
+                    out.push({
+                        star: s, star_angle: sa, body: b, body_angle: ba,
+                        jd: Math.round(((ts + tb) / 2) * 1e6) / 1e6,
+                        gap_min: Math.round(gap * 1e4) / 1e4,
+                    });
+                }
+            }
+        }
+    }
+    out.sort((x, y) => (x.star < y.star ? -1 : x.star > y.star ? 1 : x.body < y.body ? -1 : x.body > y.body ? 1 : x.jd - y.jd));
+    return out;
+}

package/dist/src/patterns.d.ts

@@ -0,0 +1,52 @@
+import type { Chart } from "./chart.js";
+/** Pattern aspects, including the quincunx the default Ptolemaic set omits. */
+export declare const PATTERN_ANGLES: Record<string, number>;
+/** Default orbs: {@link DEFAULT_ORBS} for the five Ptolemaic aspects, plus a
+ *  tight quincunx. Override via {@link PatternOptions.orbs}. */
+export declare const PATTERN_ORBS: Record<string, number>;
+/** One configuration found in a chart. */
+export interface ChartPattern {
+    /** Configuration kind, e.g. `"t_square"` or `"grand_trine"`. */
+    kind: string;
+    /** Participating body ids, sorted. */
+    bodies: string[];
+    /** Focal body for a T-square or yod (the squared / quincunx apex). */
+    apex?: string;
+    /** Sign for a `stellium_sign`. */
+    sign?: string;
+    /** House for a `stellium_house`. */
+    house?: number;
+    /** Worst defining-aspect orb in degrees; `0` for stelliums. */
+    orb: number;
+}
+/** A body's longitude (and house, for stelliums) for {@link detectPatternsIn}. */
+export interface PatternBody {
+    lon: number;
+    house?: number | null;
+}
+export interface PatternOptions {
+    /** Per-aspect orb overrides (degrees), keyed by aspect name. */
+    orbs?: Record<string, number>;
+    /** Body ids to consider; defaults to the aspectable bodies present. */
+    bodies?: string[];
+}
+/**
+ * The configurations present among a body map. Lower-level form of
+ * {@link detectPatterns}: `bodies` maps a body id to `{ lon, house? }`.
+ */
+export declare function detectPatternsIn(bodies: Record<string, PatternBody>, opts?: PatternOptions): ChartPattern[];
+/**
+ * The aspect configurations present in a {@link Chart}: T-squares, grand trines,
+ * grand crosses, yods, kites, mystic rectangles, and stelliums by sign and by
+ * house. Bodies outside their fitted range (absent from the chart) are skipped.
+ *
+ * @param chart A {@link Chart} from {@link Engine.chart} / {@link Engine.chartAt}.
+ * @param opts Orb overrides and an optional explicit body set.
+ * @returns The configurations, most-complex first, each a {@link ChartPattern}.
+ * @example
+ * ```ts
+ * const chart = engine.chart(1990, 6, 10, 14, 30, 0, 27.95, -82.46, "placidus");
+ * detectPatterns(chart); // [{ kind: "mystic_rectangle", bodies: [...], orb: 2.54 }, ...]
+ * ```
+ */
+export declare function detectPatterns(chart: Chart, opts?: PatternOptions): ChartPattern[];

package/dist/src/patterns.js

@@ -0,0 +1,224 @@
+/**
+ * Classical aspect configurations as first-class objects.
+ *
+ * Pure geometry over a chart's body longitudes (and houses, for stelliums); no
+ * interpretation. Each configuration is judged from pairwise angular separations
+ * against an explicit, overridable orb policy: the engine's {@link DEFAULT_ORBS}
+ * for the Ptolemaic aspects, plus a quincunx (150°) for yods. The default body
+ * set is the aspectable bodies (planets and Chiron; nodes and Lilith excluded).
+ *
+ * Reported patterns are maximal: a grand cross suppresses the two T-squares it
+ * contains and a kite suppresses its grand trine. Port of the Python reference
+ * `astroengine.patterns`, pinned by `patterns-golden`.
+ */
+import { mod } from "./core.js";
+import { SIGNS, NOT_ASPECTABLE } from "./chart.js";
+/** Pattern aspects, including the quincunx the default Ptolemaic set omits. */
+export const PATTERN_ANGLES = {
+    conjunction: 0, sextile: 60, square: 90, trine: 120, quincunx: 150, opposition: 180,
+};
+/** Default orbs: {@link DEFAULT_ORBS} for the five Ptolemaic aspects, plus a
+ *  tight quincunx. Override via {@link PatternOptions.orbs}. */
+export const PATTERN_ORBS = {
+    conjunction: 8, sextile: 4, square: 7, trine: 7, quincunx: 3, opposition: 8,
+};
+const KIND_ORDER = [
+    "grand_cross", "mystic_rectangle", "kite", "t_square", "grand_trine",
+    "yod", "stellium_sign", "stellium_house",
+];
+const separation = (la, lb) => Math.abs(mod(la - lb + 180, 360) - 180);
+/** The single aspect a pair forms (orbs do not overlap), as `[name, orb]`, or null. */
+function relation(la, lb, orbs) {
+    const sep = separation(la, lb);
+    for (const name of Object.keys(PATTERN_ANGLES)) {
+        const orb = Math.abs(sep - PATTERN_ANGLES[name]);
+        if (orb <= orbs[name])
+            return [name, orb];
+    }
+    return null;
+}
+function cmpBodies(a, b) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++)
+        if (a[i] !== b[i])
+            return a[i] < b[i] ? -1 : 1;
+    return a.length - b.length;
+}
+/**
+ * The configurations present among a body map. Lower-level form of
+ * {@link detectPatterns}: `bodies` maps a body id to `{ lon, house? }`.
+ */
+export function detectPatternsIn(bodies, opts = {}) {
+    const orbs = opts.orbs ?? PATTERN_ORBS;
+    const names = (opts.bodies ?? Object.keys(bodies).filter((b) => !NOT_ASPECTABLE.has(b)))
+        .filter((b) => b in bodies);
+    const lon = {};
+    for (const b of names)
+        lon[b] = mod(bodies[b].lon, 360);
+    const key = (a, b) => (a < b ? `${a}|${b}` : `${b}|${a}`);
+    const rel = new Map();
+    for (let i = 0; i < names.length; i++) {
+        for (let j = i + 1; j < names.length; j++) {
+            const r = relation(lon[names[i]], lon[names[j]], orbs);
+            if (r)
+                rel.set(key(names[i], names[j]), r);
+        }
+    }
+    const asp = (a, b) => rel.get(key(a, b)) ?? null;
+    const isAspect = (a, b, kind) => {
+        const r = asp(a, b);
+        return r !== null && r[0] === kind;
+    };
+    const out = [];
+    // Grand trines (3-body) and grand crosses / mystic rectangles (4-body).
+    const grandTrines = [];
+    for (let i = 0; i < names.length; i++) {
+        for (let j = i + 1; j < names.length; j++) {
+            for (let k = j + 1; k < names.length; k++) {
+                const [a, b, c] = [names[i], names[j], names[k]];
+                if (isAspect(a, b, "trine") && isAspect(b, c, "trine") && isAspect(a, c, "trine")) {
+                    const orb = Math.max(asp(a, b)[1], asp(b, c)[1], asp(a, c)[1]);
+                    grandTrines.push({ kind: "grand_trine", bodies: [a, b, c].sort(), orb });
+                }
+            }
+        }
+    }
+    const grandCrosses = [];
+    const mysticRectangles = [];
+    for (let i = 0; i < names.length; i++) {
+        for (let j = i + 1; j < names.length; j++) {
+            for (let k = j + 1; k < names.length; k++) {
+                for (let l = k + 1; l < names.length; l++) {
+                    const quad = [names[i], names[j], names[k], names[l]];
+                    const pairs = [
+                        [quad[0], quad[1]], [quad[0], quad[2]], [quad[0], quad[3]],
+                        [quad[1], quad[2]], [quad[1], quad[3]], [quad[2], quad[3]],
+                    ];
+                    const kinds = pairs.map(([a, b]) => asp(a, b));
+                    if (kinds.some((r) => r === null))
+                        continue;
+                    const counts = {};
+                    let worst = 0;
+                    for (const r of kinds) {
+                        counts[r[0]] = (counts[r[0]] ?? 0) + 1;
+                        if (r[1] > worst)
+                            worst = r[1];
+                    }
+                    if (counts.opposition === 2 && counts.square === 4) {
+                        grandCrosses.push({ kind: "grand_cross", bodies: [...quad].sort(), orb: worst });
+                    }
+                    else if (counts.opposition === 2 && counts.trine === 2 && counts.sextile === 2) {
+                        mysticRectangles.push({ kind: "mystic_rectangle", bodies: [...quad].sort(), orb: worst });
+                    }
+                }
+            }
+        }
+    }
+    // Kite: a grand trine plus a fourth body opposite one member.
+    const kites = [];
+    for (const gt of grandTrines) {
+        const tri = gt.bodies;
+        for (const d of names) {
+            if (tri.includes(d))
+                continue;
+            for (const apex of tri) {
+                const others = tri.filter((x) => x !== apex);
+                if (isAspect(d, apex, "opposition")
+                    && isAspect(d, others[0], "sextile")
+                    && isAspect(d, others[1], "sextile")) {
+                    const orb = Math.max(gt.orb, asp(d, apex)[1], asp(d, others[0])[1], asp(d, others[1])[1]);
+                    kites.push({ kind: "kite", bodies: [...tri, d].sort(), apex, orb });
+                }
+            }
+        }
+    }
+    // T-square: an opposition whose two ends both square a common apex.
+    const tSquares = [];
+    for (let i = 0; i < names.length; i++) {
+        for (let j = i + 1; j < names.length; j++) {
+            const [a, b] = [names[i], names[j]];
+            if (!isAspect(a, b, "opposition"))
+                continue;
+            for (const apex of names) {
+                if (apex === a || apex === b)
+                    continue;
+                if (isAspect(apex, a, "square") && isAspect(apex, b, "square")) {
+                    const orb = Math.max(asp(a, b)[1], asp(apex, a)[1], asp(apex, b)[1]);
+                    tSquares.push({ kind: "t_square", bodies: [a, b, apex].sort(), apex, orb });
+                }
+            }
+        }
+    }
+    // Yod: a sextile whose two ends both quincunx a common apex.
+    const yods = [];
+    for (let i = 0; i < names.length; i++) {
+        for (let j = i + 1; j < names.length; j++) {
+            const [a, b] = [names[i], names[j]];
+            if (!isAspect(a, b, "sextile"))
+                continue;
+            for (const apex of names) {
+                if (apex === a || apex === b)
+                    continue;
+                if (isAspect(apex, a, "quincunx") && isAspect(apex, b, "quincunx")) {
+                    const orb = Math.max(asp(a, b)[1], asp(apex, a)[1], asp(apex, b)[1]);
+                    yods.push({ kind: "yod", bodies: [a, b, apex].sort(), apex, orb });
+                }
+            }
+        }
+    }
+    // Suppress sub-patterns contained in a larger reported one.
+    const subset = (small, big) => small.every((x) => big.includes(x));
+    const keptTSquares = tSquares.filter((t) => !grandCrosses.some((g) => subset(t.bodies, g.bodies)));
+    const keptTrines = grandTrines.filter((g) => !kites.some((k) => subset(g.bodies, k.bodies)));
+    out.push(...grandCrosses, ...mysticRectangles, ...kites, ...keptTSquares, ...keptTrines, ...yods);
+    // Stelliums by sign and by house: three or more bodies sharing one.
+    const bySign = {};
+    for (const b of names) {
+        const s = Math.floor(lon[b] / 30) % 12;
+        (bySign[s] ??= []).push(b);
+    }
+    for (const s of Object.keys(bySign)) {
+        const members = bySign[Number(s)];
+        if (members.length >= 3) {
+            out.push({ kind: "stellium_sign", bodies: [...members].sort(), sign: SIGNS[Number(s)], orb: 0 });
+        }
+    }
+    const byHouse = {};
+    for (const b of names) {
+        const h = bodies[b].house;
+        if (h != null)
+            (byHouse[h] ??= []).push(b);
+    }
+    for (const h of Object.keys(byHouse)) {
+        const members = byHouse[Number(h)];
+        if (members.length >= 3) {
+            out.push({ kind: "stellium_house", bodies: [...members].sort(), house: Number(h), orb: 0 });
+        }
+    }
+    out.sort((a, b) => KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind) || cmpBodies(a.bodies, b.bodies));
+    for (const p of out)
+        p.orb = Math.round(p.orb * 1e4) / 1e4;
+    return out;
+}
+/**
+ * The aspect configurations present in a {@link Chart}: T-squares, grand trines,
+ * grand crosses, yods, kites, mystic rectangles, and stelliums by sign and by
+ * house. Bodies outside their fitted range (absent from the chart) are skipped.
+ *
+ * @param chart A {@link Chart} from {@link Engine.chart} / {@link Engine.chartAt}.
+ * @param opts Orb overrides and an optional explicit body set.
+ * @returns The configurations, most-complex first, each a {@link ChartPattern}.
+ * @example
+ * ```ts
+ * const chart = engine.chart(1990, 6, 10, 14, 30, 0, 27.95, -82.46, "placidus");
+ * detectPatterns(chart); // [{ kind: "mystic_rectangle", bodies: [...], orb: 2.54 }, ...]
+ * ```
+ */
+export function detectPatterns(chart, opts = {}) {
+    const bodies = {};
+    for (const [name, p] of Object.entries(chart.bodies)) {
+        if (p)
+            bodies[name] = { lon: p.lon, house: p.house };
+    }
+    return detectPatternsIn(bodies, opts);
+}

package/dist/src/signature.d.ts

@@ -0,0 +1,58 @@
+import type { Chart } from "./chart.js";
+export declare const ELEMENTS: readonly ["fire", "earth", "air", "water"];
+export declare const MODALITIES: readonly ["cardinal", "fixed", "mutable"];
+export interface ChartSignature {
+    /** Bodies per element (fire/earth/air/water). */
+    elements: Record<string, number>;
+    /** Bodies per modality (cardinal/fixed/mutable). */
+    modalities: Record<string, number>;
+    /** Bodies per angularity (angular/succedent/cadent), house-based. */
+    angularity: Record<string, number>;
+    /** Bodies per quadrant ("1"-"4"), house-based. */
+    quadrants: Record<string, number>;
+    /** Bodies above/below the horizon and east/west, house-based. */
+    hemispheres: Record<string, number>;
+    /** Argmax of the distributions; `sign` is the most-occupied sign (>=2) or null. */
+    dominant: {
+        element: string;
+        modality: string;
+        sign: string | null;
+    };
+    /** Classical ruler of the Ascendant's sign, or null when no Ascendant given. */
+    ruler: string | null;
+    /** The bodies counted, sorted. */
+    bodies: string[];
+}
+/** A body's longitude (and house) for {@link chartSignatureOf}. */
+export interface SignatureBody {
+    lon: number;
+    house?: number | null;
+}
+export interface SignatureOptions {
+    /** Ascendant sign index 0-11; yields the classical chart ruler. */
+    ascSign?: number | null;
+    /** Body ids to count; defaults to the aspectable bodies present. */
+    bodies?: string[];
+}
+/**
+ * Structural counts for a body map. Lower-level form of {@link chartSignature}:
+ * `bodies` maps a body id to `{ lon, house? }`.
+ */
+export declare function chartSignatureOf(bodies: Record<string, SignatureBody>, opts?: SignatureOptions): ChartSignature;
+/**
+ * The structural signature of a {@link Chart}: element / modality / angularity /
+ * quadrant / hemisphere distributions over its bodies, the dominant element,
+ * modality, and most-occupied sign, and the classical chart ruler. Counts only,
+ * no interpretation. Bodies absent from the chart (outside their fitted range)
+ * are skipped.
+ *
+ * @param chart A {@link Chart} from {@link Engine.chart} / {@link Engine.chartAt}.
+ * @param opts An explicit body set, or an Ascendant-sign override.
+ * @returns A {@link ChartSignature}.
+ * @example
+ * ```ts
+ * const chart = engine.chart(1990, 6, 10, 14, 30, 0, 27.95, -82.46, "placidus");
+ * chartSignature(chart).dominant; // { element: "earth", modality: "cardinal", sign: "Capricorn" }
+ * ```
+ */
+export declare function chartSignature(chart: Chart, opts?: SignatureOptions): ChartSignature;

package/dist/src/signature.js

@@ -0,0 +1,106 @@
+/**
+ * A chart's structural signature, as plain counts.
+ *
+ * Element / modality distributions (from each body's sign), angularity /
+ * quadrant / hemisphere distributions (from its house), the dominant element,
+ * modality, and most-occupied sign (argmax of the counts), and the classical
+ * chart ruler (the domicile ruler of the Ascendant's sign). No interpretation,
+ * no "flavour" labels.
+ *
+ * The only convention is which bodies are counted and that each counts once: the
+ * default is the aspectable bodies (planets and Chiron; nodes and Lilith
+ * excluded), each weight 1. Weighted "dominance" schemes are deliberately not the
+ * default. Port of the Python reference `astroengine.signature`, pinned by
+ * `signature-golden`.
+ */
+import { mod } from "./core.js";
+import { SIGNS, NOT_ASPECTABLE } from "./chart.js";
+export const ELEMENTS = ["fire", "earth", "air", "water"];
+export const MODALITIES = ["cardinal", "fixed", "mutable"];
+const ANGULARITY = ["angular", "succedent", "cadent"];
+/** Classical (domicile) ruler by sign index 0-11, matching the engine's dignities. */
+const RULERS = ["mars", "venus", "mercury", "moon", "sun", "mercury",
+    "venus", "mars", "jupiter", "saturn", "saturn", "jupiter"];
+function argmax(counts, order) {
+    let best = order[0];
+    let bestV = -1;
+    for (const k of order)
+        if (counts[k] > bestV) {
+            bestV = counts[k];
+            best = k;
+        }
+    return best;
+}
+/**
+ * Structural counts for a body map. Lower-level form of {@link chartSignature}:
+ * `bodies` maps a body id to `{ lon, house? }`.
+ */
+export function chartSignatureOf(bodies, opts = {}) {
+    const names = (opts.bodies ?? Object.keys(bodies).filter((b) => !NOT_ASPECTABLE.has(b)))
+        .filter((b) => b in bodies);
+    const elements = { fire: 0, earth: 0, air: 0, water: 0 };
+    const modalities = { cardinal: 0, fixed: 0, mutable: 0 };
+    const angularity = { angular: 0, succedent: 0, cadent: 0 };
+    const quadrants = { 1: 0, 2: 0, 3: 0, 4: 0 };
+    const hemispheres = { above: 0, below: 0, eastern: 0, western: 0 };
+    const signCounts = {};
+    for (const b of names) {
+        const sign = Math.floor(mod(bodies[b].lon, 360) / 30) % 12;
+        elements[ELEMENTS[sign % 4]]++;
+        modalities[MODALITIES[sign % 3]]++;
+        signCounts[sign] = (signCounts[sign] ?? 0) + 1;
+        const h = bodies[b].house;
+        if (h != null) {
+            angularity[ANGULARITY[(h - 1) % 3]]++;
+            quadrants[String(Math.floor((h - 1) / 3) + 1)]++;
+            hemispheres[h >= 7 ? "above" : "below"]++;
+            hemispheres[[10, 11, 12, 1, 2, 3].includes(h) ? "eastern" : "western"]++;
+        }
+    }
+    let domSign = null;
+    let best = 1;
+    for (const s of Object.keys(signCounts).map(Number).sort((a, b) => a - b)) {
+        if (signCounts[s] > best) {
+            best = signCounts[s];
+            domSign = s;
+        }
+    }
+    return {
+        elements,
+        modalities,
+        angularity,
+        quadrants,
+        hemispheres,
+        dominant: {
+            element: argmax(elements, ELEMENTS),
+            modality: argmax(modalities, MODALITIES),
+            sign: domSign !== null ? SIGNS[domSign] : null,
+        },
+        ruler: opts.ascSign != null ? RULERS[opts.ascSign] : null,
+        bodies: [...names].sort(),
+    };
+}
+/**
+ * The structural signature of a {@link Chart}: element / modality / angularity /
+ * quadrant / hemisphere distributions over its bodies, the dominant element,
+ * modality, and most-occupied sign, and the classical chart ruler. Counts only,
+ * no interpretation. Bodies absent from the chart (outside their fitted range)
+ * are skipped.
+ *
+ * @param chart A {@link Chart} from {@link Engine.chart} / {@link Engine.chartAt}.
+ * @param opts An explicit body set, or an Ascendant-sign override.
+ * @returns A {@link ChartSignature}.
+ * @example
+ * ```ts
+ * const chart = engine.chart(1990, 6, 10, 14, 30, 0, 27.95, -82.46, "placidus");
+ * chartSignature(chart).dominant; // { element: "earth", modality: "cardinal", sign: "Capricorn" }
+ * ```
+ */
+export function chartSignature(chart, opts = {}) {
+    const bodies = {};
+    for (const [name, p] of Object.entries(chart.bodies))
+        if (p)
+            bodies[name] = { lon: p.lon, house: p.house };
+    const ascSign = opts.ascSign ?? Math.floor(mod(chart.angles.asc, 360) / 30) % 12;
+    return chartSignatureOf(bodies, { ...opts, ascSign });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caelus",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Astrological ephemeris engine. MIT, no AGPL, no ephemeris files. Checked against Swiss Ephemeris.",
   "type": "module",
   "main": "dist/src/index.js",