rave-engine 1.0.0

package/src/calc/swisseph.js

@@ -0,0 +1,87 @@
+// OPTIONAL high-precision backend, built on the native `swisseph` binding.
+//
+// This file is only loaded when EPHE_BACKEND=swisseph AND the native binding +
+// ephemeris files are actually available. `swisseph` is an optional dependency:
+// the package works fully without it (the pure-JS `astronomia` backend is the
+// default). Note that `swisseph` is AGPL/commercial and ships Astrodienst data
+// files, so it is never required for the published package.
+//
+// Exposes the same interface as ./astronomia.js so the two are interchangeable:
+//   { name, BODIES, julianDayUT(dt), longitude(body, jdUT) }
+
+const path = require('path');
+const fs = require('fs');
+
+const { normalizeAngleDegrees } = require('./mandala');
+
+// Loaded lazily — require() of the native binding can throw on ABI mismatch.
+const swe = require('swisseph');
+
+const BODY_TO_SE = {
+  sun: swe.SE_SUN,
+  moon: swe.SE_MOON,
+  mercury: swe.SE_MERCURY,
+  venus: swe.SE_VENUS,
+  mars: swe.SE_MARS,
+  jupiter: swe.SE_JUPITER,
+  saturn: swe.SE_SATURN,
+  uranus: swe.SE_URANUS,
+  neptune: swe.SE_NEPTUNE,
+  pluto: swe.SE_PLUTO,
+  north_node: swe.SE_TRUE_NODE,
+};
+
+const BODIES = Object.keys(BODY_TO_SE);
+const FLAGS = swe.SEFLG_SWIEPH | swe.SEFLG_SPEED;
+
+let _ephePathSet = false;
+
+function isReadableDir(dirPath) {
+  try {
+    return fs.statSync(dirPath).isDirectory();
+  } catch (_e) {
+    return false;
+  }
+}
+
+function ensureEphePath() {
+  if (_ephePathSet) return;
+  const configured = process.env.EPHE_PATH;
+  let ephePath = null;
+  if (configured && isReadableDir(path.resolve(configured))) {
+    ephePath = path.resolve(configured);
+  } else {
+    // swisseph ships its own ephe/ folder; use it as a fallback.
+    try {
+      const pkg = require.resolve('swisseph/package.json');
+      const candidate = path.join(path.dirname(pkg), 'ephe');
+      if (isReadableDir(candidate)) ephePath = candidate;
+    } catch (_e) {
+      /* ignore */
+    }
+  }
+  if (ephePath) swe.swe_set_ephe_path(ephePath);
+  _ephePathSet = true;
+}
+
+function julianDayUT(dt) {
+  const hour =
+    dt.getUTCHours() +
+    dt.getUTCMinutes() / 60 +
+    dt.getUTCSeconds() / 3600 +
+    dt.getUTCMilliseconds() / 3600000;
+  return swe.swe_julday(dt.getUTCFullYear(), dt.getUTCMonth() + 1, dt.getUTCDate(), hour, swe.SE_GREG_CAL);
+}
+
+function longitude(body, jdUT) {
+  ensureEphePath();
+  const id = BODY_TO_SE[body];
+  if (id === undefined) throw new Error(`swisseph backend: unknown body "${body}"`);
+  const r = swe.swe_calc_ut(jdUT, id, FLAGS);
+  if (!r || !Number.isFinite(r.longitude)) {
+    throw new Error(`swisseph backend: swe_calc_ut failed for "${body}" (${r && r.error})`);
+  }
+  return normalizeAngleDegrees(r.longitude);
+}
+
+module.exports = { name: 'swisseph', BODIES, julianDayUT, longitude };

package/src/chart.js

