@verifyhash/solar-calc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 <OWNER-NAME PLACEHOLDER>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# solar-calc
+
+<!-- publish-prep -->
+> **TODO (owner): pick the final npm name/scope before publishing.**
+> The npm package name is **not** finalized by this project. Convention used here:
+> `package.json` keeps the working slug `solar-calc` as a placeholder — replace it
+> (and the `npm install` line below) with the real published name/scope before
+> running `npm publish`.
+
+A tiny, **zero-dependency** Node library for solar geometry: sunrise, sunset,
+solar noon, day length, the Sun's elevation and azimuth at any instant, plus
+civil-twilight and golden-hour boundaries — for any latitude, longitude, and
+date.
+
+Every export is a **pure function**: no I/O, no network, no daemon, no
+dependencies, and no mutation of its arguments. The math follows the algorithm
+published by [NOAA's Solar Calculator](https://gml.noaa.gov/grad/solcalc/), a
+simplified form of Jean Meeus, *Astronomical Algorithms* (2nd ed.). Against
+published almanac times it lands within about a minute at mid latitudes (see
+the test fixtures).
+
+## Who it's for
+
+Developers building **weather**, **photography**, **astronomy**, or
+**agriculture** tools who need reliable solar numbers without pulling in a big
+ephemeris package or hitting an API:
+
+- a weather dashboard showing today's sunrise/sunset and length of day;
+- a photography planner that wants the golden-hour window for a shoot;
+- an astronomy or stargazing app that needs when civil twilight ends;
+- a solar/agriculture model that needs the Sun's elevation through the day.
+
+### Honest limits
+
+- Accuracy is **~1 minute at mid latitudes** and degrades toward the poles,
+  where a tiny error in the Sun's altitude maps to a large time swing. Near the
+  Arctic/Antarctic circles, treat sunrise/sunset times as approximate; the
+  polar-night / midnight-sun *detection* (returning `null`) is reliable.
+- Elevation and azimuth are **geometric** — the Sun's true position. They do
+  **not** add atmospheric refraction, so within ~0.5° of the horizon the
+  apparent (refracted) Sun sits a little higher than the returned value.
+- Sunrise/sunset use the standard **−0.833°** horizon (refraction + solar
+  radius). One visible consequence: at the equator on an equinox the day comes
+  out as ~12 h 07 m, not exactly 12 h — that offset is real, not a bug.
+- This is a **position** library, not an irradiance/energy model: it tells you
+  *where* the Sun is, not how much power hits a panel.
+
+## Install / use
+
+No install step, no dependencies. Copy the folder in and `require` it:
+
+```js
+const solar = require('./solar-calc');
+```
+
+### Conventions
+
+| input       | meaning                                                             |
+|-------------|---------------------------------------------------------------------|
+| `lat`       | latitude in degrees, **+ North** (New York ≈ `40.71`)               |
+| `lon`       | longitude in degrees, **+ East** (New York ≈ `-74.01`)             |
+| `dateInput` | a JS `Date` (only its Y/M/D matter, read in **UTC**) **or** a plain `{ year, month, day }` object with a **1-based** month |
+| `tz`        | offset of the **local clock** from UTC in **hours** (US Eastern Standard Time = `-5`); defaults to `0` (UTC) |
+
+Daily event functions (`sunrise`, `sunset`, `solarNoon`, twilight, golden hour)
+return a JS `Date` for the true **UTC instant** of the event, or `null` when it
+doesn't happen that day (polar night / midnight sun). To print one in local
+time, use `localClockMinutes(instant, tz)` or format the `Date` with your own
+`tz`.
+
+The instantaneous functions `solarElevation(lat, lon, date)` and
+`solarAzimuth(lat, lon, date)` take a **full `Date` instant** (date **and**
+time, UTC) and need no `tz` — the instant already fixes the moment.
+
+## Worked example
+
+```js
+const solar = require('./solar-calc');
+
+// New York City, June solstice 2021. EDT is UTC−4.
+const lat = 40.7128;
+const lon = -74.006;
+const tz = -4;
+const date = { year: 2021, month: 6, day: 21 };
+
+// Pretty-print a UTC event instant as local "HH:MM".
+function localHM(instant) {
+  if (!instant) return 'none';
+  const m = solar.localClockMinutes(instant, tz);
+  const h = Math.floor(m / 60);
+  const min = Math.round(m % 60);
+  return `${String(h).padStart(2, '0')}:${String(min).padStart(2, '0')}`;
+}
+
+console.log('sunrise    ', localHM(solar.sunrise(lat, lon, date, tz)));     // 05:25
+console.log('solar noon ', localHM(solar.solarNoon(lat, lon, date, tz)));   // 12:58
+console.log('sunset     ', localHM(solar.sunset(lat, lon, date, tz)));      // 20:31
+
+const mins = solar.dayLengthMinutes(lat, lon, date, tz);
+console.log('day length ', (mins / 60).toFixed(2), 'hours');               // 15.09 hours
+
+// Golden hour for an evening shoot:
+console.log('golden hour', localHM(solar.goldenHourEveningStart(lat, lon, date, tz)),
+            '→', localHM(solar.sunset(lat, lon, date, tz)));
+
+// Where is the Sun at 15:00 local (= 19:00 UTC)?
+const t = new Date(Date.UTC(2021, 5, 21, 19, 0, 0));
+console.log('elevation  ', solar.solarElevation(lat, lon, t).toFixed(1), '°');
+console.log('azimuth    ', solar.solarAzimuth(lat, lon, t).toFixed(1), '° from north');
+```
+
+## API
+
+All angles are in **degrees**; all times/durations in **minutes** unless noted.
+
+### Daily events → `Date` (UTC instant) or `null`
+
+| function | returns |
+|----------|---------|
+| `solarNoon(lat, lon, dateInput, tz?)` | instant the Sun is highest (always defined) |
+| `sunrise(lat, lon, dateInput, tz?)` | upper limb clearing the horizon, or `null` |
+| `sunset(lat, lon, dateInput, tz?)` | upper limb touching the horizon, or `null` |
+| `civilDawn(lat, lon, dateInput, tz?)` | Sun 6° below horizon, rising, or `null` |
+| `civilDusk(lat, lon, dateInput, tz?)` | Sun 6° below horizon, setting, or `null` |
+| `goldenHourMorningEnd(lat, lon, dateInput, tz?)` | Sun reaches 6° elevation after sunrise, or `null` |
+| `goldenHourEveningStart(lat, lon, dateInput, tz?)` | Sun descends to 6° elevation before sunset, or `null` |
+
+The morning golden hour runs **sunrise → `goldenHourMorningEnd`**; the evening
+golden hour runs **`goldenHourEveningStart` → sunset**.
+
+### Durations & raw quantities → `number`
+
+| function | returns |
+|----------|---------|
+| `dayLengthMinutes(lat, lon, dateInput, tz?)` | minutes between sunrise and sunset; `0` on polar night, `1440` under the midnight sun |
+| `declination(dateInput, tz?)` | Sun's declination in degrees (+ North) for that day |
+| `equationOfTime(dateInput, tz?)` | apparent − mean solar time, in minutes (≈ −14 … +16 over a year) |
+
+### Instantaneous position → `number` (degrees)
+
+| function | returns |
+|----------|---------|
+| `solarElevation(lat, lon, date)` | geometric elevation above the horizon; negative below. `date` is a full UTC `Date` instant |
+| `solarAzimuth(lat, lon, date)` | compass bearing clockwise from **true North** (0 = N, 90 = E, 180 = S, 270 = W) |
+
+### Helper
+
+| function | returns |
+|----------|---------|
+| `localClockMinutes(instant, tz?)` | minutes-after-midnight `[0, 1440)` on the local clock for a returned event instant, or `null` if passed `null` |
+
+## Running the tests
+
+One command, no dependencies:
+
+```sh
+node test/solar.test.js
+```
+
+The suite checks four known-city fixtures (New York, London, Sydney, Tokyo)
+against **published** sunrise/sunset times within **±2 minutes**, verifies the
+equator-at-equinox ≈12-hour day, the Tromsø midnight-sun (no sunset) and
+polar-night (no sunrise) cases, cross-checks the daily and instantaneous code
+paths against each other, and asserts the twilight/golden-hour ordering. It
+exits non-zero if anything fails.
+
+## License
+
+MIT.
+
+## Install
+
+> Placeholder name: the `solar-calc` below is the working slug, not a finalized
+> npm name — see the owner TODO near the top of this README.
+
+```sh
+npm install solar-calc
+```
+
+```js
+const solar = require('solar-calc');
+
+const lat = 40.7128, lon = -74.006, tz = -4; // New York City, EDT
+const date = { year: 2021, month: 6, day: 21 };
+solar.sunrise(lat, lon, date, tz);          // Date — UTC instant of sunrise
+solar.dayLengthMinutes(lat, lon, date, tz); // minutes of daylight
+```

package/index.js

@@ -0,0 +1,414 @@
+'use strict';
+
+/**
+ * solar-calc — zero-dependency solar position & daylight math.
+ *
+ * Every export is a PURE function: no I/O, no network, no globals mutated, no
+ * dependencies. The geometry follows the algorithm published by NOAA's Global
+ * Monitoring Laboratory Solar Calculator
+ * (https://gml.noaa.gov/grad/solcalc/), which is itself a simplified form of
+ * Jean Meeus, "Astronomical Algorithms" (2nd ed.). The same equations back the
+ * NOAA spreadsheet used by thousands of solar/weather tools.
+ *
+ * CONVENTIONS
+ *   lat        latitude in degrees, + to the North   (e.g. New York = 40.7128)
+ *   lon        longitude in degrees, + to the East    (e.g. New York = -74.006)
+ *   dateInput  either a JS Date (only its Y/M/D matter — see below) or a plain
+ *              object { year, month, day } with a 1-based month (1 = January).
+ *   tz         time-zone offset of the LOCAL clock from UTC, in hours
+ *              (e.g. US Eastern Standard Time = -5). Defaults to 0 (UTC).
+ *
+ * When you pass a JS Date to a DAILY function (sunrise, sunset, solarNoon,
+ * dayLengthMinutes, twilight, golden hour) only its calendar date is used, and
+ * that date is read in UTC — so `new Date('2020-06-21')` is June 21 everywhere.
+ * If you care about a specific local day near a date boundary, pass an explicit
+ * { year, month, day } object.
+ *
+ * Daily event functions return a JS Date representing the true UTC INSTANT of
+ * the event (or null when the event does not occur that day, e.g. polar night /
+ * midnight sun). To show one in local time, format it with the same `tz` you
+ * passed in, or use localClockMinutes(instant, tz).
+ *
+ * The instantaneous functions solarElevation(lat, lon, date) and
+ * solarAzimuth(lat, lon, date) take a FULL JS Date instant (date + time, in
+ * UTC) and need no tz — the instant already pins the moment.
+ */
+
+// ---------------------------------------------------------------------------
+// Trig helpers (JS Math uses radians; the NOAA formulas are written in degrees)
+// ---------------------------------------------------------------------------
+const rad = (d) => (d * Math.PI) / 180;
+const deg = (r) => (r * 180) / Math.PI;
+
+// Zenith angle (degrees from vertical) used for the standard sunrise/sunset.
+// 90.833° = 90° + 0.833°, where 0.833° accounts for mean atmospheric
+// refraction (~34') plus the Sun's apparent radius (~16') at the horizon.
+const SUNRISE_ZENITH = 90.833;
+// Civil twilight: geometric Sun centre 6° below the horizon.
+const CIVIL_ZENITH = 96;
+// "Golden hour" upper bound: Sun 6° ABOVE the horizon (soft, warm light below
+// this). Zenith = 90 - 6 = 84.
+const GOLDEN_ZENITH = 84;
+
+const MS_PER_DAY = 86400000;
+const JULIAN_UNIX_EPOCH = 2440587.5; // Julian Day of 1970-01-01T00:00:00Z
+
+// ---------------------------------------------------------------------------
+// Date-input normalisation
+// ---------------------------------------------------------------------------
+
+// Return { year, month (1-based), day } from a JS Date (read in UTC) or a
+// plain { year, month, day } object.
+function normalizeYMD(dateInput) {
+  if (dateInput instanceof Date) {
+    if (Number.isNaN(dateInput.getTime())) {
+      throw new TypeError('solar-calc: received an invalid Date');
+    }
+    return {
+      year: dateInput.getUTCFullYear(),
+      month: dateInput.getUTCMonth() + 1,
+      day: dateInput.getUTCDate(),
+    };
+  }
+  if (
+    dateInput &&
+    typeof dateInput === 'object' &&
+    Number.isFinite(dateInput.year) &&
+    Number.isFinite(dateInput.month) &&
+    Number.isFinite(dateInput.day)
+  ) {
+    return { year: dateInput.year, month: dateInput.month, day: dateInput.day };
+  }
+  throw new TypeError(
+    'solar-calc: dateInput must be a JS Date or { year, month, day }'
+  );
+}
+
+// UTC milliseconds at 00:00:00 UTC on the given calendar date.
+function utcMidnightMs(ymd) {
+  return Date.UTC(ymd.year, ymd.month - 1, ymd.day);
+}
+
+// Julian Day for a given UTC-millisecond instant.
+function julianDay(ms) {
+  return ms / MS_PER_DAY + JULIAN_UNIX_EPOCH;
+}
+
+// ---------------------------------------------------------------------------
+// Core NOAA solar quantities, all as a function of Julian centuries T since
+// the J2000.0 epoch (JD 2451545.0).
+// ---------------------------------------------------------------------------
+
+function julianCentury(jd) {
+  return (jd - 2451545) / 36525;
+}
+
+// Sun declination (degrees) and the equation of time (minutes) for century T.
+// The equation of time is (apparent solar time − mean solar time), i.e. how far
+// a real sundial runs ahead of a mean clock.
+function sunPosition(t) {
+  // Geometric mean longitude of the Sun (deg), wrapped to [0, 360).
+  let l0 = (280.46646 + t * (36000.76983 + t * 0.0003032)) % 360;
+  if (l0 < 0) l0 += 360;
+
+  // Geometric mean anomaly of the Sun (deg).
+  const m = 357.52911 + t * (35999.05029 - 0.0001537 * t);
+
+  // Eccentricity of Earth's orbit (unitless).
+  const e = 0.016708634 - t * (0.000042037 + 0.0000001267 * t);
+
+  // Sun's equation of the centre (deg).
+  const c =
+    Math.sin(rad(m)) * (1.914602 - t * (0.004817 + 0.000014 * t)) +
+    Math.sin(rad(2 * m)) * (0.019993 - 0.000101 * t) +
+    Math.sin(rad(3 * m)) * 0.000289;
+
+  const trueLong = l0 + c; // Sun's true longitude (deg)
+
+  // Apparent longitude (deg), corrected for nutation/aberration.
+  const omega = 125.04 - 1934.136 * t;
+  const lambda = trueLong - 0.00569 - 0.00478 * Math.sin(rad(omega));
+
+  // Mean obliquity of the ecliptic (deg) and its correction.
+  const seconds = 21.448 - t * (46.815 + t * (0.00059 - t * 0.001813));
+  const e0 = 23 + (26 + seconds / 60) / 60;
+  const obliq = e0 + 0.00256 * Math.cos(rad(omega));
+
+  // Sun declination (deg).
+  const declination = deg(
+    Math.asin(Math.sin(rad(obliq)) * Math.sin(rad(lambda)))
+  );
+
+  // Equation of time (minutes).
+  const y = Math.tan(rad(obliq / 2)) ** 2;
+  const eqTime =
+    4 *
+    deg(
+      y * Math.sin(2 * rad(l0)) -
+        2 * e * Math.sin(rad(m)) +
+        4 * e * y * Math.sin(rad(m)) * Math.cos(2 * rad(l0)) -
+        0.5 * y * y * Math.sin(4 * rad(l0)) -
+        1.25 * e * e * Math.sin(2 * rad(m))
+    );
+
+  return { declination, eqTime };
+}
+
+// ---------------------------------------------------------------------------
+// Public: raw astronomical quantities (handy on their own)
+// ---------------------------------------------------------------------------
+
+/**
+ * Sun declination in degrees for the given date (evaluated at local solar noon,
+ * which is more than accurate enough for a daily value). + to the North.
+ */
+function declination(dateInput, tz = 0) {
+  const ymd = normalizeYMD(dateInput);
+  const noonMs = utcMidnightMs(ymd) + (12 - tz) * 3600000;
+  return sunPosition(julianCentury(julianDay(noonMs))).declination;
+}
+
+/**
+ * Equation of time in minutes for the given date (apparent minus mean solar
+ * time). Ranges over roughly −14 … +16 minutes across a year.
+ */
+function equationOfTime(dateInput, tz = 0) {
+  const ymd = normalizeYMD(dateInput);
+  const noonMs = utcMidnightMs(ymd) + (12 - tz) * 3600000;
+  return sunPosition(julianCentury(julianDay(noonMs))).eqTime;
+}
+
+// ---------------------------------------------------------------------------
+// Daily events: solar noon plus symmetric morning/evening events at a chosen
+// zenith angle. All returned as true UTC instants (Date) or null.
+// ---------------------------------------------------------------------------
+
+// Shared daily solve. Returns UTC minutes-after-midnight for solar noon and the
+// hour-angle (deg) needed to reach `zenith`, or the reason an event is absent.
+function dailySolve(lat, lon, dateInput, tz, zenith) {
+  const ymd = normalizeYMD(dateInput);
+  const midnightMs = utcMidnightMs(ymd);
+  // Evaluate the Sun's declination / equation of time at local solar noon.
+  const noonMs = midnightMs + (12 - tz) * 3600000;
+  const { declination: decl, eqTime } = sunPosition(
+    julianCentury(julianDay(noonMs))
+  );
+
+  // UTC minutes-after-midnight of solar noon at this longitude.
+  const solarNoonMin = 720 - eqTime - 4 * lon;
+
+  // Hour angle (deg) at which the Sun's centre sits at `zenith`.
+  const cosH =
+    (Math.cos(rad(zenith)) - Math.sin(rad(lat)) * Math.sin(rad(decl))) /
+    (Math.cos(rad(lat)) * Math.cos(rad(decl)));
+
+  let hourAngle = null;
+  let absence = null; // 'below' = never reaches zenith (stays lower);
+  //                     'above' = always above zenith (never descends to it)
+  if (cosH > 1) {
+    // Sun never gets as high as `zenith` from below: for sunrise this is a
+    // polar-night day (Sun always below the horizon).
+    absence = 'below';
+  } else if (cosH < -1) {
+    // Sun never sinks to `zenith`: for sunrise this is a midnight-sun day.
+    absence = 'above';
+  } else {
+    hourAngle = deg(Math.acos(cosH));
+  }
+
+  return { midnightMs, midnightUTC: midnightMs, decl, eqTime, solarNoonMin, hourAngle, absence };
+}
+
+// Build a UTC Date from a date's UTC-midnight and a minutes-after-midnight.
+function instantFrom(midnightMs, minutes) {
+  return new Date(midnightMs + minutes * 60000);
+}
+
+/**
+ * Solar noon (Sun due south/north, highest point of the day) as a UTC instant.
+ * Always defined.
+ */
+function solarNoon(lat, lon, dateInput, tz = 0) {
+  const s = dailySolve(lat, lon, dateInput, tz, SUNRISE_ZENITH);
+  return instantFrom(s.midnightMs, s.solarNoonMin);
+}
+
+// Generic morning event (Sun rising through `zenith`).
+function morningEvent(lat, lon, dateInput, tz, zenith) {
+  const s = dailySolve(lat, lon, dateInput, tz, zenith);
+  if (s.hourAngle === null) return null;
+  return instantFrom(s.midnightMs, s.solarNoonMin - s.hourAngle * 4);
+}
+
+// Generic evening event (Sun descending through `zenith`).
+function eveningEvent(lat, lon, dateInput, tz, zenith) {
+  const s = dailySolve(lat, lon, dateInput, tz, zenith);
+  if (s.hourAngle === null) return null;
+  return instantFrom(s.midnightMs, s.solarNoonMin + s.hourAngle * 4);
+}
+
+/** Sunrise (upper limb clearing the horizon) as a UTC instant, or null. */
+function sunrise(lat, lon, dateInput, tz = 0) {
+  return morningEvent(lat, lon, dateInput, tz, SUNRISE_ZENITH);
+}
+
+/** Sunset (upper limb touching the horizon) as a UTC instant, or null. */
+function sunset(lat, lon, dateInput, tz = 0) {
+  return eveningEvent(lat, lon, dateInput, tz, SUNRISE_ZENITH);
+}
+
+/** Start of civil dawn (Sun 6° below horizon, rising) as a UTC instant, or null. */
+function civilDawn(lat, lon, dateInput, tz = 0) {
+  return morningEvent(lat, lon, dateInput, tz, CIVIL_ZENITH);
+}
+
+/** End of civil dusk (Sun 6° below horizon, setting) as a UTC instant, or null. */
+function civilDusk(lat, lon, dateInput, tz = 0) {
+  return eveningEvent(lat, lon, dateInput, tz, CIVIL_ZENITH);
+}
+
+/**
+ * End of the morning golden hour: the Sun reaching 6° elevation after sunrise.
+ * Below this the light is soft and warm. Returns a UTC instant, or null.
+ */
+function goldenHourMorningEnd(lat, lon, dateInput, tz = 0) {
+  return morningEvent(lat, lon, dateInput, tz, GOLDEN_ZENITH);
+}
+
+/**
+ * Start of the evening golden hour: the Sun descending back to 6° elevation
+ * before sunset. Returns a UTC instant, or null.
+ */
+function goldenHourEveningStart(lat, lon, dateInput, tz = 0) {
+  return eveningEvent(lat, lon, dateInput, tz, GOLDEN_ZENITH);
+}
+
+/**
+ * Length of the day (sunrise → sunset) in minutes.
+ *   - Normal day: a value in (0, 1440).
+ *   - Polar night (Sun never rises): 0.
+ *   - Midnight sun (Sun never sets): 1440.
+ */
+function dayLengthMinutes(lat, lon, dateInput, tz = 0) {
+  const s = dailySolve(lat, lon, dateInput, tz, SUNRISE_ZENITH);
+  if (s.hourAngle === null) return s.absence === 'above' ? 1440 : 0;
+  // Day length is twice the sunrise hour angle, at 4 minutes per degree.
+  return 2 * s.hourAngle * 4;
+}
+
+// ---------------------------------------------------------------------------
+// Instantaneous position for a specific moment (UTC Date instant)
+// ---------------------------------------------------------------------------
+
+// Shared instantaneous solve for a full Date instant. Returns declination,
+// hour angle (deg), and the derived elevation/azimuth.
+function instantaneous(lat, lon, date) {
+  if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+    throw new TypeError(
+      'solar-calc: solarElevation/solarAzimuth need a valid JS Date instant'
+    );
+  }
+  const ms = date.getTime();
+  const { declination: decl, eqTime } = sunPosition(
+    julianCentury(julianDay(ms))
+  );
+
+  // UTC minutes elapsed in the current UTC day.
+  const dayStart = Date.UTC(
+    date.getUTCFullYear(),
+    date.getUTCMonth(),
+    date.getUTCDate()
+  );
+  const utcMinutes = (ms - dayStart) / 60000;
+
+  // True solar time (minutes): UTC time shifted to this longitude, plus the
+  // equation of time. 4 min per degree of longitude.
+  let trueSolarTime = (utcMinutes + eqTime + 4 * lon) % 1440;
+  if (trueSolarTime < 0) trueSolarTime += 1440;
+
+  // Hour angle (deg): 0 at solar noon, negative in the morning.
+  let hourAngle = trueSolarTime / 4 - 180;
+  if (hourAngle < -180) hourAngle += 360;
+
+  // Solar zenith → elevation.
+  const cosZenith =
+    Math.sin(rad(lat)) * Math.sin(rad(decl)) +
+    Math.cos(rad(lat)) * Math.cos(rad(decl)) * Math.cos(rad(hourAngle));
+  const zenith = deg(Math.acos(Math.max(-1, Math.min(1, cosZenith))));
+  const elevation = 90 - zenith;
+
+  // Azimuth, measured clockwise from true North (0 = N, 90 = E, 180 = S).
+  let azimuth;
+  const denom = Math.cos(rad(90 - zenith)) * Math.sin(rad(lat)); // cos(elev)*sin(lat)
+  // Guard against the poles / Sun exactly overhead where azimuth is undefined.
+  const sinZen = Math.sin(rad(zenith));
+  if (Math.abs(sinZen) < 1e-9 || Math.abs(Math.cos(rad(lat))) < 1e-9) {
+    azimuth = 180; // degenerate; report due south as a stable default
+  } else {
+    let cosAz =
+      (Math.sin(rad(lat)) * Math.cos(rad(zenith)) - Math.sin(rad(decl))) /
+      (Math.cos(rad(lat)) * sinZen);
+    cosAz = Math.max(-1, Math.min(1, cosAz));
+    const az = deg(Math.acos(cosAz));
+    azimuth = hourAngle > 0 ? (az + 180) % 360 : (540 - az) % 360;
+  }
+
+  return { elevation, azimuth, declination: decl };
+}
+
+/**
+ * Solar elevation (altitude) in degrees above the horizon for a given instant.
+ * Positive = above the horizon. This is the GEOMETRIC elevation of the Sun's
+ * centre; it does not add atmospheric refraction, so values very near 0° differ
+ * from an apparent, refracted horizon by up to ~0.5°.
+ */
+function solarElevation(lat, lon, date) {
+  return instantaneous(lat, lon, date).elevation;
+}
+
+/**
+ * Solar azimuth in degrees, measured clockwise from true North
+ * (0 = N, 90 = E, 180 = S, 270 = W).
+ */
+function solarAzimuth(lat, lon, date) {
+  return instantaneous(lat, lon, date).azimuth;
+}
+
+// ---------------------------------------------------------------------------
+// Small convenience for display
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a UTC instant (as returned by the daily event functions) to
+ * minutes-after-midnight on the LOCAL clock for the given tz offset (hours).
+ * Returns a number in [0, 1440). Useful for printing "HH:MM" local times.
+ */
+function localClockMinutes(instant, tz = 0) {
+  if (instant == null) return null;
+  const ms = instant.getTime() + tz * 3600000;
+  let mins = (ms / 60000) % 1440;
+  if (mins < 0) mins += 1440;
+  return mins;
+}
+
+module.exports = {
+  // raw quantities
+  declination,
+  equationOfTime,
+  // daily events
+  solarNoon,
+  sunrise,
+  sunset,
+  dayLengthMinutes,
+  civilDawn,
+  civilDusk,
+  goldenHourMorningEnd,
+  goldenHourEveningStart,
+  // instantaneous
+  solarElevation,
+  solarAzimuth,
+  // helpers
+  localClockMinutes,
+  // exposed for advanced use / testing
+  _sunPosition: sunPosition,
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@verifyhash/solar-calc",
+  "version": "0.1.0",
+  "description": "Zero-dependency solar position & daylight math (NOAA algorithm): sunrise, sunset, solar noon, day length, elevation, azimuth, civil twilight, and golden hour for any latitude/longitude/date.",
+  "main": "index.js",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node test/solar.test.js"
+  },
+  "keywords": [
+    "solar",
+    "sunrise",
+    "sunset",
+    "solar-noon",
+    "day-length",
+    "solar-elevation",
+    "solar-azimuth",
+    "twilight",
+    "golden-hour",
+    "noaa",
+    "astronomy",
+    "zero-dependency"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verifyhash/libs.git",
+    "directory": "solar-calc"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/solar-calc#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}