@magmacomputing/tempo-plugin-celestial

A Community plugin for Tempo providing location-aware solar twilight events (t.term.sun, t.term.solar), real-time lunar cycle phases (t.term.moon, t.term.lunar), and astronomical tidal mechanics (t.term.tide, t.term.tides).

---

Key Features

• Solar Day Cycles: Calculates daylight, night, civil-twilight, nautical-twilight, and astronomical-twilight.
• Solar Ephemeris Data: Returns sunrise, sunset, noon, solarTime (Local Apparent Solar Time), total daylightDurationMs, and observer elevation horizon dip adjustments.
• Lunar Phase & Topocentric Ephemeris: Calculates 8 discrete lunar phase states, illumination fraction (0.0–1.0), age in days, hemisphere-aware emojis, local moonrise and moonset events, meridian transit (transit), topocentric position (altitude/azimuth), bright limb crescent tilt (crescentTiltDeg), and orbital distance (distanceKm, angularDiameterArcmin, isSupermoon, isMicromoon).
• Local Eclipse Obscuration: Detects active solar and lunar eclipses ('total-solar', 'annular-solar', 'partial-solar', 'total-lunar', 'partial-lunar', 'penumbral-lunar') and computes local disk obscuration fraction (0.0 to 1.0).
• Astronomical Tidal Mechanics: Provides pure astronomical solar/lunar alignment calculations (t.term.tide, t.term.tides) for spring, neap, and normal tides, alongside isKingTide perigee indicators.

---

Installation

npm install @magmacomputing/tempo-plugin-celestial

---

Quickstart

Interactive Demo (@magmacomputing/tempo-plugin-celestial)

Open in Full REPL↗

// 🌙 Celestial Solar & Lunar Ephemeris Demo (@magmacomputing/tempo-plugin-celestial)
const now = new Tempo();
console.log('Moon Phase:', now.term.lunar.phase);
console.log('Illumination:', (now.term.lunar.illumination * 100).toFixed(1) + '%');
console.log('Is King Tide?', now.term.tides.isKingTide);

return `Phase: ${now.term.lunar.phase} (${(now.term.lunar.illumination * 100).toFixed(0)}% illuminated)`;

Executes 100% in browser via native ESM sandbox

import { Tempo } from '@magmacomputing/tempo';
import { CelestialPlugin } from '@magmacomputing/tempo-plugin-celestial';

Tempo.use(CelestialPlugin);

// Provide geographic coordinates (e.g. New York City)
const t = new Tempo('2026-06-21T12:00:00Z', {
  timeZone: 'America/New_York',
  geo: { lat: 40.7128, lng: -74.006 }
});

// --- Solar Day State & Ephemeris ---
console.log(t.term.sun);                 // 'daylight'
console.log(t.term.solar.phase);         // 'Daylight'
console.log(t.term.solar.sunrise);       // Tempo instance for local sunrise
console.log(t.term.solar.noon);          // Tempo instance for local solar noon
console.log(t.term.solar.solarTime);     // Tempo instance for local apparent solar time (AST)

// --- Lunar Phase & Ephemeris ---
console.log(t.term.moon);                // 'waxing-crescent'
console.log(t.term.lunar.phase);         // 'Waxing Crescent'
console.log(t.term.lunar.illumination);  // 0.45
console.log(t.term.lunar.moonrise);      // Tempo instance for local moonrise (or null)

// --- Astronomical Tidal Mechanics ---
console.log(t.term.tide);                // 'spring', 'neap', or 'normal'
console.log(t.term.tides.alignmentDeg);  // Solar-lunar alignment angle (0..360°)
console.log(t.term.tides.isSpringTide);  // true during Syzygy (New or Full Moon)
console.log(t.term.tides.isKingTide);    // true when Spring Tide aligns with Lunar Perigee

// --- Term Lifecycle Hooks ---
// Snapping & stepping
t.set('#moon.start');                    // Snap to start of active lunar phase
t.add('#moon');                          // Step forward by 1 synodic lunation (~29.53 days)
t.set('#solar.start');                   // Snap to sunrise
t.set('#solar.mid');                     // Snap to solar noon
t.add('#tide');                          // Step forward by 1 tidal cycle (745 min)

