@zendir/ui 0.2.21 → 0.3.1

package/dist/react/3d/ZenSpace3DTypes.d.ts

@@ -436,6 +436,17 @@ export interface ZenSpace3DProps {
     timeScale?: number;
     /** Auto-play on mount */
     autoPlay?: boolean;
+    /**
+     * Reference time used to convert ECI / J2000 positions into the
+     * Earth-Fixed (ECEF) frame Cesium renders. Should be the **simulation
+     * clock as a real UTC Date** (sim epoch + sim seconds) so the
+     * sub-satellite point on Earth lines up with the actual ground track.
+     *
+     * If omitted, the Cesium backend falls back to wall-clock now —
+     * geometry stays self-consistent but the ground track will drift from
+     * the engine's truth as Earth rotates.
+     */
+    referenceTime?: Date;
     /**
      * Sun direction vector for lighting and atmosphere effects
      * Typically from Zendir SDK sun position calculation
@@ -485,8 +496,24 @@ export interface ZenSpace3DProps {
     showAxisHelper?: boolean;
     /** Maneuver nodes */
     maneuverNodes?: ManeuverNode[];
-    /** Layer visibility overrides */
+    /**
+     * Render-flag layers — affect HOW objects are drawn.
+     *   `labels`   — name labels next to satellite / GS markers (default off)
+     *   `coverage` — sensor footprint ellipses + cones                (default off)
+     *   `orbits`   — historical orbit polylines                       (default on)
+     */
     layers?: Partial<LayerVisibility>;
+    /**
+     * Object-group visibility — toggle WHOLE categories on/off without
+     * unmounting the viewer. Defaults to "everything visible". Drives the
+     * upcoming `<LayerControlPanel />` — also usable directly for headless
+     * apps that want pre-set visibility.
+     */
+    visibility?: {
+        spacecraft?: boolean;
+        groundStations?: boolean;
+        celestialBodies?: boolean;
+    };
     /** Show controls panel */
     showControls?: boolean;
     /** Show timeline */

package/dist/react/3d/ZenSpace3DUtils.d.ts

@@ -1,183 +1,27 @@
-import { Vector3D, LatLonAlt, SphericalCoords, TLEData, Satellite, OrbitPath, CoverageHexGrid } from './ZenSpace3DTypes';
+import { Vector3D } from './ZenSpace3DTypes';
 
-/** Earth's radius in km */
+/** Earth's mean radius in km. */
 export declare const EARTH_RADIUS_KM = 6371;
-/** Earth's gravitational parameter (km³/s²) */
-export declare const EARTH_MU = 398600.4418;
-/** Astronomical Unit in km */
-export declare const AU_KM = 149597870.7;
-/** Degrees to radians */
+/** Degrees → radians. */
 export declare const DEG_TO_RAD: number;
-/** Radians to degrees */
+/** Radians → degrees. */
 export declare const RAD_TO_DEG: number;
-/** J2000 epoch (January 1, 2000, 12:00 TT) */
-export declare const J2000_EPOCH: Date;
-/** Seconds per day */
-export declare const SECONDS_PER_DAY = 86400;
-/** Minutes per day */
-export declare const MINUTES_PER_DAY = 1440;
-/** Scene Earth radius (render units) */
+/** Earth radius in scene units (Three.js render space). */
 export declare const SCENE_EARTH_RADIUS = 3000;
-/** Scene scale factor (km to render units) */
+/** Conversion factor: 1 km → scene units. */
 export declare const KM_TO_SCENE: number;
-/** Scene scale for Solar System (different scale) */
-export declare const SOLAR_SYSTEM_SCALE = 1;
 /**
- * Convert latitude/longitude/altitude to Cartesian (ECI-like for rendering)
- * @param lat Latitude in degrees
- * @param lon Longitude in degrees
- * @param altKm Altitude in kilometers
- * @param earthRadius Scene radius for Earth
- * @returns Cartesian coordinates
+ * Convert lat/lon/alt to a Cartesian point in scene space.
+ *
+ * Result is in *render units* (scaled by `KM_TO_SCENE`), suitable for
+ * direct use in the Three.js scene graph. For ECI→ECEF on the Cesium
+ * backend, use `Cesium.Transforms.computeTemeToPseudoFixedMatrix`.
+ *
+ * @param lat        Latitude in degrees.
+ * @param lon        Longitude in degrees.
+ * @param altKm      Altitude above Earth surface in km (default 0).
+ * @param earthRadius Scene radius for Earth (default `SCENE_EARTH_RADIUS`).
  */
 export declare function latLonAltToCartesian(lat: number, lon: number, altKm?: number, earthRadius?: number): Vector3D;
-/**
- * Convert Cartesian to latitude/longitude/altitude
- * @param position Cartesian position
- * @param earthRadius Scene radius for Earth
- * @returns Lat/Lon/Alt
- */
-export declare function cartesianToLatLonAlt(position: Vector3D, earthRadius?: number): LatLonAlt;
-/**
- * Convert Cartesian to spherical coordinates
- */
-export declare function cartesianToSpherical(position: Vector3D): SphericalCoords;
-/**
- * Convert spherical to Cartesian coordinates
- */
-export declare function sphericalToCartesian(coords: SphericalCoords): Vector3D;
-/**
- * Convert ECI (Earth-Centered Inertial) to ECEF (Earth-Centered Earth-Fixed)
- * @param eci ECI position (km)
- * @param gmst Greenwich Mean Sidereal Time (radians)
- */
-export declare function eciToEcef(eci: Vector3D, gmst: number): Vector3D;
-/**
- * Calculate Greenwich Mean Sidereal Time
- * @param date Date/time
- * @returns GMST in radians
- */
-export declare function calculateGMST(date: Date): number;
-/**
- * Convert Date to Julian Date
- */
-export declare function dateToJulianDate(date: Date): number;
-/**
- * Parse Two-Line Element set
- */
-export declare function parseTLE(line1: string, line2: string): TLEData | null;
-/**
- * Simplified SGP4 propagation
- * @param tle TLE data
- * @param minutesFromEpoch Minutes from TLE epoch
- * @returns Position in km (ECI coordinates)
- */
-export declare function propagateSGP4Simple(tle: TLEData, minutesFromEpoch: number): Vector3D;
-/**
- * Propagate satellite to specific time
- * @param satellite Satellite with TLE
- * @param time Target time
- * @returns Position in km (ECI)
- */
-export declare function propagateSatellite(satellite: Satellite, time: Date): Vector3D | null;
-/**
- * Generate orbit path for a satellite
- * @param satellite Satellite with TLE
- * @param startTime Start time
- * @param duration Duration in minutes
- * @param steps Number of steps
- */
-export declare function generateOrbitPath(satellite: Satellite, startTime: Date, duration?: number, steps?: number): OrbitPath | null;
-/**
- * Calculate if a satellite is visible from a ground station
- * @param satPos Satellite position (scene units)
- * @param gsLatLon Ground station lat/lon
- * @param minElevation Minimum elevation angle (degrees)
- */
-export declare function isVisible(satPos: Vector3D, gsLatLon: {
-    latitude: number;
-    longitude: number;
-}, minElevation?: number): boolean;
-/**
- * Calculate visibility cone vertices for rendering
- * @param gsLatLon Ground station position
- * @param minElevation Minimum elevation angle
- * @param altitude Altitude for cone apex (km)
- * @param segments Number of segments for cone circle
- */
-export declare function calculateVisibilityConeGeometry(gsLatLon: {
-    latitude: number;
-    longitude: number;
-}, minElevation?: number, altitude?: number, segments?: number): Vector3D[];
-/**
- * Generate footprint polygon for a satellite
- * @param satPos Satellite position (scene units)
- * @param minElevation Minimum elevation angle
- * @param segments Number of segments
- */
-export declare function calculateFootprint(satPos: Vector3D, minElevation?: number, segments?: number): Array<{
-    latitude: number;
-    longitude: number;
-}>;
-/**
- * Generate a hexagonal grid covering the globe
- * @param resolution Grid resolution (lower = fewer hexagons)
- */
-export declare function generateHexGrid(resolution?: number): CoverageHexGrid;
-/**
- * Update hex grid coverage values based on satellite footprints
- */
-export declare function updateHexGridCoverage(grid: CoverageHexGrid, satellites: Satellite[], time: Date): CoverageHexGrid;
-export declare function dot(a: Vector3D, b: Vector3D): number;
-export declare function cross(a: Vector3D, b: Vector3D): Vector3D;
-export declare function magnitude(v: Vector3D): number;
-export declare function normalize(v: Vector3D): Vector3D;
-export declare function subtract(a: Vector3D, b: Vector3D): Vector3D;
-export declare function add(a: Vector3D, b: Vector3D): Vector3D;
-export declare function scale(v: Vector3D, s: number): Vector3D;
-export declare function distance(a: Vector3D, b: Vector3D): number;
-export declare function lerp(a: Vector3D, b: Vector3D, t: number): Vector3D;
-/**
- * Ease-out cubic function
- */
+/** Cubic ease-out curve, used by camera fly-to animations. */
 export declare function easeOutCubic(t: number): number;
-/**
- * Ease-in-out cubic function
- */
-export declare function easeInOutCubic(t: number): number;
-/**
- * Smooth step function
- */
-export declare function smoothstep(edge0: number, edge1: number, x: number): number;
-/**
- * Interpolate between two colors
- */
-export declare function lerpColor(color1: string, color2: string, t: number): string;
-/**
- * Hex to RGB
- */
-export declare function hexToRgb(hex: string): {
-    r: number;
-    g: number;
-    b: number;
-} | null;
-/**
- * Get color from value (0-1) on a gradient scale
- */
-export declare function getGradientColor(value: number, colors?: string[]): string;
-/**
- * Format time duration as HH:MM:SS
- */
-export declare function formatDuration(seconds: number): string;
-/**
- * Format distance in appropriate units
- */
-export declare function formatDistance(km: number): string;
-/**
- * Format velocity
- */
-export declare function formatVelocity(kmPerSec: number): string;
-/**
- * Format date/time for display
- */
-export declare function formatDateTime(date: Date): string;

package/dist/react/3d/ZenSpace3DUtils.js

@@ -1,9 +1,28 @@
 const EARTH_RADIUS_KM = 6371;
 const DEG_TO_RAD = Math.PI / 180;
 const RAD_TO_DEG = 180 / Math.PI;
+const SCENE_EARTH_RADIUS = 3e3;
+const KM_TO_SCENE = SCENE_EARTH_RADIUS / EARTH_RADIUS_KM;
+function latLonAltToCartesian(lat, lon, altKm = 0, earthRadius = SCENE_EARTH_RADIUS) {
+  const r = earthRadius + altKm * KM_TO_SCENE;
+  const phi = (90 - lat) * DEG_TO_RAD;
+  const theta = (lon + 180) * DEG_TO_RAD;
+  return {
+    x: -r * Math.sin(phi) * Math.cos(theta),
+    y: r * Math.cos(phi),
+    z: r * Math.sin(phi) * Math.sin(theta)
+  };
+}
+function easeOutCubic(t) {
+  return 1 - Math.pow(1 - t, 3);
+}
 export {
   DEG_TO_RAD,
   EARTH_RADIUS_KM,
-  RAD_TO_DEG
+  KM_TO_SCENE,
+  RAD_TO_DEG,
+  SCENE_EARTH_RADIUS,
+  easeOutCubic,
+  latLonAltToCartesian
 };
 //# sourceMappingURL=ZenSpace3DUtils.js.map

package/dist/react/3d/ZenSpace3DUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"ZenSpace3DUtils.js","sources":["../../../src/react/3d/ZenSpace3DUtils.ts"],"sourcesContent":["/**\r\n * @zendir/ui - ZenSpace3D Utility Functions\r\n * \r\n * Coordinate transformations, TLE propagation, coverage calculations,\r\n * and other utilities for 3D space visualization.\r\n */\r\n\r\nimport type {\r\n  Vector3D,\r\n  LatLonAlt,\r\n  SphericalCoords,\r\n  TLEData,\r\n  Satellite,\r\n  OrbitPath,\r\n  CoverageHexGrid,\r\n  VisibilityCone as _VisibilityCone,\r\n} from './ZenSpace3DTypes';\r\n\r\n// =============================================================================\r\n// Constants\r\n// =============================================================================\r\n\r\n/** Earth's radius in km */\r\nexport const EARTH_RADIUS_KM = 6371;\r\n\r\n/** Earth's gravitational parameter (km³/s²) */\r\nexport const EARTH_MU = 398600.4418;\r\n\r\n/** Astronomical Unit in km */\r\nexport const AU_KM = 149597870.7;\r\n\r\n/** Degrees to radians */\r\nexport const DEG_TO_RAD = Math.PI / 180;\r\n\r\n/** Radians to degrees */\r\nexport const RAD_TO_DEG = 180 / Math.PI;\r\n\r\n/** J2000 epoch (January 1, 2000, 12:00 TT) */\r\nexport const J2000_EPOCH = new Date('2000-01-01T12:00:00Z');\r\n\r\n/** Seconds per day */\r\nexport const SECONDS_PER_DAY = 86400;\r\n\r\n/** Minutes per day */\r\nexport const MINUTES_PER_DAY = 1440;\r\n\r\n// =============================================================================\r\n// Scene Scale Constants\r\n// =============================================================================\r\n\r\n/** Scene Earth radius (render units) */\r\nexport const SCENE_EARTH_RADIUS = 3000;\r\n\r\n/** Scene scale factor (km to render units) */\r\nexport const KM_TO_SCENE = SCENE_EARTH_RADIUS / EARTH_RADIUS_KM;\r\n\r\n/** Scene scale for Solar System (different scale) */\r\nexport const SOLAR_SYSTEM_SCALE = 1; // 1 unit = 1 km in solar system mode\r\n\r\n// =============================================================================\r\n// Coordinate Conversions\r\n// =============================================================================\r\n\r\n/**\r\n * Convert latitude/longitude/altitude to Cartesian (ECI-like for rendering)\r\n * @param lat Latitude in degrees\r\n * @param lon Longitude in degrees\r\n * @param altKm Altitude in kilometers\r\n * @param earthRadius Scene radius for Earth\r\n * @returns Cartesian coordinates\r\n */\r\nexport function latLonAltToCartesian(\r\n  lat: number,\r\n  lon: number,\r\n  altKm: number = 0,\r\n  earthRadius: number = SCENE_EARTH_RADIUS\r\n): Vector3D {\r\n  const r = earthRadius + altKm * KM_TO_SCENE;\r\n  const phi = (90 - lat) * DEG_TO_RAD;\r\n  const theta = (lon + 180) * DEG_TO_RAD;\r\n  \r\n  return {\r\n    x: -r * Math.sin(phi) * Math.cos(theta),\r\n    y: r * Math.cos(phi),\r\n    z: r * Math.sin(phi) * Math.sin(theta),\r\n  };\r\n}\r\n\r\n/**\r\n * Convert Cartesian to latitude/longitude/altitude\r\n * @param position Cartesian position\r\n * @param earthRadius Scene radius for Earth\r\n * @returns Lat/Lon/Alt\r\n */\r\nexport function cartesianToLatLonAlt(\r\n  position: Vector3D,\r\n  earthRadius: number = SCENE_EARTH_RADIUS\r\n): LatLonAlt {\r\n  const r = Math.sqrt(position.x ** 2 + position.y ** 2 + position.z ** 2);\r\n  const lat = 90 - Math.acos(position.y / r) * RAD_TO_DEG;\r\n  const lon = Math.atan2(position.z, -position.x) * RAD_TO_DEG - 180;\r\n  const alt = (r - earthRadius) / KM_TO_SCENE;\r\n  \r\n  return { latitude: lat, longitude: lon, altitude: alt };\r\n}\r\n\r\n/**\r\n * Convert Cartesian to spherical coordinates\r\n */\r\nexport function cartesianToSpherical(position: Vector3D): SphericalCoords {\r\n  const radius = Math.sqrt(position.x ** 2 + position.y ** 2 + position.z ** 2);\r\n  const theta = Math.atan2(position.z, position.x);\r\n  const phi = Math.acos(position.y / radius);\r\n  \r\n  return { radius, theta, phi };\r\n}\r\n\r\n/**\r\n * Convert spherical to Cartesian coordinates\r\n */\r\nexport function sphericalToCartesian(coords: SphericalCoords): Vector3D {\r\n  return {\r\n    x: coords.radius * Math.sin(coords.phi) * Math.cos(coords.theta),\r\n    y: coords.radius * Math.cos(coords.phi),\r\n    z: coords.radius * Math.sin(coords.phi) * Math.sin(coords.theta),\r\n  };\r\n}\r\n\r\n/**\r\n * Convert ECI (Earth-Centered Inertial) to ECEF (Earth-Centered Earth-Fixed)\r\n * @param eci ECI position (km)\r\n * @param gmst Greenwich Mean Sidereal Time (radians)\r\n */\r\nexport function eciToEcef(eci: Vector3D, gmst: number): Vector3D {\r\n  const cosGmst = Math.cos(gmst);\r\n  const sinGmst = Math.sin(gmst);\r\n  \r\n  return {\r\n    x: eci.x * cosGmst + eci.y * sinGmst,\r\n    y: -eci.x * sinGmst + eci.y * cosGmst,\r\n    z: eci.z,\r\n  };\r\n}\r\n\r\n/**\r\n * Calculate Greenwich Mean Sidereal Time\r\n * @param date Date/time\r\n * @returns GMST in radians\r\n */\r\nexport function calculateGMST(date: Date): number {\r\n  const jd = dateToJulianDate(date);\r\n  const t = (jd - 2451545.0) / 36525.0;\r\n  \r\n  // GMST in degrees\r\n  let gmst = 280.46061837 + \r\n             360.98564736629 * (jd - 2451545.0) + \r\n             0.000387933 * t * t - \r\n             t * t * t / 38710000.0;\r\n  \r\n  // Normalize to 0-360\r\n  gmst = gmst % 360;\r\n  if (gmst < 0) gmst += 360;\r\n  \r\n  return gmst * DEG_TO_RAD;\r\n}\r\n\r\n/**\r\n * Convert Date to Julian Date\r\n */\r\nexport function dateToJulianDate(date: Date): number {\r\n  const year = date.getUTCFullYear();\r\n  const month = date.getUTCMonth() + 1;\r\n  const day = date.getUTCDate();\r\n  const hour = date.getUTCHours();\r\n  const minute = date.getUTCMinutes();\r\n  const second = date.getUTCSeconds();\r\n  \r\n  let y = year;\r\n  let m = month;\r\n  \r\n  if (m <= 2) {\r\n    y -= 1;\r\n    m += 12;\r\n  }\r\n  \r\n  const a = Math.floor(y / 100);\r\n  const b = 2 - a + Math.floor(a / 4);\r\n  \r\n  const jd = Math.floor(365.25 * (y + 4716)) +\r\n             Math.floor(30.6001 * (m + 1)) +\r\n             day + b - 1524.5 +\r\n             (hour + minute / 60 + second / 3600) / 24;\r\n  \r\n  return jd;\r\n}\r\n\r\n// =============================================================================\r\n// TLE Parsing & Propagation (Simplified SGP4)\r\n// =============================================================================\r\n\r\n/**\r\n * Parse Two-Line Element set\r\n */\r\nexport function parseTLE(line1: string, line2: string): TLEData | null {\r\n  try {\r\n    // Line 1 parsing\r\n    const epochYear = parseInt(line1.substring(18, 20));\r\n    const epochDay = parseFloat(line1.substring(20, 32));\r\n    const bstar = parseScientificNotation(line1.substring(53, 61));\r\n    \r\n    // Line 2 parsing\r\n    const inclination = parseFloat(line2.substring(8, 16));\r\n    const raan = parseFloat(line2.substring(17, 25));\r\n    const eccentricityStr = '0.' + line2.substring(26, 33);\r\n    const eccentricity = parseFloat(eccentricityStr);\r\n    const argOfPerigee = parseFloat(line2.substring(34, 42));\r\n    const meanAnomaly = parseFloat(line2.substring(43, 51));\r\n    const meanMotion = parseFloat(line2.substring(52, 63));\r\n    \r\n    // Calculate epoch date\r\n    const fullYear = epochYear < 57 ? 2000 + epochYear : 1900 + epochYear;\r\n    const epoch = new Date(Date.UTC(fullYear, 0, 1));\r\n    epoch.setTime(epoch.getTime() + (epochDay - 1) * SECONDS_PER_DAY * 1000);\r\n    \r\n    return {\r\n      line1,\r\n      line2,\r\n      epoch,\r\n      meanMotion,\r\n      eccentricity,\r\n      inclination,\r\n      raan,\r\n      argOfPerigee,\r\n      meanAnomaly,\r\n      bstar,\r\n    };\r\n  } catch (e) {\r\n    if (import.meta.env.DEV) {\r\n      console.error('Failed to parse TLE:', e);\r\n    }\r\n    return null;\r\n  }\r\n}\r\n\r\n/**\r\n * Parse TLE scientific notation (e.g., \" 12345-4\" = 0.12345e-4)\r\n */\r\nfunction parseScientificNotation(str: string): number {\r\n  const trimmed = str.trim();\r\n  if (trimmed.length === 0) return 0;\r\n  \r\n  // Find the position of the exponent sign\r\n  let mantissa: string;\r\n  let exponent: number;\r\n  \r\n  const lastSignPos = Math.max(trimmed.lastIndexOf('+'), trimmed.lastIndexOf('-'));\r\n  if (lastSignPos > 0) {\r\n    mantissa = '0.' + trimmed.substring(0, lastSignPos).replace(/[^0-9]/g, '');\r\n    exponent = parseInt(trimmed.substring(lastSignPos));\r\n  } else {\r\n    mantissa = '0.' + trimmed.replace(/[^0-9]/g, '');\r\n    exponent = 0;\r\n  }\r\n  \r\n  return parseFloat(mantissa) * Math.pow(10, exponent);\r\n}\r\n\r\n/**\r\n * Simplified SGP4 propagation\r\n * @param tle TLE data\r\n * @param minutesFromEpoch Minutes from TLE epoch\r\n * @returns Position in km (ECI coordinates)\r\n */\r\nexport function propagateSGP4Simple(tle: TLEData, minutesFromEpoch: number): Vector3D {\r\n  // Semi-major axis from mean motion\r\n  const n = tle.meanMotion * 2 * Math.PI / MINUTES_PER_DAY; // rad/min\r\n  const a = Math.pow(EARTH_MU / (n * n / 60 / 60), 1/3); // km\r\n  \r\n  // Current mean anomaly\r\n  const M = (tle.meanAnomaly + (360 * tle.meanMotion * minutesFromEpoch / MINUTES_PER_DAY)) % 360;\r\n  const M_rad = M * DEG_TO_RAD;\r\n  \r\n  // Solve Kepler's equation for eccentric anomaly (simplified Newton-Raphson)\r\n  let E = M_rad;\r\n  for (let i = 0; i < 10; i++) {\r\n    E = M_rad + tle.eccentricity * Math.sin(E);\r\n  }\r\n  \r\n  // True anomaly\r\n  const cosE = Math.cos(E);\r\n  const sinE = Math.sin(E);\r\n  const nu = Math.atan2(\r\n    Math.sqrt(1 - tle.eccentricity ** 2) * sinE,\r\n    cosE - tle.eccentricity\r\n  );\r\n  \r\n  // Distance\r\n  const r = a * (1 - tle.eccentricity * cosE);\r\n  \r\n  // Position in orbital plane\r\n  const xOrb = r * Math.cos(nu);\r\n  const yOrb = r * Math.sin(nu);\r\n  \r\n  // RAAN and inclination with simple precession\r\n  const raanRad = tle.raan * DEG_TO_RAD;\r\n  const incRad = tle.inclination * DEG_TO_RAD;\r\n  const argPeriRad = tle.argOfPerigee * DEG_TO_RAD;\r\n  \r\n  // Rotation matrices\r\n  const cosRaan = Math.cos(raanRad);\r\n  const sinRaan = Math.sin(raanRad);\r\n  const cosInc = Math.cos(incRad);\r\n  const sinInc = Math.sin(incRad);\r\n  const cosArgPeri = Math.cos(argPeriRad);\r\n  const sinArgPeri = Math.sin(argPeriRad);\r\n  \r\n  // Transform to ECI\r\n  const x = (cosRaan * cosArgPeri - sinRaan * sinArgPeri * cosInc) * xOrb +\r\n            (-cosRaan * sinArgPeri - sinRaan * cosArgPeri * cosInc) * yOrb;\r\n  const y = (sinRaan * cosArgPeri + cosRaan * sinArgPeri * cosInc) * xOrb +\r\n            (-sinRaan * sinArgPeri + cosRaan * cosArgPeri * cosInc) * yOrb;\r\n  const z = (sinArgPeri * sinInc) * xOrb + (cosArgPeri * sinInc) * yOrb;\r\n  \r\n  return { x, y, z };\r\n}\r\n\r\n/**\r\n * Propagate satellite to specific time\r\n * @param satellite Satellite with TLE\r\n * @param time Target time\r\n * @returns Position in km (ECI)\r\n */\r\nexport function propagateSatellite(satellite: Satellite, time: Date): Vector3D | null {\r\n  if (!satellite.tle) return null;\r\n  \r\n  const minutesFromEpoch = (time.getTime() - satellite.tle.epoch.getTime()) / 60000;\r\n  return propagateSGP4Simple(satellite.tle, minutesFromEpoch);\r\n}\r\n\r\n/**\r\n * Generate orbit path for a satellite\r\n * @param satellite Satellite with TLE\r\n * @param startTime Start time\r\n * @param duration Duration in minutes\r\n * @param steps Number of steps\r\n */\r\nexport function generateOrbitPath(\r\n  satellite: Satellite,\r\n  startTime: Date,\r\n  duration: number = 90,\r\n  steps: number = 180\r\n): OrbitPath | null {\r\n  if (!satellite.tle) return null;\r\n  \r\n  const points: Vector3D[] = [];\r\n  const startMinutes = (startTime.getTime() - satellite.tle.epoch.getTime()) / 60000;\r\n  \r\n  for (let i = 0; i <= steps; i++) {\r\n    const minutesFromEpoch = startMinutes + (i / steps) * duration;\r\n    const pos = propagateSGP4Simple(satellite.tle, minutesFromEpoch);\r\n    \r\n    // Convert to scene coordinates\r\n    points.push({\r\n      x: pos.x * KM_TO_SCENE,\r\n      y: pos.z * KM_TO_SCENE, // Swap Y/Z for Three.js\r\n      z: pos.y * KM_TO_SCENE,\r\n    });\r\n  }\r\n  \r\n  return {\r\n    objectId: satellite.id,\r\n    points,\r\n    timeSpan: duration * 60,\r\n    isFuture: true,\r\n    color: satellite.color || '#22d3ee',\r\n  };\r\n}\r\n\r\n// =============================================================================\r\n// Coverage & Visibility Calculations\r\n// =============================================================================\r\n\r\n/**\r\n * Calculate if a satellite is visible from a ground station\r\n * @param satPos Satellite position (scene units)\r\n * @param gsLatLon Ground station lat/lon\r\n * @param minElevation Minimum elevation angle (degrees)\r\n */\r\nexport function isVisible(\r\n  satPos: Vector3D,\r\n  gsLatLon: { latitude: number; longitude: number },\r\n  minElevation: number = 5\r\n): boolean {\r\n  const gsPos = latLonAltToCartesian(gsLatLon.latitude, gsLatLon.longitude, 0);\r\n  \r\n  // Vector from ground station to satellite\r\n  const toSat = {\r\n    x: satPos.x - gsPos.x,\r\n    y: satPos.y - gsPos.y,\r\n    z: satPos.z - gsPos.z,\r\n  };\r\n  \r\n  // Ground station \"up\" vector (normal to Earth surface)\r\n  const up = normalize(gsPos);\r\n  \r\n  // Calculate elevation angle\r\n  const elevation = 90 - Math.acos(dot(normalize(toSat), up)) * RAD_TO_DEG;\r\n  \r\n  return elevation >= minElevation;\r\n}\r\n\r\n/**\r\n * Calculate visibility cone vertices for rendering\r\n * @param gsLatLon Ground station position\r\n * @param minElevation Minimum elevation angle\r\n * @param altitude Altitude for cone apex (km)\r\n * @param segments Number of segments for cone circle\r\n */\r\nexport function calculateVisibilityConeGeometry(\r\n  gsLatLon: { latitude: number; longitude: number },\r\n  minElevation: number = 5,\r\n  altitude: number = 2000,\r\n  segments: number = 32\r\n): Vector3D[] {\r\n  const gsPos = latLonAltToCartesian(gsLatLon.latitude, gsLatLon.longitude, 0);\r\n  const vertices: Vector3D[] = [];\r\n  \r\n  // Cone apex is at ground station\r\n  vertices.push(gsPos);\r\n  \r\n  // Calculate cone opening angle\r\n  const coneAngle = (90 - minElevation) * DEG_TO_RAD;\r\n  const coneRadius = altitude * Math.tan(coneAngle);\r\n  \r\n  // Get local tangent plane vectors\r\n  const up = normalize(gsPos);\r\n  const east = normalize(cross({ x: 0, y: 1, z: 0 }, up));\r\n  const north = cross(up, east);\r\n  \r\n  // Generate cone base circle\r\n  for (let i = 0; i <= segments; i++) {\r\n    const angle = (i / segments) * Math.PI * 2;\r\n    const basePoint = {\r\n      x: gsPos.x + up.x * altitude * KM_TO_SCENE + \r\n         (east.x * Math.cos(angle) + north.x * Math.sin(angle)) * coneRadius * KM_TO_SCENE,\r\n      y: gsPos.y + up.y * altitude * KM_TO_SCENE + \r\n         (east.y * Math.cos(angle) + north.y * Math.sin(angle)) * coneRadius * KM_TO_SCENE,\r\n      z: gsPos.z + up.z * altitude * KM_TO_SCENE + \r\n         (east.z * Math.cos(angle) + north.z * Math.sin(angle)) * coneRadius * KM_TO_SCENE,\r\n    };\r\n    vertices.push(basePoint);\r\n  }\r\n  \r\n  return vertices;\r\n}\r\n\r\n/**\r\n * Generate footprint polygon for a satellite\r\n * @param satPos Satellite position (scene units)\r\n * @param minElevation Minimum elevation angle\r\n * @param segments Number of segments\r\n */\r\nexport function calculateFootprint(\r\n  satPos: Vector3D,\r\n  minElevation: number = 5,\r\n  segments: number = 36\r\n): Array<{ latitude: number; longitude: number }> {\r\n  const satLla = cartesianToLatLonAlt(satPos);\r\n  const footprint: Array<{ latitude: number; longitude: number }> = [];\r\n  \r\n  // Simplified footprint calculation\r\n  // Central angle of visibility circle\r\n  const earthAngularRadius = Math.asin(EARTH_RADIUS_KM / (EARTH_RADIUS_KM + satLla.altitude));\r\n  const elevAngle = minElevation * DEG_TO_RAD;\r\n  const nadir = Math.PI / 2 - elevAngle - earthAngularRadius;\r\n  const footprintRadius = nadir * RAD_TO_DEG;\r\n  \r\n  for (let i = 0; i < segments; i++) {\r\n    const bearing = (i / segments) * 360;\r\n    const point = destinationPoint(\r\n      satLla.latitude,\r\n      satLla.longitude,\r\n      footprintRadius * 111.32, // Approximate km per degree\r\n      bearing\r\n    );\r\n    footprint.push(point);\r\n  }\r\n  \r\n  return footprint;\r\n}\r\n\r\n/**\r\n * Calculate destination point given start, distance, and bearing\r\n */\r\nfunction destinationPoint(\r\n  lat: number,\r\n  lon: number,\r\n  distanceKm: number,\r\n  bearing: number\r\n): { latitude: number; longitude: number } {\r\n  const R = EARTH_RADIUS_KM;\r\n  const d = distanceKm / R;\r\n  const brng = bearing * DEG_TO_RAD;\r\n  const lat1 = lat * DEG_TO_RAD;\r\n  const lon1 = lon * DEG_TO_RAD;\r\n  \r\n  const lat2 = Math.asin(\r\n    Math.sin(lat1) * Math.cos(d) +\r\n    Math.cos(lat1) * Math.sin(d) * Math.cos(brng)\r\n  );\r\n  \r\n  const lon2 = lon1 + Math.atan2(\r\n    Math.sin(brng) * Math.sin(d) * Math.cos(lat1),\r\n    Math.cos(d) - Math.sin(lat1) * Math.sin(lat2)\r\n  );\r\n  \r\n  return {\r\n    latitude: lat2 * RAD_TO_DEG,\r\n    longitude: lon2 * RAD_TO_DEG,\r\n  };\r\n}\r\n\r\n// =============================================================================\r\n// Hexagonal Grid for Coverage\r\n// =============================================================================\r\n\r\n/**\r\n * Generate a hexagonal grid covering the globe\r\n * @param resolution Grid resolution (lower = fewer hexagons)\r\n */\r\nexport function generateHexGrid(resolution: number = 2): CoverageHexGrid {\r\n  const hexagons: CoverageHexGrid['hexagons'] = [];\r\n  \r\n  // Simplified hex grid generation (not true H3, but visually similar)\r\n  const latStep = 180 / (resolution * 8);\r\n  const lonStep = 360 / (resolution * 16);\r\n  \r\n  let id = 0;\r\n  for (let lat = -90 + latStep / 2; lat < 90; lat += latStep) {\r\n    // Adjust longitude step for latitude (narrower near poles)\r\n    const adjustedLonStep = lonStep / Math.cos(lat * DEG_TO_RAD);\r\n    const offset = (Math.floor((lat + 90) / latStep) % 2) * (adjustedLonStep / 2);\r\n    \r\n    for (let lon = -180 + offset; lon < 180; lon += adjustedLonStep) {\r\n      hexagons.push({\r\n        id: `hex_${id++}`,\r\n        value: 0,\r\n        center: { latitude: lat, longitude: lon },\r\n      });\r\n    }\r\n  }\r\n  \r\n  return {\r\n    resolution,\r\n    hexagons,\r\n    colorScale: { min: '#1a1a2e', max: '#00ff88' },\r\n  };\r\n}\r\n\r\n/**\r\n * Update hex grid coverage values based on satellite footprints\r\n */\r\nexport function updateHexGridCoverage(\r\n  grid: CoverageHexGrid,\r\n  satellites: Satellite[],\r\n  time: Date\r\n): CoverageHexGrid {\r\n  // Clone grid\r\n  const updatedGrid = {\r\n    ...grid,\r\n    hexagons: grid.hexagons.map(h => ({ ...h, value: 0 })),\r\n  };\r\n  \r\n  satellites.forEach(sat => {\r\n    const pos = propagateSatellite(sat, time);\r\n    if (!pos) return;\r\n    \r\n    const scenePos = {\r\n      x: pos.x * KM_TO_SCENE,\r\n      y: pos.z * KM_TO_SCENE,\r\n      z: pos.y * KM_TO_SCENE,\r\n    };\r\n    \r\n    const footprint = calculateFootprint(scenePos);\r\n    \r\n    // Check each hexagon\r\n    updatedGrid.hexagons.forEach(hex => {\r\n      const inFootprint = isPointInPolygon(hex.center, footprint);\r\n      if (inFootprint) {\r\n        hex.value = Math.min(1, hex.value + 0.2);\r\n      }\r\n    });\r\n  });\r\n  \r\n  return updatedGrid;\r\n}\r\n\r\n/**\r\n * Point-in-polygon test (simplified)\r\n */\r\nfunction isPointInPolygon(\r\n  point: { latitude: number; longitude: number },\r\n  polygon: Array<{ latitude: number; longitude: number }>\r\n): boolean {\r\n  let inside = false;\r\n  const n = polygon.length;\r\n  \r\n  for (let i = 0, j = n - 1; i < n; j = i++) {\r\n    const xi = polygon[i].longitude;\r\n    const yi = polygon[i].latitude;\r\n    const xj = polygon[j].longitude;\r\n    const yj = polygon[j].latitude;\r\n    \r\n    if (((yi > point.latitude) !== (yj > point.latitude)) &&\r\n        (point.longitude < (xj - xi) * (point.latitude - yi) / (yj - yi) + xi)) {\r\n      inside = !inside;\r\n    }\r\n  }\r\n  \r\n  return inside;\r\n}\r\n\r\n// =============================================================================\r\n// Vector Math Utilities\r\n// =============================================================================\r\n\r\nexport function dot(a: Vector3D, b: Vector3D): number {\r\n  return a.x * b.x + a.y * b.y + a.z * b.z;\r\n}\r\n\r\nexport function cross(a: Vector3D, b: Vector3D): Vector3D {\r\n  return {\r\n    x: a.y * b.z - a.z * b.y,\r\n    y: a.z * b.x - a.x * b.z,\r\n    z: a.x * b.y - a.y * b.x,\r\n  };\r\n}\r\n\r\nexport function magnitude(v: Vector3D): number {\r\n  return Math.sqrt(v.x * v.x + v.y * v.y + v.z * v.z);\r\n}\r\n\r\nexport function normalize(v: Vector3D): Vector3D {\r\n  const m = magnitude(v);\r\n  if (m === 0) return { x: 0, y: 0, z: 0 };\r\n  return { x: v.x / m, y: v.y / m, z: v.z / m };\r\n}\r\n\r\nexport function subtract(a: Vector3D, b: Vector3D): Vector3D {\r\n  return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z };\r\n}\r\n\r\nexport function add(a: Vector3D, b: Vector3D): Vector3D {\r\n  return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z };\r\n}\r\n\r\nexport function scale(v: Vector3D, s: number): Vector3D {\r\n  return { x: v.x * s, y: v.y * s, z: v.z * s };\r\n}\r\n\r\nexport function distance(a: Vector3D, b: Vector3D): number {\r\n  return magnitude(subtract(a, b));\r\n}\r\n\r\nexport function lerp(a: Vector3D, b: Vector3D, t: number): Vector3D {\r\n  return {\r\n    x: a.x + (b.x - a.x) * t,\r\n    y: a.y + (b.y - a.y) * t,\r\n    z: a.z + (b.z - a.z) * t,\r\n  };\r\n}\r\n\r\n// =============================================================================\r\n// Animation Utilities\r\n// =============================================================================\r\n\r\n/**\r\n * Ease-out cubic function\r\n */\r\nexport function easeOutCubic(t: number): number {\r\n  return 1 - Math.pow(1 - t, 3);\r\n}\r\n\r\n/**\r\n * Ease-in-out cubic function\r\n */\r\nexport function easeInOutCubic(t: number): number {\r\n  return t < 0.5\r\n    ? 4 * t * t * t\r\n    : 1 - Math.pow(-2 * t + 2, 3) / 2;\r\n}\r\n\r\n/**\r\n * Smooth step function\r\n */\r\nexport function smoothstep(edge0: number, edge1: number, x: number): number {\r\n  const t = Math.max(0, Math.min(1, (x - edge0) / (edge1 - edge0)));\r\n  return t * t * (3 - 2 * t);\r\n}\r\n\r\n// =============================================================================\r\n// Color Utilities\r\n// =============================================================================\r\n\r\n/**\r\n * Interpolate between two colors\r\n */\r\nexport function lerpColor(color1: string, color2: string, t: number): string {\r\n  const c1 = hexToRgb(color1);\r\n  const c2 = hexToRgb(color2);\r\n  \r\n  if (!c1 || !c2) return color1;\r\n  \r\n  const r = Math.round(c1.r + (c2.r - c1.r) * t);\r\n  const g = Math.round(c1.g + (c2.g - c1.g) * t);\r\n  const b = Math.round(c1.b + (c2.b - c1.b) * t);\r\n  \r\n  return `rgb(${r}, ${g}, ${b})`;\r\n}\r\n\r\n/**\r\n * Hex to RGB\r\n */\r\nexport function hexToRgb(hex: string): { r: number; g: number; b: number } | null {\r\n  const result = /^#?([a-f\\d]{2})([a-f\\d]{2})([a-f\\d]{2})$/i.exec(hex);\r\n  return result\r\n    ? {\r\n        r: parseInt(result[1], 16),\r\n        g: parseInt(result[2], 16),\r\n        b: parseInt(result[3], 16),\r\n      }\r\n    : null;\r\n}\r\n\r\n/**\r\n * Get color from value (0-1) on a gradient scale\r\n */\r\nexport function getGradientColor(\r\n  value: number,\r\n  colors: string[] = ['#1a1a2e', '#0f3460', '#16c79a', '#ff6b6b']\r\n): string {\r\n  const clampedValue = Math.max(0, Math.min(1, value));\r\n  const scaledValue = clampedValue * (colors.length - 1);\r\n  const index = Math.floor(scaledValue);\r\n  const t = scaledValue - index;\r\n  \r\n  if (index >= colors.length - 1) return colors[colors.length - 1];\r\n  \r\n  return lerpColor(colors[index], colors[index + 1], t);\r\n}\r\n\r\n// =============================================================================\r\n// Format Utilities\r\n// =============================================================================\r\n\r\n/**\r\n * Format time duration as HH:MM:SS\r\n */\r\nexport function formatDuration(seconds: number): string {\r\n  const h = Math.floor(seconds / 3600);\r\n  const m = Math.floor((seconds % 3600) / 60);\r\n  const s = Math.floor(seconds % 60);\r\n  \r\n  return `${h.toString().padStart(2, '0')}:${m.toString().padStart(2, '0')}:${s.toString().padStart(2, '0')}`;\r\n}\r\n\r\n/**\r\n * Format distance in appropriate units\r\n */\r\nexport function formatDistance(km: number): string {\r\n  if (km < 1) {\r\n    return `${(km * 1000).toFixed(0)} m`;\r\n  } else if (km < 1000) {\r\n    return `${km.toFixed(1)} km`;\r\n  } else if (km < AU_KM / 100) {\r\n    return `${(km / 1000).toFixed(2)} thousand km`;\r\n  } else {\r\n    return `${(km / AU_KM).toFixed(4)} AU`;\r\n  }\r\n}\r\n\r\n/**\r\n * Format velocity\r\n */\r\nexport function formatVelocity(kmPerSec: number): string {\r\n  return `${kmPerSec.toFixed(3)} km/s`;\r\n}\r\n\r\n/**\r\n * Format date/time for display\r\n */\r\nexport function formatDateTime(date: Date): string {\r\n  return date.toISOString().replace('T', ' ').split('.')[0] + ' UTC';\r\n}\r\n"],"names":[],"mappings":"AAuBO,MAAM,kBAAkB;AASxB,MAAM,aAAa,KAAK,KAAK;AAG7B,MAAM,aAAa,MAAM,KAAK;"}
+{"version":3,"file":"ZenSpace3DUtils.js","sources":["../../../src/react/3d/ZenSpace3DUtils.ts"],"sourcesContent":["/**\n * @zendir/ui - ZenSpace3D rendering math\n *\n * The minimal helper set needed by the live 3D backends:\n *   • Earth + scene scaling constants used by the Three.js path\n *     (`ZenSpace3D.tsx`) and the Cesium capture source\n *     (`CesiumCaptureSource.ts`)\n *   • `latLonAltToCartesian` — lat/lon/alt → render-space Cartesian\n *   • `easeOutCubic` — camera-fly-to easing\n *\n * Higher-level orbital math (TLE/SGP4 propagation, GMST, visibility cones,\n * hex-grid coverage) was removed — those weren't consumed by either\n * backend. The Cesium backend uses Cesium's own `Transforms` for\n * ECI→ECEF, and the Three.js backend draws coverage from explicit\n * `SatelliteCoverage` props rather than computing it locally.\n */\n\nimport type { Vector3D } from './ZenSpace3DTypes';\n\n// ── Constants ─────────────────────────────────────────────────────────────────\n\n/** Earth's mean radius in km. */\nexport const EARTH_RADIUS_KM = 6371;\n\n/** Degrees → radians. */\nexport const DEG_TO_RAD = Math.PI / 180;\n\n/** Radians → degrees. */\nexport const RAD_TO_DEG = 180 / Math.PI;\n\n/** Earth radius in scene units (Three.js render space). */\nexport const SCENE_EARTH_RADIUS = 3000;\n\n/** Conversion factor: 1 km → scene units. */\nexport const KM_TO_SCENE = SCENE_EARTH_RADIUS / EARTH_RADIUS_KM;\n\n// ── Coordinate conversion ─────────────────────────────────────────────────────\n\n/**\n * Convert lat/lon/alt to a Cartesian point in scene space.\n *\n * Result is in *render units* (scaled by `KM_TO_SCENE`), suitable for\n * direct use in the Three.js scene graph. For ECI→ECEF on the Cesium\n * backend, use `Cesium.Transforms.computeTemeToPseudoFixedMatrix`.\n *\n * @param lat        Latitude in degrees.\n * @param lon        Longitude in degrees.\n * @param altKm      Altitude above Earth surface in km (default 0).\n * @param earthRadius Scene radius for Earth (default `SCENE_EARTH_RADIUS`).\n */\nexport function latLonAltToCartesian(\n  lat: number,\n  lon: number,\n  altKm: number = 0,\n  earthRadius: number = SCENE_EARTH_RADIUS,\n): Vector3D {\n  const r = earthRadius + altKm * KM_TO_SCENE;\n  const phi = (90 - lat) * DEG_TO_RAD;\n  const theta = (lon + 180) * DEG_TO_RAD;\n  return {\n    x: -r * Math.sin(phi) * Math.cos(theta),\n    y: r * Math.cos(phi),\n    z: r * Math.sin(phi) * Math.sin(theta),\n  };\n}\n\n// ── Easing ────────────────────────────────────────────────────────────────────\n\n/** Cubic ease-out curve, used by camera fly-to animations. */\nexport function easeOutCubic(t: number): number {\n  return 1 - Math.pow(1 - t, 3);\n}\n"],"names":[],"mappings":"AAsBO,MAAM,kBAAkB;AAGxB,MAAM,aAAa,KAAK,KAAK;AAG7B,MAAM,aAAa,MAAM,KAAK;AAG9B,MAAM,qBAAqB;AAG3B,MAAM,cAAc,qBAAqB;AAgBzC,SAAS,qBACd,KACA,KACA,QAAgB,GAChB,cAAsB,oBACZ;AACV,QAAM,IAAI,cAAc,QAAQ;AAChC,QAAM,OAAO,KAAK,OAAO;AACzB,QAAM,SAAS,MAAM,OAAO;AAC5B,SAAO;AAAA,IACL,GAAG,CAAC,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,KAAK;AAAA,IACtC,GAAG,IAAI,KAAK,IAAI,GAAG;AAAA,IACnB,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,KAAK;AAAA,EAAA;AAEzC;AAKO,SAAS,aAAa,GAAmB;AAC9C,SAAO,IAAI,KAAK,IAAI,IAAI,GAAG,CAAC;AAC9B;"}