@@ -0,0 +1,84 @@
+// computeChart — the high-level "powerful primitive".
+//
+// From a birth date / time / timezone (and an optional location), it returns
+// three coherent sections:
+//   - geneKeys   : the Gene Keys ("Jinki") sphere map — gk + line per sphere
+//   - humanDesign: the full Human Design bodygraph — activations, gates,
+//                  channels, defined / open centers, Type, Authority, Profile
+//   - astrology  : extended astrology — Ascendant / Descendant / MC / IC and
+//                  house cusps (needs a location; null if none resolvable)
+
+const { parseBirthToUtc } = require('./birth/parseBirth');
+const { computeEngineTest, computeActivations } = require('./calc/profile');
+const { computeBodygraph } = require('./hd/bodygraph');
+const { computeAngles, computeHouses } = require('./hd/houses');
+const { resolveLocation } = require('./timezone/location');
+
+/**
+ * @param {{
+ *   birthdate: string,
+ *   birthtime: string,
+ *   timezone: string,
+ *   location?: { lat:number, lng:number },
+ *   houseSystem?: 'placidus'|'whole'|'equal'
+ * }} input
+ */
+function computeChart(input) {
+  const birthUtc = parseBirthToUtc(input);
+
+  const engine = computeEngineTest({ birthUtc });
+  const activations = computeActivations({ birthUtc });
+  const bodygraph = computeBodygraph(activations);
+
+  // Resolve a birth location: explicit lat/lng wins, else the timezone's
+  // representative (most-populous-city) coordinates.
+  const location = resolveLocation({
+    lat: input.location && input.location.lat,
+    lng: input.location && input.location.lng,
+    timezone: input.timezone,
+  });
+
+  let astrology = null;
+  if (location) {
+    const jdUT = engine._meta.jd_personality;
+    const houseSystem = input.houseSystem || 'placidus';
+    astrology = {
+      location,
+      angles: computeAngles({ jdUT, lat: location.lat, lng: location.lng }),
+      houses: computeHouses({ jdUT, lat: location.lat, lng: location.lng, system: houseSystem }),
+    };
+  }
+
+  // geneKeys spheres without the internal _meta key.
+  const { _meta: spheresMeta, ...spheres } = engine.spheres;
+
+  return {
+    input: {
+      birthdate: input.birthdate,
+      birthtime: input.birthtime,
+      timezone: input.timezone,
+      birth_utc: birthUtc.toISOString(),
+      location,
+    },
+    geneKeys: { spheres },
+    humanDesign: {
+      type: bodygraph.type,
+      authority: bodygraph.authority,
+      profile: bodygraph.profile,
+      definitionCount: bodygraph.definitionCount,
+      p_: engine.p_,
+      d_: engine.d_,
+      activations: { personality: activations.personality, design: activations.design },
+      activatedGates: bodygraph.activatedGates,
+      definedChannels: bodygraph.definedChannels,
+      definedCenters: bodygraph.definedCenters,
+      openCenters: bodygraph.openCenters,
+      centers: bodygraph.centers,
+      gateActivations: bodygraph.gateActivations,
+    },
+    astrology,
+    _meta: engine._meta,
+  };
+}
+
+module.exports = { computeChart };

package/src/hd/bodygraph.js