// Semantic parsing & ordinals
const nextSunrise = Tempo.from('#solar.sunrise', { anchor: t });
const equinox = Tempo.from('1st day of #equinox', { anchor: t });

// Dynamic token formatting
console.log(t.format('Moon: {#moon.emoji} {#moon.phase} ({#moon.illumination})'));
console.log(t.format('Sun: {#solar.phase} | Elev: {#solar.elevation}'));

Auto-Installation (Side-Effect Import)

import { Tempo } from '@magmacomputing/tempo';
import '@magmacomputing/tempo-plugin-celestial/install';

const t = new Tempo('2026-06-21T12:00:00Z', { geo: { lat: 40.7128, lng: -74.006 } });
console.log(t.term.sun);

Geographic Coordinates & Null Contract

Pure Astronomical Calculations

Tidal state resolution and synodic lunar phases rely on deterministic celestial mechanics for reproducible, offset-independent math across all time zones.

Location-Dependent Null Contract

• Global Astronomical Properties (t.term.moon, t.term.lunar.phase, t.term.lunar.illumination, t.term.tides.isSpringTide, t.term.tides.alignmentDeg) resolve location-independently and are always computed.
• Geo-Dependent Properties (t.term.sun, solar.sunrise, solar.sunset, solar.noon, solar.solarTime, lunar.moonrise, lunar.moonset, lunar.transit, lunar.altitude, lunar.azimuth, lunar.crescentTiltDeg, lunar.distanceKm, lunar.eclipse, lunar.obscuration, tides.lunarTideMinute) evaluate to null when geographic coordinates (geo: { lat, lng }) are omitted.
• Distinction: Property access on t.term evaluates to undefined if CelestialPlugin is not loaded, and to null if the plugin is active but location coordinates were not supplied. When debug >= 1 is enabled in Tempo configuration, a developer warning is logged when evaluating geo-dependent keys without coordinates.

Coordinates, Sphere & Timezone Resolution

• sphere Derivation: Setting { geo: { lat, lng } } automatically computes the observer's hemisphere ('north', 'south', or 'equator').
• timeZone Requirement: Geographic coordinates (lat, lng) calculate the exact physical UTC moments of astronomical events, but do not auto-derive political timezone boundaries in core Tempo. Always supply an explicit timeZone (e.g. 'America/New_York' or 'UTC') to ensure local day and night ranges project deterministically across different host environments and CI runners.

---

Topic Guides

Explore detailed guides on specific celestial capabilities:

• Astronomical Seasons, Solstices & Equinoxes: Solar quarters, equinoxes, solstices, hemisphere-aware seasonal labels (t.term.astro, t.term.equinox, t.term.solstice), and sub-minute Meeus ephemeris boundaries.
• Solar Day Cycles & Ephemeris: Twilight bands (civil, nautical, astronomical), atmospheric elevation dip correction, exact apparent solar noon (solar.noon), and Local Apparent Solar Time (solar.solarTime).
• Lunar Ephemeris, Topocentric Ephemeris & Eclipses: 8 synodic lunar phases, illumination ratio, lunar age, hemisphere-aware emojis, topocentric horizon events (moonrise/moonset), meridian transits (transit), real-time sky position (altitude/azimuth), crescent tilt (crescentTiltDeg), orbital distance (isSupermoon/isMicromoon), and local solar/lunar eclipse detection (eclipse/obscuration).
• Astronomical Tidal Mechanics: Syzygy, quadrature, and perigee calculations (spring, neap, king tides), solar-lunar alignment angles, and 745-minute tidal cycles.
• Production Use Cases & Architectural Patterns: Photovoltaic microgrid inverter modes, greenhouse DLI supplemental lighting, maritime keel clearance windows, and golden hour drone flight scheduling.

---

License

This is a Community plugin. It is completely free and open-source for personal and commercial use under the MIT license.