package/dist/react/3d/capturePngAnalysis.js

@@ -0,0 +1,42 @@
+function rgbToLuma(r, g, b) {
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+async function meanLuminanceFromPngBytes(png) {
+  var _a;
+  if (typeof createImageBitmap !== "function" || typeof document === "undefined") {
+    return 0;
+  }
+  try {
+    const blob = new Blob([png], { type: "image/png" });
+    const bmp = await createImageBitmap(blob);
+    const w = bmp.width;
+    const h = bmp.height;
+    const canvas = document.createElement("canvas");
+    const step = Math.max(1, Math.floor(Math.sqrt(w * h / 4096)));
+    canvas.width = Math.ceil(w / step);
+    canvas.height = Math.ceil(h / step);
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return 0;
+    ctx.drawImage(bmp, 0, 0, w, h, 0, 0, canvas.width, canvas.height);
+    const { data } = ctx.getImageData(0, 0, canvas.width, canvas.height);
+    let sum = 0;
+    const n = data.length / 4;
+    for (let i = 0; i < data.length; i += 4) {
+      sum += rgbToLuma(data[i], data[i + 1], data[i + 2]);
+    }
+    (_a = bmp.close) == null ? void 0 : _a.call(bmp);
+    return n > 0 ? sum / n : 0;
+  } catch {
+    return 0;
+  }
+}
+async function isPngMostlyBlack(png, threshold = 5) {
+  const m = await meanLuminanceFromPngBytes(png);
+  return m < threshold;
+}
+export {
+  isPngMostlyBlack,
+  meanLuminanceFromPngBytes,
+  rgbToLuma
+};
+//# sourceMappingURL=capturePngAnalysis.js.map

package/dist/react/3d/capturePngAnalysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capturePngAnalysis.js","sources":["../../../src/react/3d/capturePngAnalysis.ts"],"sourcesContent":["/**\r\n * Lightweight PNG analysis for capture QA (brightness / \"all black\" detection).\r\n * Used by tests and optional runtime checks — keep dependency-free (no pngjs).\r\n */\r\n\r\n/** ITU-R BT.709 luma from RGB */\r\nexport function rgbToLuma(r: number, g: number, b: number): number {\r\n  return 0.2126 * r + 0.7152 * g + 0.0722 * b;\r\n}\r\n\r\n/**\r\n * Sample mean luma of PNG bytes by drawing to a small canvas (browser / happy-dom).\r\n * Returns 0 if decode fails. For very large images, samples a grid (max ~4096 samples).\r\n */\r\nexport async function meanLuminanceFromPngBytes(png: Uint8Array): Promise<number> {\r\n  if (typeof createImageBitmap !== 'function' || typeof document === 'undefined') {\r\n    return 0;\r\n  }\r\n  try {\r\n    const blob = new Blob([png as unknown as BlobPart], { type: 'image/png' });\r\n    const bmp = await createImageBitmap(blob);\r\n    const w = bmp.width;\r\n    const h = bmp.height;\r\n    const canvas = document.createElement('canvas');\r\n    const step = Math.max(1, Math.floor(Math.sqrt((w * h) / 4096)));\r\n    canvas.width = Math.ceil(w / step);\r\n    canvas.height = Math.ceil(h / step);\r\n    const ctx = canvas.getContext('2d');\r\n    if (!ctx) return 0;\r\n    ctx.drawImage(bmp, 0, 0, w, h, 0, 0, canvas.width, canvas.height);\r\n    const { data } = ctx.getImageData(0, 0, canvas.width, canvas.height);\r\n    let sum = 0;\r\n    const n = data.length / 4;\r\n    for (let i = 0; i < data.length; i += 4) {\r\n      sum += rgbToLuma(data[i], data[i + 1], data[i + 2]);\r\n    }\r\n    bmp.close?.();\r\n    return n > 0 ? sum / n : 0;\r\n  } catch {\r\n    return 0;\r\n  }\r\n}\r\n\r\n/**\r\n * True if the image is uniformly dark (likely failed render / empty GL buffer).\r\n * Threshold is mean luma on 0–255 scale (default 5 ≈ pure black).\r\n */\r\nexport async function isPngMostlyBlack(png: Uint8Array, threshold = 5): Promise<boolean> {\r\n  const m = await meanLuminanceFromPngBytes(png);\r\n  return m < threshold;\r\n}\r\n"],"names":[],"mappings":"AAMO,SAAS,UAAU,GAAW,GAAW,GAAmB;AACjE,SAAO,SAAS,IAAI,SAAS,IAAI,SAAS;AAC5C;AAMA,eAAsB,0BAA0B,KAAkC;AAR3E;AASL,MAAI,OAAO,sBAAsB,cAAc,OAAO,aAAa,aAAa;AAC9E,WAAO;AAAA,EACT;AACA,MAAI;AACF,UAAM,OAAO,IAAI,KAAK,CAAC,GAA0B,GAAG,EAAE,MAAM,aAAa;AACzE,UAAM,MAAM,MAAM,kBAAkB,IAAI;AACxC,UAAM,IAAI,IAAI;AACd,UAAM,IAAI,IAAI;AACd,UAAM,SAAS,SAAS,cAAc,QAAQ;AAC9C,UAAM,OAAO,KAAK,IAAI,GAAG,KAAK,MAAM,KAAK,KAAM,IAAI,IAAK,IAAI,CAAC,CAAC;AAC9D,WAAO,QAAQ,KAAK,KAAK,IAAI,IAAI;AACjC,WAAO,SAAS,KAAK,KAAK,IAAI,IAAI;AAClC,UAAM,MAAM,OAAO,WAAW,IAAI;AAClC,QAAI,CAAC,IAAK,QAAO;AACjB,QAAI,UAAU,KAAK,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,OAAO,OAAO,OAAO,MAAM;AAChE,UAAM,EAAE,KAAA,IAAS,IAAI,aAAa,GAAG,GAAG,OAAO,OAAO,OAAO,MAAM;AACnE,QAAI,MAAM;AACV,UAAM,IAAI,KAAK,SAAS;AACxB,aAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK,GAAG;AACvC,aAAO,UAAU,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;AAAA,IACpD;AACA,cAAI,UAAJ;AACA,WAAO,IAAI,IAAI,MAAM,IAAI;AAAA,EAC3B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAMA,eAAsB,iBAAiB,KAAiB,YAAY,GAAqB;AACvF,QAAM,IAAI,MAAM,0BAA0B,GAAG;AAC7C,SAAO,IAAI;AACb;"}

package/dist/react/3d/index.d.ts

@@ -1,19 +1,15 @@
 /**
  * @zendir/ui - 3D Components
  *
- * ZenSpace3D uses Cesium by default when installed (optional peer); falls back to Three.js.
- * Install `cesium` for the best globe/orbit experience; otherwise Three.js is used.
- *
- * Components:
- * - ZenSpace3D: Unified 3D space visualization (Cesium default, Three.js fallback)
- * - EarthViewer: Earth-focused 3D (Three.js, legacy)
- * - SolarSystemViewer: Solar system (Three.js, legacy)
+ * `ZenSpace3D` is the single canonical 3D viewer. Cesium is used when the
+ * peer dep is installed (production path); a Three.js renderer is used
+ * otherwise. Pair it with `useSimulationScene` for live-data integration.
  */
 export { ZenSpace3D, default as ZenSpace3DDefault } from './ZenSpace3D';
 export { ZenSpace3DCesium } from './ZenSpace3DCesium';
 export type { ZenSpace3DCesiumProps } from './ZenSpace3DCesium';
 export type { ZenSpace3DProps, ZenSpace3DHandle, ViewMode, CameraMode, ObjectCategory, SpaceObject, Satellite, Debris, SpaceStation, Asteroid, TLEData, OrbitPath, ManeuverNode, VisibilityCone, SatelliteCoverage, CoverageRegion, CoverageHexGrid, OverpassInfo, OrbitDesignArc, CoverageCell, TimeState, SelectionState, CameraState, LayerVisibility, ToolType, ToolState, Vector3D, LatLonAlt, SphericalCoords, SceneConfig, SceneObject, ZenSpace3DCallbacks, } from './ZenSpace3DTypes';
-export { latLonAltToCartesian, cartesianToLatLonAlt, cartesianToSpherical, sphericalToCartesian, eciToEcef, calculateGMST, dateToJulianDate, parseTLE, propagateSGP4Simple, propagateSatellite, generateOrbitPath, isVisible, calculateVisibilityConeGeometry, calculateFootprint, generateHexGrid, updateHexGridCoverage, dot, cross, magnitude, normalize, subtract, add, scale, distance, lerp, easeOutCubic, easeInOutCubic, smoothstep, lerpColor, hexToRgb, getGradientColor, formatDuration, formatDistance, formatVelocity, formatDateTime, EARTH_RADIUS_KM, EARTH_MU, AU_KM, DEG_TO_RAD, RAD_TO_DEG, J2000_EPOCH, SCENE_EARTH_RADIUS, KM_TO_SCENE, } from './ZenSpace3DUtils';
+export { latLonAltToCartesian, easeOutCubic, EARTH_RADIUS_KM, DEG_TO_RAD, RAD_TO_DEG, SCENE_EARTH_RADIUS, KM_TO_SCENE, } from './ZenSpace3DUtils';
 export { atmosphereVertexShader, atmosphereFragmentShader, starsVertexShader, starsFragmentShader, coverageVertexShader, coverageFragmentShader, visibilityConeVertexShader, visibilityConeFragmentShader, orbitLineVertexShader, orbitLineFragmentShader, objectGlowVertexShader, objectGlowFragmentShader, selectionRingVertexShader, selectionRingFragmentShader, terminatorVertexShader, terminatorFragmentShader, gridVertexShader, gridFragmentShader, planetRingVertexShader, planetRingFragmentShader, debrisVertexShader, debrisFragmentShader, createAtmosphereUniforms, createStarsUniforms, createVisibilityConeUniforms, } from './ZenSpace3DShaders';
 export { createCesiumCaptureSource, ecefMetersToSdkPosition, eulerXyzToHpr, ecefEulerXyzToHpr, computeDofBlurPx } from './CesiumCaptureSource';
 export type { CesiumCaptureSourceOptions, CesiumCaptureSourceHandle } from './CesiumCaptureSource';
@@ -21,7 +17,5 @@ export type { CesiumCaptureSourceOptions, CesiumCaptureSourceHandle } from './Ce
 export { rgbToLuma, meanLuminanceFromPngBytes, isPngMostlyBlack } from './capturePngAnalysis';
 export { loadThree, isThreeLoaded } from './threeLoader';
 export type { ThreeModule, OrbitControlsType } from './threeLoader';
-export { EarthViewer } from './EarthViewer';
-export type { EarthViewerProps } from './EarthViewer';
-export { SolarSystemViewer } from './SolarSystemViewer';
-export type { SolarSystemViewerProps, PlanetPosition } from './SolarSystemViewer';
+export { useSimulationScene } from '../hooks/useSimulationScene';
+export type { CelestialBody, PositionTickDiag, SimulationSceneClient, SimulationSceneObject, StructureDiag, UseSimulationSceneOptions, UseSimulationSceneResult, } from '../hooks/useSimulationScene';

package/dist/react/3d/index.js

@@ -0,0 +1,57 @@
+import { ZenSpace3D, ZenSpace3D as ZenSpace3D2 } from "./ZenSpace3D.js";
+import { ZenSpace3DCesium } from "./ZenSpace3DCesium.js";
+import { DEG_TO_RAD, EARTH_RADIUS_KM, KM_TO_SCENE, RAD_TO_DEG, SCENE_EARTH_RADIUS, easeOutCubic, latLonAltToCartesian } from "./ZenSpace3DUtils.js";
+import { atmosphereFragmentShader, atmosphereVertexShader, coverageFragmentShader, coverageVertexShader, createAtmosphereUniforms, createStarsUniforms, createVisibilityConeUniforms, debrisFragmentShader, debrisVertexShader, gridFragmentShader, gridVertexShader, objectGlowFragmentShader, objectGlowVertexShader, orbitLineFragmentShader, orbitLineVertexShader, planetRingFragmentShader, planetRingVertexShader, selectionRingFragmentShader, selectionRingVertexShader, starsFragmentShader, starsVertexShader, terminatorFragmentShader, terminatorVertexShader, visibilityConeFragmentShader, visibilityConeVertexShader } from "./ZenSpace3DShaders.js";
+import { computeDofBlurPx, createCesiumCaptureSource, ecefEulerXyzToHpr, ecefMetersToSdkPosition, eulerXyzToHpr } from "./CesiumCaptureSource.js";
+import { isPngMostlyBlack, meanLuminanceFromPngBytes, rgbToLuma } from "./capturePngAnalysis.js";
+import { isThreeLoaded, loadThree } from "./threeLoader.js";
+import { useSimulationScene } from "../hooks/useSimulationScene.js";
+export {
+  DEG_TO_RAD,
+  EARTH_RADIUS_KM,
+  KM_TO_SCENE,
+  RAD_TO_DEG,
+  SCENE_EARTH_RADIUS,
+  ZenSpace3D,
+  ZenSpace3DCesium,
+  ZenSpace3D2 as ZenSpace3DDefault,
+  atmosphereFragmentShader,
+  atmosphereVertexShader,
+  computeDofBlurPx,
+  coverageFragmentShader,
+  coverageVertexShader,
+  createAtmosphereUniforms,
+  createCesiumCaptureSource,
+  createStarsUniforms,
+  createVisibilityConeUniforms,
+  debrisFragmentShader,
+  debrisVertexShader,
+  easeOutCubic,
+  ecefEulerXyzToHpr,
+  ecefMetersToSdkPosition,
+  eulerXyzToHpr,
+  gridFragmentShader,
+  gridVertexShader,
+  isPngMostlyBlack,
+  isThreeLoaded,
+  latLonAltToCartesian,
+  loadThree,
+  meanLuminanceFromPngBytes,
+  objectGlowFragmentShader,
+  objectGlowVertexShader,
+  orbitLineFragmentShader,
+  orbitLineVertexShader,
+  planetRingFragmentShader,
+  planetRingVertexShader,
+  rgbToLuma,
+  selectionRingFragmentShader,
+  selectionRingVertexShader,
+  starsFragmentShader,
+  starsVertexShader,
+  terminatorFragmentShader,
+  terminatorVertexShader,
+  useSimulationScene,
+  visibilityConeFragmentShader,
+  visibilityConeVertexShader
+};
+//# sourceMappingURL=index.js.map

package/dist/react/3d/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}