@@ -0,0 +1,270 @@
+// Human Design bodygraph: the canonical (Jovian Archive / Ra Uru Hu) mapping of
+// the 64 gates to the 9 centers and the 36 channels, plus the derivation of a
+// full bodygraph (activated gates, defined channels, defined / open centers,
+// Type, Authority, Profile) from a set of planetary gate activations.
+//
+// This data is fixed, well-known reference data — the same bodygraph used by
+// every Human Design chart calculator.
+
+// The 9 centers.
+const CENTERS = [
+  'head',
+  'ajna',
+  'throat',
+  'g',
+  'heart',
+  'sacral',
+  'solarplexus',
+  'spleen',
+  'root',
+];
+
+// Human-readable center labels.
+const CENTER_LABELS = {
+  head: 'Head',
+  ajna: 'Ajna',
+  throat: 'Throat',
+  g: 'G (Identity)',
+  heart: 'Heart (Ego/Will)',
+  sacral: 'Sacral',
+  solarplexus: 'Solar Plexus',
+  spleen: 'Spleen',
+  root: 'Root',
+};
+
+// The "motor" centers — sources of energy/pressure that can power the Throat.
+const MOTOR_CENTERS = ['sacral', 'heart', 'solarplexus', 'root'];
+
+// Gate → center. All 64 gates appear exactly once (asserted in tests).
+const GATE_CENTER = {
+  // Head (Crown)
+  64: 'head', 61: 'head', 63: 'head',
+  // Ajna
+  47: 'ajna', 24: 'ajna', 4: 'ajna', 17: 'ajna', 11: 'ajna', 43: 'ajna',
+  // Throat
+  62: 'throat', 23: 'throat', 56: 'throat', 35: 'throat', 12: 'throat', 45: 'throat',
+  33: 'throat', 8: 'throat', 31: 'throat', 20: 'throat', 16: 'throat',
+  // G (Identity / Self)
+  1: 'g', 13: 'g', 25: 'g', 46: 'g', 2: 'g', 15: 'g', 10: 'g', 7: 'g',
+  // Heart (Ego / Will)
+  21: 'heart', 40: 'heart', 26: 'heart', 51: 'heart',
+  // Spleen
+  48: 'spleen', 57: 'spleen', 44: 'spleen', 50: 'spleen', 32: 'spleen', 28: 'spleen', 18: 'spleen',
+  // Sacral
+  34: 'sacral', 5: 'sacral', 14: 'sacral', 29: 'sacral', 59: 'sacral', 9: 'sacral',
+  3: 'sacral', 42: 'sacral', 27: 'sacral',
+  // Solar Plexus (Emotional)
+  6: 'solarplexus', 37: 'solarplexus', 30: 'solarplexus', 55: 'solarplexus',
+  49: 'solarplexus', 22: 'solarplexus', 36: 'solarplexus',
+  // Root
+  53: 'root', 60: 'root', 52: 'root', 19: 'root', 39: 'root', 41: 'root',
+  58: 'root', 38: 'root', 54: 'root',
+};
+
+// The 36 channels as unordered gate pairs. The two centers a channel connects
+// are DERIVED from GATE_CENTER (see CHANNELS below) so the data can't drift.
+const CHANNEL_GATE_PAIRS = [
+  [1, 8], [2, 14], [3, 60], [4, 63], [5, 15], [6, 59], [7, 31], [9, 52],
+  [10, 20], [10, 34], [10, 57], [11, 56], [12, 22], [13, 33], [16, 48], [17, 62],
+  [18, 58], [19, 49], [20, 34], [20, 57], [21, 45], [23, 43], [24, 61], [25, 51],
+  [26, 44], [27, 50], [28, 38], [29, 46], [30, 41], [32, 54], [34, 57], [35, 36],
+  [37, 40], [39, 55], [42, 53], [47, 64],
+];
+
+// Optional channel names (nice-to-have for output; not required for derivation).
+const CHANNEL_NAMES = {
+  '1-8': 'Inspiration', '2-14': 'The Beat', '3-60': 'Mutation', '4-63': 'Logic',
+  '5-15': 'Rhythm', '6-59': 'Mating', '7-31': 'The Alpha', '9-52': 'Concentration',
+  '10-20': 'Awakening', '10-34': 'Exploration', '10-57': 'Perfected Form',
+  '11-56': 'Curiosity', '12-22': 'Openness', '13-33': 'The Prodigal',
+  '16-48': 'The Wavelength', '17-62': 'Acceptance', '18-58': 'Judgment',
+  '19-49': 'Synthesis', '20-34': 'Charisma', '20-57': 'The Brainwave',
+  '21-45': 'Money', '23-43': 'Structuring', '24-61': 'Awareness', '25-51': 'Initiation',
+  '26-44': 'Surrender', '27-50': 'Preservation', '28-38': 'Struggle',
+  '29-46': 'Discovery', '30-41': 'Recognition', '32-54': 'Transformation',
+  '34-57': 'Power', '35-36': 'Transitoriness', '37-40': 'Community',
+  '39-55': 'Emoting', '42-53': 'Maturation', '47-64': 'Abstraction',
+};
+
+function channelKey(a, b) {
+  const [lo, hi] = a < b ? [a, b] : [b, a];
+  return `${lo}-${hi}`;
+}
+
+// Materialized channel list with derived centers.
+const CHANNELS = CHANNEL_GATE_PAIRS.map(([a, b]) => {
+  const [lo, hi] = a < b ? [a, b] : [b, a];
+  const key = `${lo}-${hi}`;
+  return {
+    key,
+    gates: [lo, hi],
+    centers: [GATE_CENTER[lo], GATE_CENTER[hi]],
+    name: CHANNEL_NAMES[key] || null,
+  };
+});
+
+function uniqueSorted(nums) {
+  return [...new Set(nums)].sort((x, y) => x - y);
+}
+
+// Reachability in the defined-center graph: can any motor center reach Throat?
+function motorConnectsToThroat(definedCentersSet, definedChannels) {
+  if (!definedCentersSet.has('throat')) return false;
+  // adjacency among defined centers via defined channels
+  const adj = new Map();
+  for (const c of definedCentersSet) adj.set(c, new Set());
+  for (const ch of definedChannels) {
+    const [c1, c2] = ch.centers;
+    if (adj.has(c1) && adj.has(c2)) {
+      adj.get(c1).add(c2);
+      adj.get(c2).add(c1);
+    }
+  }
+  const motors = MOTOR_CENTERS.filter((m) => definedCentersSet.has(m));
+  // BFS from each motor; success if Throat is reached.
+  const seen = new Set();
+  const queue = [...motors];
+  motors.forEach((m) => seen.add(m));
+  while (queue.length) {
+    const cur = queue.shift();
+    if (cur === 'throat') return true;
+    for (const nxt of adj.get(cur) || []) {
+      if (!seen.has(nxt)) {
+        seen.add(nxt);
+        queue.push(nxt);
+      }
+    }
+  }
+  return false;
+}
+
+function determineType(definedCentersSet, definedChannels) {
+  if (definedCentersSet.size === 0) return 'Reflector';
+  const sacral = definedCentersSet.has('sacral');
+  const motorThroat = motorConnectsToThroat(definedCentersSet, definedChannels);
+  if (sacral) return motorThroat ? 'Manifesting Generator' : 'Generator';
+  return motorThroat ? 'Manifestor' : 'Projector';
+}
+
+function determineAuthority(definedCentersSet, definedChannels) {
+  const has = (c) => definedCentersSet.has(c);
+  if (definedCentersSet.size === 0) return 'Lunar (Reflector)';
+  if (has('solarplexus')) return 'Emotional (Solar Plexus)';
+  if (has('sacral')) return 'Sacral';
+  if (has('spleen')) return 'Splenic';
+  if (has('heart')) return 'Ego (Heart)';
+  // G defined and connected to the throat → Self-Projected.
+  if (has('g') && has('throat')) {
+    const gReachesThroat = motorConnectsToThroatFrom('g', definedCentersSet, definedChannels);
+    if (gReachesThroat) return 'Self-Projected (G)';
+  }
+  // Only awareness/throat centers → Mental (Environmental / "None").
+  return 'Mental (None / Environmental)';
+}
+
+// Generic reachability from a single start center to the throat.
+function motorConnectsToThroatFrom(start, definedCentersSet, definedChannels) {
+  if (!definedCentersSet.has('throat') || !definedCentersSet.has(start)) return false;
+  const adj = new Map();
+  for (const c of definedCentersSet) adj.set(c, new Set());
+  for (const ch of definedChannels) {
+    const [c1, c2] = ch.centers;
+    if (adj.has(c1) && adj.has(c2)) {
+      adj.get(c1).add(c2);
+      adj.get(c2).add(c1);
+    }
+  }
+  const seen = new Set([start]);
+  const queue = [start];
+  while (queue.length) {
+    const cur = queue.shift();
+    if (cur === 'throat') return true;
+    for (const nxt of adj.get(cur) || []) {
+      if (!seen.has(nxt)) {
+        seen.add(nxt);
+        queue.push(nxt);
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Derive a full Human Design bodygraph from planetary activations.
+ *
+ * @param {{
+ *   personality: Array<{ body: string, gate: number, line: number }>,
+ *   design: Array<{ body: string, gate: number, line: number }>
+ * }} activations  (as returned by computeActivations)
+ * @returns {{
+ *   type: string,
+ *   authority: string,
+ *   profile: string,
+ *   definitionCount: number,
+ *   activatedGates: number[],
+ *   definedChannels: Array<{ key, gates, centers, name }>,
+ *   definedCenters: string[],
+ *   openCenters: string[],
+ *   centers: Record<string, boolean>,
+ *   gateActivations: Record<number, Array<{ stream, body, line }>>
+ * }}
+ */
+function computeBodygraph(activations) {
+  const personality = activations.personality || [];
+  const design = activations.design || [];
+  const all = [...personality, ...design];
+
+  const activatedGates = uniqueSorted(all.map((a) => a.gate));
+  const gateSet = new Set(activatedGates);
+
+  const definedChannels = CHANNELS.filter(
+    (ch) => gateSet.has(ch.gates[0]) && gateSet.has(ch.gates[1])
+  );
+
+  const definedCentersSet = new Set();
+  for (const ch of definedChannels) {
+    definedCentersSet.add(ch.centers[0]);
+    definedCentersSet.add(ch.centers[1]);
+  }
+  const definedCenters = CENTERS.filter((c) => definedCentersSet.has(c));
+  const openCenters = CENTERS.filter((c) => !definedCentersSet.has(c));
+
+  const centers = {};
+  for (const c of CENTERS) centers[c] = definedCentersSet.has(c);
+
+  // Per-gate activation detail (which body/stream lit each gate).
+  const gateActivations = {};
+  for (const a of all) {
+    if (!gateActivations[a.gate]) gateActivations[a.gate] = [];
+    gateActivations[a.gate].push({ stream: a.stream, body: a.body, line: a.line });
+  }
+
+  // Profile = personality Sun line / design Sun line.
+  const pSun = personality.find((a) => a.body === 'sun');
+  const dSun = design.find((a) => a.body === 'sun');
+  const profile = pSun && dSun ? `${pSun.line}/${dSun.line}` : null;
+
+  return {
+    type: determineType(definedCentersSet, definedChannels),
+    authority: determineAuthority(definedCentersSet, definedChannels),
+    profile,
+    definitionCount: definedChannels.length,
+    activatedGates,
+    definedChannels,
+    definedCenters,
+    openCenters,
+    centers,
+    gateActivations,
+  };
+}
+
+module.exports = {
+  CENTERS,
+  CENTER_LABELS,
+  MOTOR_CENTERS,
+  GATE_CENTER,
+  CHANNELS,
+  CHANNEL_NAMES,
+  channelKey,
+  computeBodygraph,
+};

package/src/hd/houses.js

@@ -0,0 +1,229 @@
+// Extended astrology: chart angles (Ascendant, Descendant, MC, IC) and house
+// cusps (Whole Sign, Equal, Placidus).
+//
+// These need NO ephemeris — only local sidereal time and the obliquity of the
+// ecliptic — so they are computed purely from Julian Day (UT) + geographic
+// latitude/longitude using the MIT `astronomia` package for sidereal time and
+// obliquity.
+
+const A = require('astronomia');
+const { normalizeAngleDegrees, mapLongitudeDegrees } = require('../calc/mandala');
+
+const D2R = Math.PI / 180;
+const R2D = 180 / Math.PI;
+
+const SIGNS = [
+  'Aries', 'Taurus', 'Gemini', 'Cancer', 'Leo', 'Virgo',
+  'Libra', 'Scorpio', 'Sagittarius', 'Capricorn', 'Aquarius', 'Pisces',
+];
+
+function signOf(lonDeg) {
+  const lon = normalizeAngleDegrees(lonDeg);
+  const idx = Math.floor(lon / 30);
+  return {
+    sign: SIGNS[idx],
+    signIndex: idx,
+    degInSign: lon - idx * 30,
+  };
+}
+
+/**
+ * Greenwich Apparent Sidereal Time in degrees for a Julian Day (UT).
+ * astronomia returns seconds of time; convert to degrees (×15/3600).
+ */
+function gastDegrees(jdUT) {
+  return normalizeAngleDegrees((A.sidereal.apparent(jdUT) / 3600) * 15);
+}
+
+function trueObliquityDeg(jdUT) {
+  // mean obliquity + nutation in obliquity, in degrees
+  return (A.nutation.meanObliquity(jdUT) + A.nutation.nutation(jdUT)[1]) * R2D;
+}
+
+/**
+ * Right Ascension of the Midheaven (Local Apparent Sidereal Time) in degrees.
+ * @param {number} jdUT
+ * @param {number} lngEast geographic longitude, degrees east (negative = west)
+ */
+function ramcDegrees(jdUT, lngEast) {
+  return normalizeAngleDegrees(gastDegrees(jdUT) + lngEast);
+}
+
+/**
+ * Ecliptic longitude of a point on the ecliptic (β=0) given its right ascension.
+ * λ = atan2(sin α, cos α · cos ε)
+ */
+function eclipticLonFromRA(raDeg, epsDeg) {
+  const ra = raDeg * D2R;
+  const eps = epsDeg * D2R;
+  return normalizeAngleDegrees(Math.atan2(Math.sin(ra), Math.cos(ra) * Math.cos(eps)) * R2D);
+}
+
+function declOfEclipticPoint(lonDeg, epsDeg) {
+  return Math.asin(Math.sin(epsDeg * D2R) * Math.sin(lonDeg * D2R)) * R2D;
+}
+
+/**
+ * Compute the four chart angles.
+ * @param {{ jdUT: number, lat: number, lng: number }} args  lat/lng in degrees
+ *        (lat north +, lng east +)
+ * @returns {{ ascendant, descendant, mc, ic }} each { longitude, sign, signIndex, degInSign, gateLine }
+ */
+function computeAngles({ jdUT, lat, lng }) {
+  const eps = trueObliquityDeg(jdUT);
+  const ramc = ramcDegrees(jdUT, lng);
+  const ramcR = ramc * D2R;
+  const epsR = eps * D2R;
+  const phiR = lat * D2R;
+
+  const mc = normalizeAngleDegrees(
+    Math.atan2(Math.sin(ramcR), Math.cos(ramcR) * Math.cos(epsR)) * R2D
+  );
+
+  let asc = normalizeAngleDegrees(
+    Math.atan2(
+      Math.cos(ramcR),
+      -(Math.sin(ramcR) * Math.cos(epsR) + Math.tan(phiR) * Math.sin(epsR))
+    ) * R2D
+  );
+
+  // The Ascendant must lie in the rising semicircle, i.e. 0..180° east of the
+  // MC. If the formula landed on the opposite point, flip it.
+  if (normalizeAngleDegrees(asc - mc) > 180) {
+    asc = normalizeAngleDegrees(asc + 180);
+  }
+
+  const decorate = (lon) => ({
+    longitude: lon,
+    ...signOf(lon),
+    gateLine: (() => {
+      const m = mapLongitudeDegrees(lon);
+      return { gate: m.hexagram, line: m.line };
+    })(),
+  });
+
+  return {
+    ascendant: decorate(asc),
+    descendant: decorate(normalizeAngleDegrees(asc + 180)),
+    mc: decorate(mc),
+    ic: decorate(normalizeAngleDegrees(mc + 180)),
+    _meta: { ramc, obliquity: eps },
+  };
+}
+
+// Iterative Placidus intermediate cusp (houses 11, 12, 2, 3).
+// Solves for the ecliptic point whose RA divides its day/night semi-arc in the
+// Placidus ratio. Returns null if the point is circumpolar (Placidus undefined,
+// typically |lat| > ~66°).
+function placidusIntermediate(ramc, eps, lat, which) {
+  // which: '11' | '12' | '2' | '3'
+  const phiR = lat * D2R;
+  const epsR = eps * D2R;
+
+  // target RA(SA, NA) per cusp; SA = semidiurnal arc, NA = 180 - SA
+  function targetRA(SA) {
+    const NA = 180 - SA;
+    switch (which) {
+      case '11':
+        return ramc + (1 / 3) * SA;
+      case '12':
+        return ramc + (2 / 3) * SA;
+      case '2':
+        return ramc + SA + (1 / 3) * NA;
+      case '3':
+        return ramc + SA + (2 / 3) * NA;
+      default:
+        throw new Error(`bad cusp ${which}`);
+    }
+  }
+
+  // initial offsets 30/60/120/150
+  const initialOffset = { 11: 30, 12: 60, 2: 120, 3: 150 }[which];
+  let ra = ramc + initialOffset;
+
+  for (let i = 0; i < 100; i += 1) {
+    const lon = eclipticLonFromRA(ra, eps);
+    const decl = declOfEclipticPoint(lon, eps);
+    const cosSA = -Math.tan(phiR) * Math.tan(decl * D2R);
+    if (cosSA <= -1 || cosSA >= 1) return null; // circumpolar → Placidus fails
+    const SA = Math.acos(cosSA) * R2D;
+    const next = targetRA(SA);
+    if (Math.abs(normalizeAngleDegrees(next - ra + 180) - 180) < 1e-9) {
+      ra = next;
+      break;
+    }
+    ra = next;
+  }
+  return eclipticLonFromRA(ra, eps);
+}
+
+/**
+ * Compute the 12 house cusps for a given system.
+ * @param {{ jdUT, lat, lng, system?: 'whole'|'equal'|'placidus' }} args
+ * @returns {{ system, cusps: Array<{ house, longitude, sign, degInSign }>, angles, fallback? }}
+ */
+function computeHouses({ jdUT, lat, lng, system = 'placidus' }) {
+  const angles = computeAngles({ jdUT, lat, lng });
+  const asc = angles.ascendant.longitude;
+  const mc = angles.mc.longitude;
+  const eps = angles._meta.obliquity;
+  const ramc = angles._meta.ramc;
+
+  const sys = String(system).toLowerCase();
+  let cuspLons = new Array(12);
+  let usedSystem = sys;
+  let fallback;
+
+  if (sys === 'whole') {
+    const base = Math.floor(normalizeAngleDegrees(asc) / 30) * 30;
+    for (let i = 0; i < 12; i += 1) cuspLons[i] = normalizeAngleDegrees(base + i * 30);
+  } else if (sys === 'equal') {
+    for (let i = 0; i < 12; i += 1) cuspLons[i] = normalizeAngleDegrees(asc + i * 30);
+  } else {
+    // placidus
+    const c11 = placidusIntermediate(ramc, eps, lat, '11');
+    const c12 = placidusIntermediate(ramc, eps, lat, '12');
+    const c2 = placidusIntermediate(ramc, eps, lat, '2');
+    const c3 = placidusIntermediate(ramc, eps, lat, '3');
+    if ([c11, c12, c2, c3].some((x) => x === null)) {
+      // Polar latitude: fall back to whole sign.
+      fallback = 'placidus undefined at this latitude — fell back to whole sign';
+      usedSystem = 'whole';
+      const base = Math.floor(normalizeAngleDegrees(asc) / 30) * 30;
+      for (let i = 0; i < 12; i += 1) cuspLons[i] = normalizeAngleDegrees(base + i * 30);
+    } else {
+      cuspLons[0] = asc; // 1
+      cuspLons[1] = c2; // 2
+      cuspLons[2] = c3; // 3
+      cuspLons[3] = normalizeAngleDegrees(mc + 180); // 4 (IC)
+      cuspLons[4] = normalizeAngleDegrees(c11 + 180); // 5
+      cuspLons[5] = normalizeAngleDegrees(c12 + 180); // 6
+      cuspLons[6] = normalizeAngleDegrees(asc + 180); // 7 (Desc)
+      cuspLons[7] = normalizeAngleDegrees(c2 + 180); // 8
+      cuspLons[8] = normalizeAngleDegrees(c3 + 180); // 9
+      cuspLons[9] = mc; // 10 (MC)
+      cuspLons[10] = c11; // 11
+      cuspLons[11] = c12; // 12
+    }
+  }
+
+  const cusps = cuspLons.map((lon, i) => ({
+    house: i + 1,
+    longitude: lon,
+    ...signOf(lon),
+  }));
+
+  return { system: usedSystem, requestedSystem: sys, fallback, cusps, angles };
+}
+
+module.exports = {
+  SIGNS,
+  signOf,
+  computeAngles,
+  computeHouses,
+  // exposed for testing
+  gastDegrees,
+  trueObliquityDeg,
+  ramcDegrees,
+  eclipticLonFromRA,
+};