feat(satellites): flag naked-eye visible passes

- Add Sun position and Earth-shadow checks
- Add visible to pass results
- next_iss_pass prefers a visible pass, falls back with visible: false

CHANGELOG.md

@@ -5,7 +5,9 @@
 ## Satellite pass prediction
 
 - Bisect pass rise/set to ~0.2 s and fit peak elevation with a parabola.
+- Mark passes visible from Earth-shadow and civil-twilight checks.
 - Add `getNextSatellitePass(noradId, options)` for any loaded catalog satellite.
+- `next_iss_pass` now prefers the next visible pass and falls back to the next pass with `visible: false`.
 
 ## Voice component boundaries
 

docs/CURRENT-STATE.md

@@ -2714,7 +2714,7 @@ silently demoting every later lookup for the session.
   `activeCameraCardEnabled` presentation option can publish the retained
   protected-card path. Disable tears the tier down completely.
   Coverage/viewshed semantics unchanged.
-- **Satellites**: orbit rings rotate about Earth's Z by ΔGMST every ~1s (exact inertial→ECEF compensation; no SGP4 re-runs); the tracked satellite propagates per frame with one shared epoch for dot/label/camera. Verified: ISS holds <1km perpendicular to its ring while tracked. Pass prediction (`src/data/satellitePass.js`; `getNextSatellitePass`, `getNextIssPass`) scans at 20s, bisects rise/set to ~0.2s, and fits the peak with a parabola.
+- **Satellites**: orbit rings rotate about Earth's Z by ΔGMST every ~1s (exact inertial→ECEF compensation; no SGP4 re-runs); the tracked satellite propagates per frame with one shared epoch for dot/label/camera. Verified: ISS holds <1km perpendicular to its ring while tracked. Pass prediction (`src/data/satellitePass.js`; `getNextSatellitePass`, `getNextIssPass`) scans at 20s, bisects rise/set to ~0.2s, fits the peak with a parabola, and marks a pass visible when the satellite is outside a cylindrical Earth shadow while the observer's Sun is at or below −6°. `next_iss_pass` returns the next visible pass, falling back to the next pass with `visible: false`.
 - **Space Missions (30d)**: recent launches render as bounded shared-host, horizon-occluded mission markers using Launch Library 2 v2.3 detailed records. Enabling the layer selects the unified right-side Context panel's Space Missions mode and enables the required satellite layer. Before applying its temporary dense/hidden Satellite mode, Space Missions snapshots the complete standalone Satellite parameter set and exact enabled-layer set. Disabling Space Missions from either Context or the left Data Layers rail restores those parameters and the exact prior enabled state, so a Satellite layer that was already on stays on while a mode-owned dependency returns off; enabling Satellites by itself remains independent. Selecting a mission isolates its launch-to-orbit transfer and dashed satellite orbit, fills that same panel with navigation/details, and animates a small phase-colored marker along the exact displayed Cartesian samples. Marker hit testing drill-picks through photorealistic tiles so the depth-test-free tactical dot remains reliably selectable; its text is non-interactive shared-host presentation. The selected pad is the camera's zoom pivot: the overview remains centered on its launch site, wheel zoom approaches that site instead of drifting elsewhere, and camera pitch progressively changes from global nadir to an oblique close 3D view. Its protected shared-host callout remains visible and expands to include both mission and launch-site names. `FOCUS` flies directly to a 12 km oblique frame around the selected launch site and retains the same anchored zoom/orbit behavior. `REPLAY ASCENT` resets the selected marker at the pad, frames it from an oblique third-person angle, and follows it through the mission-specific compressed ascent directly into one orbital lap at the default `1×` rate. A live `0.25×`–`4×` slider changes ascent and orbit playback speed; adjusting it mid-replay preserves the current path position and historical mission timestamp. Re-entry/recovery cannot be inserted into replay. At orbit insertion the camera smoothly pulls back over the first fifth of the orbital replay and pitches to a globe-scale nadir view while continuing to target the moving replay point. Replay Cancel, mission navigation, deselection, layer disable, and data refresh all release camera ownership. Reconstructed paths are one continuous 128-sample geodetic curve: horizontal departure begins near zero while altitude rises quickly, then the climb progressively bends toward insertion without the former hard 120 km corner. Unmatched orbit fallbacks are smooth planar inclined rings rather than longitude/latitude ground-track curves. The panel lists disclosed payload names, types, operators/manufacturers, mass, multiplicity, and destination when supplied; an empty LL2 payload collection is shown as `CLASSIFIED / MULTI-PAYLOAD`. Launcher, spacecraft, and recoverable payload stages appear in a compact stage table with serial/flight/reuse details, recovery outcome/type, destination, and final coordinates when those records exist; an empty recovery collection omits the section. Stage recoveries with confirmed coordinates use those coordinates; return-to-launch-site records use the pad; downrange-only records receive an explicitly labeled estimated endpoint along the ascent azimuth. Available endpoints render as static 2 px dashed descent/recovery paths with a fixed final-position dot and an estimated atmospheric-interface segment when applicable. The ascent is geodetically densified above the ellipsoid toward the orbit's nearest insertion point, then rendered with `ArcType.NONE`, so it neither cuts through Earth nor separates from the marker. Because LL2 does not normally supply continuous ascent telemetry, pad-to-insertion paths without upstream trajectory samples are labeled `RECONSTRUCTED ESTIMATE` / `ASCENT ESTIMATE`; only supplied trajectory samples receive the replay wording. Selected-orbit framing fits the complete ring, rear-side linework uses normal scene depth occlusion, and current distance, speed, and callout data come only from a launch-year-validated satellite match. Speed is the magnitude of the SGP4 inertial velocity vector at the same propagation epoch as position, displayed in km/s with km/h available as hover detail. Unavailable operator, site, launch-time, orbit, current-altitude, and speed values omit their detail rows instead of reserving panel space with placeholders. Newly launched payloads absent from the core operational groups use CelesTrak's cached active TLE feed as a lookup-only fallback; weak constellation-name matches are rejected. The replay callout maps compressed animation progress onto Launch Library's mission-relative timeline, showing the historical UTC date/time at the marker's current path position; unavailable timelines remain explicit. Matched live satellite positions propagate at one-second cadence and use a distinct green dot/callout with the current UTC date/time.
   When no mission is selected, the Context panel presents a scrollable newest-first roster of every launch in the rolling window, including the smaller 5 px operator-colored marker, provider, and launch date. Hovering or keyboard-focusing a row shows four compact cyan corner brackets on both that roster row and its corresponding globe dot, rotates the globe at the current zoom to center it, and gives its label declutter priority without selecting it; the globe label remains unbracketed. Selecting a roster row invokes the same mission isolation and full-orbit framing as clicking its globe marker. The replay vehicle is one screen-space SVG/CSS HUD overlay rather than separate Cesium billboard, label, and reticle graphics. It is hidden during ordinary Focus and manual close views, where the standard selected launch-site label remains visible, and exists only while ascent replay is active. Its fixed pixel scale is shared by ascent and insertion, so camera range never resizes the rocket on screen before the phase boundary. Generic Launch Library pad names are reduced to their identifying suffix, and replay timestamps use a cyan state title over unprefixed white UTC date/time values. `REPLAY ASCENT` holds the unframed cyan/white rocket at the pad for a real-time `T−10` countdown, transitions through `LIFTOFF`, and attaches six tapered cyan/white ellipse waves directly below it from liftoff through insertion to convey thrust without adding scene geometry. While replay is active, the single start button is replaced by compact Play, Pause, and Cancel icon controls. Pause freezes countdown or mission time, vehicle/stage positions, camera target, labels, and thrust-wave animation; Play resumes from that exact frame, and Cancel releases replay camera ownership. The rocket and thrust group rotates from the path's live screen-space tangent, so its nose follows the visible ascent curve while the adjacent text remains upright. The camera begins as a close oblique launch chase, then smoothly widens between roughly 120 and 420 km vehicle altitude into a higher oblique context view that keeps the moving rocket targeted while exposing the ascent bend and orbit connection. At insertion the rocket/thrust glyph is replaced by the fixed-size cyan orbit dot, which the camera follows through the existing globe-scale orbit pullback. The chase camera limits per-frame yaw changes across heading wraps so it cannot abruptly cross in front of the vehicle and make ascent read in reverse; the replay-speed slider affects mission playback but not countdown duration.
   Mission world text has no native `LabelGraphics`: overview launch markers publish at most 48 ambient candidates for a 24-winner budget, while selecting a mission clears that overview source and publishes its launch-site callout, stage re-entry annotations, live/estimated payload-position readout, and orbit annotation as protected selected-lane entries. The source retains the exact former strings and colors. Static anchors reuse the Cartesian values used to build their mission geometry; the moving payload entry reads the layer's per-frame live-position cache; catalog-backed orbit annotation positions are cached in the same one-second matrix update that realigns the orbit primitive. Keyhole edge fade, horizon culling, final collision placement, and UI exclusion are owned by the shared host. Deselect restores the bounded overview, and refresh, disable, and destroy replace or clear both mission sources.

