caelus 0.14.0 → 0.16.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,10 +6,45 @@ 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>;
 export type HouseSystem = "placidus" | "porphyry" | "equal" | "whole_sign" | "koch" | "regiomontanus" | "campanus" | "alcabitius" | "morinus" | "meridian" | "polich_page" | "vehlow";
+/** The canonical house-system ids, in a stable order (also used for error text). */
+export declare const HOUSE_SYSTEMS: readonly HouseSystem[];
+/** Resolve a forgiving house-system string (any case, spaces or hyphens, or a
+ *  known alias) to a canonical {@link HouseSystem}, or throw listing the valid
+ *  ids. Lets MCP, share links, and hand-written calls pass "whole sign",
+ *  "Whole_Sign", "whole", etc. without tripping the strict union. */
+export declare function normalizeHouseSystem(raw: string): HouseSystem;
+export type Element = "fire" | "earth" | "air" | "water";
+export type Modality = "cardinal" | "fixed" | "mutable";
+/** Triplicity (element) of a sign: `"fire"`, `"earth"`, `"air"`, or `"water"`. */
+export declare function element(sign: number | string): Element;
+/** Quadruplicity (modality) of a sign: `"cardinal"`, `"fixed"`, or `"mutable"`. */
+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
+ * domicile and exaltation). Empty when the body is peregrine there or has no
+ * classical rulership (the outer planets, Chiron, the nodes).
+ *
+ * @param body Body id, e.g. `"mars"`.
+ * @param sign A sign index `0`–`11` (Aries = 0) or its name, e.g. `"Aries"`.
+ * @returns The dignities held, in the order above; empty if none.
+ * @example
+ * ```ts
+ * dignities("mars", "Aries"); // ["domicile"]
+ * dignities("sun", "Libra");  // ["fall"]
+ * ```
+ */
+export declare function dignities(body: string, sign: number | string): string[];
 export type Ayanamsa = keyof typeof AYANAMSA_J2000 & string;
 export type Zodiac = "tropical" | `sidereal:${string}`;
 export interface Observer {
@@ -58,6 +93,33 @@ export interface Position {
     /** Equatorial declination, true equinox of date, degrees. */
     dec: number;
 }
+/** A {@link Position} enriched with chart-relative placement, as returned per
+ *  body by {@link Engine.chart} and {@link Engine.chartAt}. */
+export interface ChartBody extends Position {
+    /** 1-based house the body falls in, by the chart's cusps (1–12). */
+    house: number;
+    /** Essential dignities held in the body's sign (see {@link dignities});
+     *  empty when peregrine or for bodies without classical rulerships. */
+    dignities: string[];
+}
+/** Default chart bodies that are Chebyshev-packed, so they can fall outside
+ *  their fitted range (and be omitted from a chart). Opt-in asteroids are
+ *  packed too, but arrive as arbitrary ids through the string index. */
+export type PackedBody = "chiron";
+/** Bodies guaranteed to be in every chart: the analytic Sun–Pluto and the lunar
+ *  nodes, which resolve across all supported epochs. (Chiron is Chebyshev-packed
+ *  and can fall outside its fitted range, so it is *not* guaranteed.) */
+export type AlwaysBody = Exclude<Body, PackedBody>;
+/**
+ * A chart's bodies, keyed by id. The analytic core ({@link AlwaysBody}) is
+ * always present and needs no presence check. {@link PackedBody} bodies (Chiron)
+ * and any opt-in extras requested via {@link ChartOptions.bodies} may be absent
+ * when the instant is outside their fitted range (see {@link Chart.unavailable}),
+ * so those accesses are typed `ChartBody | undefined` and must be guarded.
+ */
+export type ChartBodies = Record<AlwaysBody, ChartBody> & Partial<Record<PackedBody, ChartBody>> & {
+    [id: string]: ChartBody | undefined;
+};
 /** One aspect between two bodies in a {@link Chart}. */
 export interface Aspect {
     /** First body id. */
@@ -81,8 +143,14 @@ export interface Chart {
     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>;
+    /** Apparent position per body, enriched with house and dignities, keyed by
+     *  body id. See {@link ChartBody}. */
+    bodies: ChartBodies;
+    /** Body ids that were requested but omitted because the instant falls outside
+     *  their fitted range (e.g. Chiron and other Chebyshev-packed bodies before
+     *  ~1850 or after ~2150). Empty for the usual modern dates. The analytic
+     *  bodies (Sun through Pluto and the nodes) are always present. */
+    unavailable: string[];
     /** Chart angles in degrees: Ascendant, Midheaven, Vertex, East Point. */
     angles: {
         asc: number;
@@ -235,10 +303,10 @@ export declare class Engine {
      * 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).
+     * time, and not a Julian Day. Passing a JD in `y` builds an absurd instant 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`.
@@ -254,9 +322,12 @@ export declare class Engine {
      *   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.
+     *   whole-sign above the polar circles). A body outside its fitted range
+     *   (e.g. Chiron before ~1850) is omitted from `bodies` and listed in
+     *   `unavailable` rather than failing the whole chart.
+     * @throws RangeError only if the instant itself is absurd — far outside any
+     *   supported epoch — which almost always means a Julian Day was passed where
+     *   calendar fields belong.
      * @example
      * ```ts
      * // 1990-06-10 14:30 UT at Tampa, FL (27.95° N, 82.46° W), Placidus houses

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 = [
@@ -23,7 +23,92 @@ export const ASPECTS = {
 export const DEFAULT_ORBS = {
     conjunction: 8, sextile: 4, square: 7, trine: 7, opposition: 8,
 };
+/** The canonical house-system ids, in a stable order (also used for error text). */
+export const HOUSE_SYSTEMS = [
+    "placidus", "porphyry", "equal", "whole_sign", "koch", "regiomontanus",
+    "campanus", "alcabitius", "morinus", "meridian", "polich_page", "vehlow",
+];
+// Short or alternate names that normalization (lowercase + space/hyphen -> "_")
+// can't reach on its own. "whole sign", "Polich Page", etc. already normalize to
+// their canonical id, so only genuinely different spellings live here.
+const HOUSE_ALIASES = {
+    whole: "whole_sign", signs: "whole_sign", wholesign: "whole_sign",
+    equal_house: "equal", porphyrius: "porphyry", placidean: "placidus",
+};
+/** Resolve a forgiving house-system string (any case, spaces or hyphens, or a
+ *  known alias) to a canonical {@link HouseSystem}, or throw listing the valid
+ *  ids. Lets MCP, share links, and hand-written calls pass "whole sign",
+ *  "Whole_Sign", "whole", etc. without tripping the strict union. */
+export function normalizeHouseSystem(raw) {
+    const key = raw.trim().toLowerCase().replace(/[\s-]+/g, "_");
+    if (HOUSE_SYSTEMS.includes(key))
+        return key;
+    const alias = HOUSE_ALIASES[key];
+    if (alias)
+        return alias;
+    throw new Error(`unknown house system '${raw}' (valid: ${HOUSE_SYSTEMS.join(", ")})`);
+}
+const ELEMENTS = ["fire", "earth", "air", "water"];
+const MODALITIES = ["cardinal", "fixed", "mutable"];
+/** Sign index `0`–`11` (Aries = 0) from an index or a sign name (`"Aries"`). */
+function signIndex(sign) {
+    return typeof sign === "number" ? mod(Math.floor(sign), 12) : SIGNS.indexOf(sign);
+}
+/** Triplicity (element) of a sign: `"fire"`, `"earth"`, `"air"`, or `"water"`. */
+export function element(sign) {
+    return ELEMENTS[mod(signIndex(sign), 4)];
+}
+/** Quadruplicity (modality) of a sign: `"cardinal"`, `"fixed"`, or `"mutable"`. */
+export function modality(sign) {
+    return MODALITIES[mod(signIndex(sign), 3)];
+}
+/** 1-based quadrant (I–IV) of a 1-based house number: houses 1–3 -> 1, etc. */
+export function quadrant(house) {
+    return Math.floor(mod(house - 1, 12) / 3) + 1;
+}
+// ----------------------------------------------------------- essential dignities
+export const DOMICILE = {
+    sun: [4], moon: [3], mercury: [2, 5], venus: [1, 6],
+    mars: [0, 7], jupiter: [8, 11], saturn: [9, 10],
+};
+export const EXALTATION = {
+    sun: 0, moon: 1, mercury: 5, venus: 11, mars: 9, jupiter: 3, saturn: 6,
+};
+/**
+ * Essential dignities a body holds in a sign: any of `"domicile"`,
+ * `"exaltation"`, `"detriment"`, `"fall"` (the last two are the signs opposite
+ * domicile and exaltation). Empty when the body is peregrine there or has no
+ * classical rulership (the outer planets, Chiron, the nodes).
+ *
+ * @param body Body id, e.g. `"mars"`.
+ * @param sign A sign index `0`–`11` (Aries = 0) or its name, e.g. `"Aries"`.
+ * @returns The dignities held, in the order above; empty if none.
+ * @example
+ * ```ts
+ * dignities("mars", "Aries"); // ["domicile"]
+ * dignities("sun", "Libra");  // ["fall"]
+ * ```
+ */
+export function dignities(body, sign) {
+    const idx = signIndex(sign);
+    const dom = DOMICILE[body] ?? [];
+    const out = [];
+    if (dom.includes(idx))
+        out.push("domicile");
+    if (EXALTATION[body] === idx)
+        out.push("exaltation");
+    if (dom.map((d) => mod(d + 6, 12)).includes(idx))
+        out.push("detriment");
+    if (body in EXALTATION && mod(EXALTATION[body] + 6, 12) === idx)
+        out.push("fall");
+    return out;
+}
 const KM_PER_AU = 149597870.7;
+// A generous window for the analytic models. Every real chart, however
+// historical, sits well inside it; an instant far outside almost always means a
+// Julian Day was passed to chart() where calendar fields belong.
+const JD_SANE_MIN = -2_000_000; // ~ 10000 BC
+const JD_SANE_MAX = 9_000_000; // ~ 20000 AD
 function parseZodiac(zodiac) {
     if (zodiac === "tropical")
         return null;
@@ -339,10 +424,10 @@ export class Engine {
      * 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).
+     * time, and not a Julian Day. Passing a JD in `y` builds an absurd instant 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`.
@@ -358,9 +443,12 @@ export class Engine {
      *   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.
+     *   whole-sign above the polar circles). A body outside its fitted range
+     *   (e.g. Chiron before ~1850) is omitted from `bodies` and listed in
+     *   `unavailable` rather than failing the whole chart.
+     * @throws RangeError only if the instant itself is absurd — far outside any
+     *   supported epoch — which almost always means a Julian Day was passed where
+     *   calendar fields belong.
      * @example
      * ```ts
      * // 1990-06-10 14:30 UT at Tampa, FL (27.95° N, 82.46° W), Placidus houses
@@ -393,8 +481,12 @@ export class Engine {
      * @see {@link Engine.chart} for the calendar-field entry point.
      */
     chartAt(jdUt, lat, lonEast, opts = "placidus") {
+        if (!Number.isFinite(jdUt) || jdUt < JD_SANE_MIN || jdUt > JD_SANE_MAX) {
+            throw new RangeError(`chart instant (jd ${jdUt}) is far outside the supported range; if you ` +
+                `meant a calendar date, pass year/month/day to chart() rather than a Julian Day.`);
+        }
         const o = typeof opts === "string" ? { houseSystem: opts } : opts;
-        const houseSystem = o.houseSystem ?? "placidus";
+        const houseSystem = normalizeHouseSystem(o.houseSystem ?? "placidus");
         const zodiac = o.zodiac ?? "tropical";
         const mode = parseZodiac(zodiac);
         const calc = {
@@ -406,8 +498,22 @@ export class Engine {
             ...BODIES, ...(o.bodies ?? []).filter((b) => !BODIES.includes(b)),
         ];
         const bodies = {};
-        for (const b of names)
-            bodies[b] = this.position(b, jdUt, calc);
+        const unavailable = [];
+        for (const b of names) {
+            try {
+                bodies[b] = this.position(b, jdUt, calc);
+            }
+            catch (e) {
+                // A Chebyshev-packed body (Chiron, fitted asteroids) outside its fitted
+                // range throws RangeError. Omit it and report it rather than discarding
+                // the whole chart; the analytic bodies still resolve. Any other error
+                // (e.g. a missing data pack) is a real fault and propagates.
+                if (e instanceof RangeError)
+                    unavailable.push(b);
+                else
+                    throw e;
+            }
+        }
         const [asc, mc, armc, eps] = H.angles(this.data, jdUt, lat, lonEast);
         const [vtx, east] = H.vertexEastPoint(armc, lat * DEG, eps);
         const phi = lat * DEG;
@@ -454,7 +560,7 @@ export class Engine {
                 cusps = H.housesVehlow(armc, phi, eps);
             }
             else {
-                throw new Error(`unknown house system '${houseSystem}'`);
+                throw new Error(`unknown house system '${houseSystem}' (valid: ${HOUSE_SYSTEMS.join(", ")})`);
             }
         }
         catch (err) {
@@ -477,21 +583,44 @@ export class Engine {
         else {
             cuspsDeg = cusps.map(outDeg);
         }
+        // Enrich each position with chart-relative placement (house) and the
+        // essential dignities of its sign, so callers don't recompute from cusps.
+        const chartBodies = {};
+        for (const b of names) {
+            const p = bodies[b];
+            if (!p)
+                continue; // omitted: outside its fitted range (see `unavailable`)
+            chartBodies[b] = {
+                ...p,
+                house: houseIndex(p.lon, cuspsDeg),
+                dignities: dignities(b, Math.floor(mod(p.lon, 360) / 30)),
+            };
+        }
         return {
             jdUt,
             zodiac,
             houseSystem: used,
             houseSystemRequested: houseSystem,
-            bodies,
+            bodies: chartBodies,
+            unavailable,
             angles: {
                 asc: outDeg(asc), mc: outDeg(mc),
                 vertex: outDeg(vtx), eastPoint: outDeg(east),
             },
             cusps: cuspsDeg,
-            aspects: findAspects(bodies, o.orbs ?? DEFAULT_ORBS),
+            aspects: findAspects(chartBodies, o.orbs ?? DEFAULT_ORBS),
         };
     }
 }
+/** 1-based house for an ecliptic longitude (degrees) given the twelve cusp
+ *  longitudes (degrees), wrapping across 0. */
+function houseIndex(lon, cusps) {
+    for (let i = 0; i < 12; i++) {
+        if (mod(lon - cusps[i], 360) < mod(cusps[(i + 1) % 12] - cusps[i], 360))
+            return i + 1;
+    }
+    return 12;
+}
 export function findAspects(bodies, orbs = DEFAULT_ORBS) {
     const out = [];
     const names = Object.keys(bodies).filter((b) => !NOT_ASPECTABLE.has(b));
@@ -511,8 +640,11 @@ export function findAspects(bodies, orbs = DEFAULT_ORBS) {
     return out;
 }
 export function fmtLon(deg) {
-    const sign = SIGNS[Math.floor(deg / 30)];
-    const d = mod(deg, 30);
+    // Normalize first: a raw or rounded longitude (e.g. exactly 360, or a small
+    // negative) would otherwise index SIGNS out of range and render "undefined".
+    const norm = mod(deg, 360);
+    const sign = SIGNS[Math.floor(norm / 30)];
+    const d = mod(norm, 30);
     const m = mod(d, 1) * 60;
     return `${String(Math.floor(d)).padStart(2)}°${String(Math.floor(m)).padStart(2, "0")}' ${sign}`;
 }

package/dist/src/derived.d.ts

@@ -109,21 +109,6 @@ export declare function declinationAspects(engine: Engine, bodies: BodyId[], jd:
 /** |declination| minus the mean obliquity, degrees. Positive = out of bounds. */
 export declare function outOfBoundsMargin(engine: Engine, body: BodyId, jd: number): number;
 export declare function outOfBounds(engine: Engine, body: BodyId, jd: number): boolean;
-/**
- * Essential dignities a body holds in a sign: any of `"domicile"`,
- * `"exaltation"`, `"detriment"`, `"fall"` (the last two are the signs opposite
- * domicile and exaltation). Empty when the body is peregrine there.
- *
- * @param body Body id, e.g. `"mars"`.
- * @param sign A sign index `0`–`11` (Aries = 0) or its name, e.g. `"Aries"`.
- * @returns The dignities held, in the order above; empty if none.
- * @example
- * ```ts
- * dignities("mars", "Aries"); // ["domicile"]
- * dignities("sun", "Libra");  // ["fall"]
- * ```
- */
-export declare function dignities(body: string, sign: number | string): string[];
 export declare function dignityOf(engine: Engine, body: BodyId, jd: number, zodiac?: Zodiac): string[];
 /** Diurnal when the Sun is above the horizon at the given place. */
 export declare function isDayChart(engine: Engine, jd: number, lat: number, lonEast: number): boolean;

package/dist/src/derived.js

@@ -9,7 +9,7 @@
  * golden fixtures pin the two together.
  */
 import { mod, meanObliquity, jdTT, DEG } from "./core.js";
-import { SIGNS } from "./chart.js";
+import { dignities } from "./chart.js";
 import { crossings } from "./events.js";
 import { azAlt } from "./pheno.js";
 export const TROPICAL_YEAR = 365.24219; // mean tropical year, days
@@ -198,44 +198,9 @@ export function outOfBounds(engine, body, jd) {
     return outOfBoundsMargin(engine, body, jd) > 0;
 }
 // ----------------------------------------------------------- dignities
-const DOMICILE = {
-    sun: [4], moon: [3], mercury: [2, 5], venus: [1, 6],
-    mars: [0, 7], jupiter: [8, 11], saturn: [9, 10],
-};
-const EXALTATION = {
-    sun: 0, moon: 1, mercury: 5, venus: 11, mars: 9, jupiter: 3, saturn: 6,
-};
-function signIndex(sign) {
-    return typeof sign === "number" ? sign : SIGNS.indexOf(sign);
-}
-/**
- * Essential dignities a body holds in a sign: any of `"domicile"`,
- * `"exaltation"`, `"detriment"`, `"fall"` (the last two are the signs opposite
- * domicile and exaltation). Empty when the body is peregrine there.
- *
- * @param body Body id, e.g. `"mars"`.
- * @param sign A sign index `0`–`11` (Aries = 0) or its name, e.g. `"Aries"`.
- * @returns The dignities held, in the order above; empty if none.
- * @example
- * ```ts
- * dignities("mars", "Aries"); // ["domicile"]
- * dignities("sun", "Libra");  // ["fall"]
- * ```
- */
-export function dignities(body, sign) {
-    const idx = signIndex(sign);
-    const dom = DOMICILE[body] ?? [];
-    const out = [];
-    if (dom.includes(idx))
-        out.push("domicile");
-    if (EXALTATION[body] === idx)
-        out.push("exaltation");
-    if (dom.map((d) => mod(d + 6, 12)).includes(idx))
-        out.push("detriment");
-    if (body in EXALTATION && mod(EXALTATION[body] + 6, 12) === idx)
-        out.push("fall");
-    return out;
-}
+// The pure `dignities(body, sign)` table now lives in chart.ts (with the other
+// sign primitives); re-exported through the package index from there. This
+// engine-aware wrapper resolves a body's sign at an instant first.
 export function dignityOf(engine, body, jd, zodiac = "tropical") {
     const lon = engine.longitude(body, jd, { zodiac });
     return dignities(body, mod(Math.floor(lon / 30), 12));

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,27 @@
+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[];

package/dist/src/parans.js

@@ -0,0 +1,59 @@
+/**
+ * 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";
+export const PARAN_ANGLES = ["rise", "mtransit", "set", "itransit"];
+export const DEFAULT_PARAN_BODIES = ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn"];
+/**
+ * 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;
+}

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/rajayoga.js

@@ -9,6 +9,7 @@ export const TRIKONAS = [1, 5, 9];
 export const DHANA_HOUSES = [2, 5, 9, 11];
 const PURE_KENDRAS = [4, 7, 10];
 const PURE_TRIKONAS = [5, 9];
+// The seven classical grahas: all analytic, so always present in a chart.
 const PLANETS = ["sun", "moon", "mars", "mercury", "jupiter", "venus", "saturn"];
 /** The traditional ruler of a sign index (0 = Aries). */
 export function signLord(sign) {

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/dist/src/yogas.d.ts

@@ -12,8 +12,8 @@
  * variant-laden yogas (Kemadruma, lordship-based raja/dhana) are left to a later
  * step. Mirrors the Python reference (astroengine/yogas.py).
  */
-import { Engine, BodyId, Zodiac } from "./chart.js";
-export declare const YOGA_PLANETS: BodyId[];
+import { Engine, Zodiac, AlwaysBody } from "./chart.js";
+export declare const YOGA_PLANETS: readonly AlwaysBody[];
 export interface Yoga {
     yoga: string;
     planets: string[];

package/dist/src/yogas.js

@@ -1,10 +1,25 @@
-import { dignities } from "./derived.js";
+/**
+ * astroengine yogas -- classical Vedic yogas (planetary combinations) judged on
+ * the sidereal rasi (D1) chart.
+ *
+ * Covers the well-defined, placement-based yogas with no textual variation: the
+ * five Pancha Mahapurusha yogas (a non-luminary in its own sign or exaltation
+ * AND in a kendra from the Ascendant -- Ruchaka/Mars, Bhadra/Mercury,
+ * Hamsa/Jupiter, Malavya/Venus, Shasha/Saturn); Gajakesari (Jupiter in a kendra
+ * from the Moon); Budha-Aditya (Sun and Mercury in one sign); and
+ * Chandra-Mangala (Moon and Mars in one sign). Own-sign/exaltation use the
+ * engine's `dignities`; houses are whole-sign from the Ascendant. The
+ * variant-laden yogas (Kemadruma, lordship-based raja/dhana) are left to a later
+ * step. Mirrors the Python reference (astroengine/yogas.py).
+ */
+import { dignities } from "./chart.js";
 /** Pancha Mahapurusha: [yoga name, planet]. */
 const MAHAPURUSHA = [
     ["Ruchaka", "mars"], ["Bhadra", "mercury"], ["Hamsa", "jupiter"],
     ["Malavya", "venus"], ["Shasha", "saturn"],
 ];
 const KENDRA = new Set([1, 4, 7, 10]);
+// The seven classical grahas: all analytic, so always present in a chart.
 export const YOGA_PLANETS = ["sun", "moon", "mars", "mercury", "jupiter", "venus", "saturn"];
 /** The placement yogas present in a chart. `signs` maps each of the seven
  *  classical planets to its 0-based sign index; `ascSign` is the Ascendant's

package/package.json

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