package/dist/react/3d/threeLoader.js

@@ -0,0 +1,22 @@
+let loadPromise = null;
+async function loadThree() {
+  if (loadPromise) {
+    return loadPromise;
+  }
+  loadPromise = (async () => {
+    const [THREE, { OrbitControls }] = await Promise.all([
+      import("three"),
+      import("three/examples/jsm/controls/OrbitControls.js")
+    ]);
+    return { THREE, OrbitControls };
+  })();
+  return loadPromise;
+}
+function isThreeLoaded() {
+  return loadPromise !== null;
+}
+export {
+  isThreeLoaded,
+  loadThree
+};
+//# sourceMappingURL=threeLoader.js.map

package/dist/react/3d/threeLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"threeLoader.js","sources":["../../../src/react/3d/threeLoader.ts"],"sourcesContent":["/**\r\n * Shared Three.js loader\r\n * \r\n * Ensures only one instance of Three.js is loaded across all 3D components.\r\n * This prevents the \"Multiple instances of Three.js being imported\" warning.\r\n */\r\n\r\nexport type ThreeModule = typeof import('three');\r\nexport type OrbitControlsType = typeof import('three/examples/jsm/controls/OrbitControls.js').OrbitControls;\r\n\r\ninterface ThreeLoaderResult {\r\n  THREE: ThreeModule;\r\n  OrbitControls: OrbitControlsType;\r\n}\r\n\r\n// Cached promise to ensure single load\r\nlet loadPromise: Promise<ThreeLoaderResult> | null = null;\r\n\r\n/**\r\n * Load Three.js and OrbitControls\r\n * Returns cached instance if already loaded\r\n */\r\nexport async function loadThree(): Promise<ThreeLoaderResult> {\r\n  if (loadPromise) {\r\n    return loadPromise;\r\n  }\r\n\r\n  loadPromise = (async () => {\r\n    const [THREE, { OrbitControls }] = await Promise.all([\r\n      import('three'),\r\n      import('three/examples/jsm/controls/OrbitControls.js'),\r\n    ]);\r\n    \r\n    return { THREE, OrbitControls };\r\n  })();\r\n\r\n  return loadPromise;\r\n}\r\n\r\n/**\r\n * Check if Three.js is already loaded\r\n */\r\nexport function isThreeLoaded(): boolean {\r\n  return loadPromise !== null;\r\n}\r\n"],"names":[],"mappings":"AAgBA,IAAI,cAAiD;AAMrD,eAAsB,YAAwC;AAC5D,MAAI,aAAa;AACf,WAAO;AAAA,EACT;AAEA,iBAAe,YAAY;AACzB,UAAM,CAAC,OAAO,EAAE,cAAA,CAAe,IAAI,MAAM,QAAQ,IAAI;AAAA,MACnD,OAAO,OAAO;AAAA,MACd,OAAO,8CAA8C;AAAA,IAAA,CACtD;AAED,WAAO,EAAE,OAAO,cAAA;AAAA,EAClB,GAAA;AAEA,SAAO;AACT;AAKO,SAAS,gBAAyB;AACvC,SAAO,gBAAgB;AACzB;"}