src/data/issPass.js

@@ -17,8 +17,9 @@ export { lookAnglesAt };
  * @param {number} [options.minElevDeg=10] Elevation that defines rise and set, in degrees
  * @param {number} [options.horizonHours=24] Maximum search window in hours
  * @param {number} [options.coarseStepSec=30] Coarse search step in seconds
- * @param {number} [options.fineStepSec=5] Fine transit step in seconds for peak tracking
- * @returns {{ riseMs: number, setMs: number, maxElevDeg: number, maxElevMs: number, riseAzDeg: number } | null}
+ * @param {number} [options.fineStepSec=5] Fine transit step in seconds for peak tracking and visibility
+ * @param {boolean} [options.requireVisible=false] Require a naked-eye-visible pass
+ * @returns {{ riseMs: number, setMs: number, maxElevDeg: number, maxElevMs: number, riseAzDeg: number, visible: boolean, sunlit: boolean, observerDark: boolean } | null}
  */
 export function findNextIssPass({
   satrec,
@@ -29,6 +30,7 @@ export function findNextIssPass({
   horizonHours = 24,
   coarseStepSec = 30,
   fineStepSec = 5,
+  requireVisible = false,
 }) {
   return findNextSatellitePass({
     satrec,
@@ -39,5 +41,6 @@ export function findNextIssPass({
     horizonHours,
     coarseStepSec,
     fineStepSec,
+    requireVisible,
   });
 }

src/data/satellitePass.js

@@ -1,14 +1,17 @@
 // src/data/satellitePass.js
 /**
- * Satellite pass prediction.
- * Look angles come from SGP4; rise/set are bisected to sub-second precision
- * and the peak is refined with a parabola. Scan pattern from skylight (MIT)
- * shared/src/celestial.ts nextISSPass.
+ * Satellite pass prediction with naked-eye visibility.
+ * Look angles come from SGP4; rise/set are bisected to sub-second precision,
+ * the peak is refined with a parabola, and visibility uses the USNO
+ * low-precision Sun position with a cylindrical Earth shadow. Scan pattern from
+ * skylight (MIT) shared/src/celestial.ts nextISSPass.
  */
 import { propagate, gstime, eciToEcf, ecfToLookAngles } from 'satellite.js';
 
 const R2D = 180 / Math.PI;
 const D2R = Math.PI / 180;
+const EARTH_RADIUS_KM = 6371.0;
+const AU_KM = 149597870.7;
 
 /**
  * Observer look angles at an instant, or null when propagation fails.
@@ -16,7 +19,7 @@ const D2R = Math.PI / 180;
  * @param {number} dateMs UTC epoch timestamp in milliseconds
  * @param {number} latDeg Observer latitude in degrees [-90, 90]
  * @param {number} lonDeg Observer longitude in degrees [-180, 180]
- * @returns {{ elevDeg: number, azDeg: number } | null}
+ * @returns {{ elevDeg: number, azDeg: number, satECI: {x:number, y:number, z:number} } | null}
  */
 export function lookAnglesAt(satrec, dateMs, latDeg, lonDeg) {
   const date = new Date(dateMs);
@@ -31,9 +34,92 @@ export function lookAnglesAt(satrec, dateMs, latDeg, lonDeg) {
   return {
     elevDeg: look.elevation * R2D,
     azDeg: (((look.azimuth * R2D) % 360) + 360) % 360,
+    satECI: pos,
   };
 }
 
+/**
+ * Compute Sun position in geocentric ECI coordinates using USNO low-precision solar coordinates.
+ * Accurate to within ~1 arcminute (~0.017°) within centuries of J2000.0.
+ * @param {number} dateMs UTC epoch timestamp in milliseconds
+ * @returns {{ x: number, y: number, z: number, raDeg: number, decDeg: number }}
+ */
+export function solarPositionECI(dateMs) {
+  const JD = dateMs / 86400000 + 2440587.5;
+  const D = JD - 2451545.0; // days since J2000.0
+  const g = ((((357.529 + 0.98560028 * D) % 360) + 360) % 360) * D2R;
+  const q = (((280.459 + 0.98564736 * D) % 360) + 360) % 360;
+  const L =
+    ((((q + 1.915 * Math.sin(g) + 0.02 * Math.sin(2 * g)) % 360) + 360) % 360) *
+    D2R;
+  const e = (23.439 - 0.00000036 * D) * D2R;
+  const ra = Math.atan2(Math.cos(e) * Math.sin(L), Math.cos(L));
+  const dec = Math.asin(Math.sin(e) * Math.sin(L));
+  return {
+    x: AU_KM * Math.cos(dec) * Math.cos(ra),
+    y: AU_KM * Math.cos(dec) * Math.sin(ra),
+    z: AU_KM * Math.sin(dec),
+    raDeg: (((ra * R2D) % 360) + 360) % 360,
+    decDeg: dec * R2D,
+  };
+}
+
+/**
+ * Check whether a satellite in ECI is illuminated by the Sun (outside Earth shadow).
+ * Uses a cylindrical Earth shadow model with mean radius 6,371 km.
+ * @param {{ x: number, y: number, z: number }} satECI Satellite position in km
+ * @param {number} dateMs UTC epoch timestamp in milliseconds
+ * @returns {boolean} True if sunlit, false if in eclipse (Earth shadow)
+ */
+export function isSatelliteSunlit(satECI, dateMs) {
+  if (!satECI || typeof satECI === 'boolean') return false;
+  const sun = solarPositionECI(dateMs);
+  const sunLen = Math.hypot(sun.x, sun.y, sun.z);
+  const sx = sun.x / sunLen;
+  const sy = sun.y / sunLen;
+  const sz = sun.z / sunLen;
+  const proj = satECI.x * sx + satECI.y * sy + satECI.z * sz;
+  if (proj > 0) return true; // Sunward side of Earth
+  const dx = satECI.x - proj * sx;
+  const dy = satECI.y - proj * sy;
+  const dz = satECI.z - proj * sz;
+  return Math.hypot(dx, dy, dz) > EARTH_RADIUS_KM;
+}
+
+/**
+ * Compute the observer local solar elevation angle in degrees.
+ * @param {number} latDeg Observer latitude in degrees
+ * @param {number} lonDeg Observer longitude in degrees
+ * @param {number} dateMs UTC epoch timestamp in milliseconds
+ * @returns {number} Solar elevation in degrees [-90, 90]
+ */
+export function observerSolarElevation(latDeg, lonDeg, dateMs) {
+  const sun = solarPositionECI(dateMs);
+  const gmst = gstime(new Date(dateMs));
+  const gmstDeg = (((gmst * R2D) % 360) + 360) % 360;
+  const localHourAngleDeg =
+    (((gmstDeg + lonDeg - sun.raDeg) % 360) + 360) % 360;
+  const H = localHourAngleDeg * D2R;
+  const phi = latDeg * D2R;
+  const dec = sun.decDeg * D2R;
+  const sinElev =
+    Math.sin(phi) * Math.sin(dec) + Math.cos(phi) * Math.cos(dec) * Math.cos(H);
+  return Math.asin(Math.max(-1, Math.min(1, sinElev))) * R2D;
+}
+
+/**
+ * Check whether the observer sky is dark (civil, nautical, or astronomical twilight / night).
+ * Default threshold is -6° (civil twilight).
+ * @param {number} latDeg Observer latitude
+ * @param {number} lonDeg Observer longitude
+ * @param {number} dateMs UTC timestamp
+ * @param {number} [maxSunElevDeg=-6] Sun elevation ceiling (default -6° for civil twilight)
+ * @returns {boolean} True if sun is at or below the threshold
+ */
+export function isObserverDark(latDeg, lonDeg, dateMs, maxSunElevDeg = -6) {
+  return observerSolarElevation(latDeg, lonDeg, dateMs) <= maxSunElevDeg;
+}
+
 /**
  * Bisect the elevation threshold boundary f(t) = elev(t) - minElevDeg = 0.
  * Assumes one threshold crossing inside the bracket. 7 iterations resolve 20s to ~0.16s.
@@ -75,7 +161,7 @@ function _bisectBoundary(
 /**
  * Find the next pass of a satellite over an observer location.
  * Uses 20s coarse scanning, bisection for sub-second rise/set times,
- * and parabolic interpolation for the peak.
+ * parabolic interpolation for the peak, and optional naked-eye visibility filtering.
  *
  * @param {Object} options
  * @param {Object} options.satrec SGP4 satellite record
@@ -86,13 +172,19 @@ function _bisectBoundary(
  * @param {number} [options.horizonHours=24] Maximum search horizon in hours (default 24h)
  * @param {number} [options.coarseStepSec=20] Coarse scan step in seconds (default 20s)
  * @param {number} [options.fineStepSec=5] Fine transit step in seconds (default 5s)
+ * @param {boolean} [options.requireVisible=false] Skip passes that are not naked-eye visible
+ * @param {number} [options.maxSunElevDeg=-6] Ceiling for observer darkness (default -6° for civil twilight)
  * @returns {{
  *   riseMs: number,
  *   setMs: number,
  *   maxElevDeg: number,
  *   maxElevMs: number,
- *   riseAzDeg: number
- * } | null}
+ *   riseAzDeg: number,
+ *   visible: boolean,
+ *   sunlit: boolean,
+ *   observerDark: boolean
+ * } | null} `visible` is true when any sampled part of the pass is sunlit under a
+ *   dark sky; `sunlit` and `observerDark` describe the peak only.
  */
 export function findNextSatellitePass({
   satrec,
@@ -103,6 +195,8 @@ export function findNextSatellitePass({
   horizonHours = 24,
   coarseStepSec = 20,
   fineStepSec = 5,
+  requireVisible = false,
+  maxSunElevDeg = -6,
 }) {
   const horizonMs = fromMs + horizonHours * 3600_000;
   const coarseMs = coarseStepSec * 1000;
@@ -156,16 +250,40 @@ export function findNextSatellitePass({
     let maxElevMs = riseMs;
     let tStepPrev = riseMs;
     let setMs = null;
+    let hasVisibleSegment = false;
     let elevPrevSample = null;
     let peakLeftElev = null;
     let peakRightElev = null;
     let peakStepMs = fineMs;
 
+    // Visibility at an instant inside [riseMs, setMs], so no elevation gate
+    const checkVisibility = (tMs) => {
+      if (hasVisibleSegment) return;
+      const look = lookAnglesAt(satrec, tMs, latDeg, lonDeg);
+      if (!look) return;
+      const sunlit = isSatelliteSunlit(look.satECI, tMs);
+      const dark = isObserverDark(latDeg, lonDeg, tMs, maxSunElevDeg);
+      if (sunlit && dark) {
+        hasVisibleSegment = true;
+      }
+    };
+
+    // Check visibility at rise
+    checkVisibility(riseMs);
+
     // Transit forward in fine steps
     while (tCurr <= horizonMs) {
       const look = lookAnglesAt(satrec, tCurr, latDeg, lonDeg);
       const elev = look ? look.elevDeg : -90;
 
+      if (look) {
+        const sunlit = isSatelliteSunlit(look.satECI, tCurr);
+        const dark = isObserverDark(latDeg, lonDeg, tCurr, maxSunElevDeg);
+        if (sunlit && dark && elev >= minElevDeg) {
+          hasVisibleSegment = true;
+        }
+      }
+
       if (elev < minElevDeg && tCurr > riseMs) {
         if (peakRightElev == null && tCurr > maxElevMs) {
           peakRightElev = elev;
@@ -223,6 +341,28 @@ export function findNextSatellitePass({
       }
     }
 
+    // Sun and sky state at the peak
+    const peakLook = lookAnglesAt(satrec, refinedPeakMs, latDeg, lonDeg);
+    const peakSunlit = peakLook
+      ? isSatelliteSunlit(peakLook.satECI, refinedPeakMs)
+      : false;
+    const peakDark = isObserverDark(
+      latDeg,
+      lonDeg,
+      refinedPeakMs,
+      maxSunElevDeg,
+    );
+
+    // Check visibility at the refined peak and at set
+    checkVisibility(refinedPeakMs);
+    checkVisibility(setMs);
+
+    // Skip passes with no visible part when requireVisible is set
+    if (requireVisible && !hasVisibleSegment) {
+      searchCursor = Math.max(setMs + 1000, searchCursor + coarseMs);
+      continue;
+    }
+
     const riseLook = lookAnglesAt(satrec, riseMs, latDeg, lonDeg);
     return {
       riseMs,
@@ -230,6 +370,9 @@ export function findNextSatellitePass({
       maxElevDeg: refinedPeakElevDeg,
       maxElevMs: refinedPeakMs,
       riseAzDeg: riseLook ? riseLook.azDeg : 0,
+      visible: hasVisibleSegment,
+      sunlit: peakSunlit,
+      observerDark: peakDark,
     };
   }
 

src/data/satellitePass.test.mjs

@@ -1,8 +1,15 @@
 // src/data/satellitePass.test.mjs
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { twoline2satrec } from 'satellite.js';
-import { findNextSatellitePass, lookAnglesAt } from './satellitePass.js';
+import { twoline2satrec, propagate } from 'satellite.js';
+import {
+  findNextSatellitePass,
+  lookAnglesAt,
+  solarPositionECI,
+  isSatelliteSunlit,
+  observerSolarElevation,
+  isObserverDark,
+} from './satellitePass.js';
 
 // Canonical archived ISS TLE (epoch 2008-09-20 ~12:25 UTC).
 const L1 =
@@ -12,6 +19,107 @@ const L2 =
 const AUSTIN = { latDeg: 30.2672, lonDeg: -97.7431 };
 const FROM_MS = Date.UTC(2008, 8, 20, 12, 30, 0);
 
+test('solarPositionECI matches the Sun at J2000.0', () => {
+  // Reference: Cesium Simon1994PlanetaryPositions at 2000-01-01 12:00 UTC
+  // gives RA 281.289°, Dec -23.033°.
+  const j2000 = solarPositionECI(Date.UTC(2000, 0, 1, 12, 0, 0));
+  assert.ok(
+    Math.abs(j2000.raDeg - 281.289) < 0.05,
+    `RA ${j2000.raDeg}° within 0.05°`,
+  );
+  assert.ok(
+    Math.abs(j2000.decDeg - -23.033) < 0.05,
+    `Dec ${j2000.decDeg}° within 0.05°`,
+  );
+});
+
+test('solarPositionECI calculates reasonable solar coordinates across seasons', () => {
+  // Near Autumnal Equinox (Sept 22, 2020): declination ≈ 0°
+  const equinox = solarPositionECI(Date.UTC(2020, 8, 22, 12, 0, 0));
+  assert.ok(
+    Math.abs(equinox.decDeg) < 1.0,
+    'declination near equinox must be close to 0°',
+  );
+
+  // Near Summer Solstice (June 21, 2020): declination ≈ +23.44°
+  const solsticeSummer = solarPositionECI(Date.UTC(2020, 5, 21, 12, 0, 0));
+  assert.ok(
+    Math.abs(solsticeSummer.decDeg - 23.44) < 0.5,
+    'summer declination ≈ 23.44°',
+  );
+
+  // Near Winter Solstice (Dec 21, 2020): declination ≈ -23.44°
+  const solsticeWinter = solarPositionECI(Date.UTC(2020, 11, 21, 12, 0, 0));
+  assert.ok(
+    Math.abs(solsticeWinter.decDeg - -23.44) < 0.5,
+    'winter declination ≈ -23.44°',
+  );
+});
+
+test('observerSolarElevation distinguishes local noon from local midnight', () => {
+  // Greenwich noon on equinox: solar elevation should be close to 90 - lat
+  const greenwichNoon = observerSolarElevation(
+    51.5,
+    0,
+    Date.UTC(2020, 8, 22, 12, 0, 0),
+  );
+  assert.ok(greenwichNoon > 30, 'sun must be well above horizon at local noon');
+
+  // Greenwich midnight: solar elevation must be deeply negative
+  const greenwichMidnight = observerSolarElevation(
+    51.5,
+    0,
+    Date.UTC(2020, 8, 22, 0, 0, 0),
+  );
+  assert.ok(
+    greenwichMidnight < -20,
+    'sun must be well below horizon at midnight',
+  );
+  assert.ok(isObserverDark(51.5, 0, Date.UTC(2020, 8, 22, 0, 0, 0), -6));
+});
+
+test('isSatelliteSunlit accurately computes cylindrical umbra shadow', () => {
+  const summerDate = Date.UTC(2020, 5, 21, 12, 0, 0);
+  const sun = solarPositionECI(summerDate);
+  const sunLen = Math.hypot(sun.x, sun.y, sun.z);
+  const sx = sun.x / sunLen;
+  const sy = sun.y / sunLen;
+  const sz = sun.z / sunLen;
+
+  // Point toward the Sun: must be sunlit
+  const daysideSat = { x: 7000 * sx, y: 7000 * sy, z: 7000 * sz };
+  assert.equal(isSatelliteSunlit(daysideSat, summerDate), true);
+
+  // Point directly in Earth shadow (opposite Sun, r = 6700 km, < Earth radius offset): must be eclipsed
+  const shadowedSat = { x: -6700 * sx, y: -6700 * sy, z: -6700 * sz };
+  assert.equal(isSatelliteSunlit(shadowedSat, summerDate), false);
+
+  // Point on night side but high altitude / far perpendicular to shadow axis (> 6371 km): must be sunlit
+  const highAltSat = { x: -6700 * sx + 10000, y: -6700 * sy, z: -6700 * sz };
+  assert.equal(isSatelliteSunlit(highAltSat, summerDate), true);
+});
+
+test('isSatelliteSunlit accurately identifies SGP4 orbital shadow entry and exit', () => {
+  const satrec = twoline2satrec(L1, L2);
+  // Minute 17 after FROM_MS (1221914820000): ISS is inside Earth umbra shadow cone
+  const tShadowed = FROM_MS + 17 * 60_000;
+  const pvShadowed = propagate(satrec, new Date(tShadowed));
+  assert.equal(
+    isSatelliteSunlit(pvShadowed.position, tShadowed),
+    false,
+    'ISS must be eclipsed in Earth umbra during orbital night',
+  );
+
+  // Minute 18 after FROM_MS (1221914880000): ISS emerges from umbra into sunlight
+  const tSunlit = FROM_MS + 18 * 60_000;
+  const pvSunlit = propagate(satrec, new Date(tSunlit));
+  assert.equal(
+    isSatelliteSunlit(pvSunlit.position, tSunlit),
+    true,
+    'ISS must be illuminated upon orbital sunrise',
+  );
+});
+
 test('findNextSatellitePass resolves pass boundaries with sub-second precision', () => {
   const satrec = twoline2satrec(L1, L2);
   const pass = findNextSatellitePass({
@@ -90,6 +198,31 @@ test('findNextSatellitePass resolves pass boundaries with sub-second precision',
   assert.ok(pass.maxElevDeg >= atSet.elevDeg);
 });
 
+test('findNextSatellitePass skips non-visible passes when requireVisible is true', () => {
+  const satrec = twoline2satrec(L1, L2);
+  const geometricPass = findNextSatellitePass({
+    satrec,
+    ...AUSTIN,
+    fromMs: FROM_MS,
+    minElevDeg: 10,
+    requireVisible: false,
+  });
+  assert.ok(geometricPass);
+
+  const visiblePass = findNextSatellitePass({
+    satrec,
+    ...AUSTIN,
+    fromMs: FROM_MS,
+    minElevDeg: 10,
+    horizonHours: 72,
+    requireVisible: true,
+  });
+
+  assert.ok(visiblePass, 'expected at least one visible pass within horizon');
+  assert.equal(visiblePass.visible, true);
+  assert.ok(visiblePass.riseMs >= geometricPass.riseMs);
+});
+
 test('findNextSatellitePass samples the peak at fineStepSec', () => {
   const satrec = twoline2satrec(L1, L2);
   const opts = { satrec, ...AUSTIN, fromMs: FROM_MS, minElevDeg: 10 };

src/layers/satellites/orbits.js

@@ -140,19 +140,22 @@ export function createOrbits({ state: layerState, services, parts, source }) {
    * @param {number} options.latDeg Observer latitude
    * @param {number} options.lonDeg Observer longitude
    * @param {number} [options.minElevDeg=10] Elevation that defines rise and set, in degrees
-   * @returns {{status:'no-tle'}|{status:'none'}|{status:'ok', pass:{riseMs:number,setMs:number,maxElevDeg:number,maxElevMs:number,riseAzDeg:number}}}
+   * @param {boolean} [options.requireVisible=false] Require a naked-eye-visible pass
+   * @returns {{status:'no-tle'}|{status:'none'}|{status:'ok', pass:{riseMs:number,setMs:number,maxElevDeg:number,maxElevMs:number,riseAzDeg:number,visible?:boolean,sunlit?:boolean,observerDark?:boolean}}}
    */
 
   function getNextIssPass({
     latDeg,
     lonDeg,
     minElevDeg = 10,
+    requireVisible = false,
     fromMs = Date.now(),
   }) {
     return getNextSatellitePass(ISS_NORAD, {
       latDeg,
       lonDeg,
       minElevDeg,
+      requireVisible,
       fromMs,
     });
   }
@@ -164,13 +167,20 @@ export function createOrbits({ state: layerState, services, parts, source }) {
    * @param {number} options.latDeg Observer latitude
    * @param {number} options.lonDeg Observer longitude
    * @param {number} [options.minElevDeg=10] Elevation that defines rise and set, in degrees
+   * @param {boolean} [options.requireVisible=false] Require a naked-eye-visible pass
    * @param {number} [options.fromMs=Date.now()] Search start time in UTC milliseconds
    * @returns {{status:'no-tle'}|{status:'none'}|{status:'ok', pass:Object}}
    */
 
   function getNextSatellitePass(
     noradId,
-    { latDeg, lonDeg, minElevDeg = 10, fromMs = Date.now() },
+    {
+      latDeg,
+      lonDeg,
+      minElevDeg = 10,
+      requireVisible = false,
+      fromMs = Date.now(),
+    },
   ) {
     const id = Number(noradId);
     if (!Number.isFinite(id)) return { status: 'no-tle' };
@@ -182,6 +192,7 @@ export function createOrbits({ state: layerState, services, parts, source }) {
       lonDeg,
       fromMs,
       minElevDeg,
+      requireVisible,
     });
     return pass ? { status: 'ok', pass } : { status: 'none' };
   }

src/voice/gevActions.js

@@ -2017,7 +2017,12 @@ function nextIssPass(viewer, args) {
     lonDeg = Cesium.Math.toDegrees(carto.longitude);
   }
   const minElevDeg = Number.isFinite(args.minElevationDeg) ? args.minElevationDeg : 10;
-  const result = getNextIssPass({ latDeg, lonDeg, minElevDeg });
+  // Prefer a naked-eye-visible pass (the tool contract); otherwise report the
+  // next pass with visible: false.
+  let result = getNextIssPass({ latDeg, lonDeg, minElevDeg, requireVisible: true });
+  if (result.status === 'none') {
+    result = getNextIssPass({ latDeg, lonDeg, minElevDeg });
+  }
   if (result.status === 'no-tle') {
     return {
       ok: false,
@@ -2042,6 +2047,7 @@ function nextIssPass(viewer, args) {
     durationMin: Math.max(1, Math.round((pass.setMs - pass.riseMs) / 60000)),
     peakElevationDeg: Math.round(pass.maxElevDeg),
     riseDirection: compassDir(pass.riseAzDeg),
+    visible: Boolean(pass.visible),
   };
 }