package/dist/react/astro/ClassificationBanner.js

@@ -1,7 +1,7 @@
 import { jsx } from "react/jsx-runtime";
 import { memo } from "react";
-import { classNames } from "../utils/index.js";
 import { useTheme } from "../theme/ThemeProvider.js";
+import { classNames } from "../utils/index.js";
 const CLASSIFICATION_STYLES = {
   unclassified: {
     bg: "#007a33",

package/dist/react/astro/GlobalStatusBar.js

@@ -1,7 +1,7 @@
 import { jsxs, jsx } from "react/jsx-runtime";
 import { memo } from "react";
-import { safeAccentText, classNames } from "../utils/index.js";
 import { useTheme } from "../theme/ThemeProvider.js";
+import { safeAccentText, classNames } from "../utils/index.js";
 const GlobalStatusBar = memo(function GlobalStatusBar2({
   appName = "Zendir",
   appDomain,

package/dist/react/astro/MissionClock.js

@@ -1,7 +1,7 @@
 import { jsxs, jsx } from "react/jsx-runtime";
 import { memo, useState, useMemo, useCallback, useEffect } from "react";
-import { tabularNumsStyle, classNames } from "../utils/index.js";
 import { useTheme } from "../theme/ThemeProvider.js";
+import { tabularNumsStyle, classNames } from "../utils/index.js";
 function formatMET(ms, showMilliseconds = false) {
   const totalSeconds = Math.floor(Math.abs(ms) / 1e3);
   const days = Math.floor(totalSeconds / 86400);
@@ -342,7 +342,7 @@ const MissionClock = memo(function MissionClock2({
     }
   );
 });
-memo(function SimpleTimer2({
+const SimpleTimer = memo(function SimpleTimer2({
   label,
   timestamp,
   direction = "countdown",
@@ -359,7 +359,7 @@ memo(function SimpleTimer2({
   const timer = { label, timestamp, direction, status, showDays };
   return /* @__PURE__ */ jsx("div", { className: classNames("zendir-simple-timer", className), children: /* @__PURE__ */ jsx(TimerDisplay, { timer, currentTime: now, tokens }) });
 });
-memo(function MissionElapsedTime2({
+const MissionElapsedTime = memo(function MissionElapsedTime2({
   launchTime,
   showMilliseconds = false,
   className = "",
@@ -378,7 +378,7 @@ memo(function MissionElapsedTime2({
     }
   );
 });
-memo(function SimulationClock2({
+const SimulationClock = memo(function SimulationClock2({
   epoch,
   elapsedSeconds = 0,
   timeScale = 1,
@@ -406,6 +406,9 @@ memo(function SimulationClock2({
   );
 });
 export {
-  MissionClock
+  MissionClock,
+  MissionElapsedTime,
+  SimpleTimer,
+  SimulationClock
 };
 //# sourceMappingURL=MissionClock.js.map