ascii-side-of-the-moon 1.0.7 → 1.0.9

package/README.md

@@ -15,10 +15,20 @@ You can use this package directly from the command line:
 npx ascii-side-of-the-moon
 
 # Show moon for a specific date
-npx ascii-side-of-the-moon 2025-09-21
+npx ascii-side-of-the-moon 2025-09-19
+
+# Include a specific UTC time (quote when using spaces)
+npx ascii-side-of-the-moon "2025-09-19 21:30"
+
+# Provide an observer location (latitude/longitude in degrees, optional elevation in meters)
+# (Latitude and longitude are optional, but both must be supplied together;
+#  elevation is ignored unless lat/lon are provided.)
+npx ascii-side-of-the-moon 2025-09-19T21:30 --lat 37.7749 --lon -122.4194 --elevation 25
 ```
 
 The CLI will display the ASCII moon art along with information about the moon's phase, illumination percentage, distance, and angular diameter.
+When an observer location is supplied, the renderer also knows the altitude/azimuth
+and can draw the horizon line to show whether the moon is above or below your local horizon.
 
 ## Example
 
@@ -42,11 +52,16 @@ console.log(moonAscii);
 
 ## API Reference
 
-### `getMoonState(date: Date): MoonState`
+### `getMoonState(date: Date, observer?: ObserverLocation): MoonState`
 Returns detailed moon information including phase, size, and libration data.
+If you pass an `observer` (latitude/longitude in degrees, optional elevation in meters),
+the returned `MoonState` also contains topocentric position (altitude, azimuth, parallactic angle);
+this enables horizon-aware rendering and correct rotation for your sky.
 
 ### `renderMoon(moonState: MoonState, options?: RenderOptions): string`
 Renders the moon as ASCII art. Returns a 29×60 character string.
+`RenderOptions` now includes `showHorizon` (default `true`): set it to `false`
+if you want to suppress the horizon overlay even when altitude data is available.
 
 ### `getMoonPhase(moonState: MoonState): string`
 Returns the English name of the moon phase (e.g., "New Moon", "Waxing Crescent", "First Quarter", "Waxing Gibbous", "Full Moon", "Waning Gibbous", "Last Quarter", "Waning Crescent").
@@ -56,12 +71,31 @@ Inside of repository for `ascii-side-of-the-moon`.
 
 Render a single date:
 ```sh
+# Show moon for current date
+pnpm run render:demo
+
+# Show moon for a specific date
 pnpm run render:demo 2025-01-01
+
+# Include a specific UTC time
+pnpm run render:demo 2025-01-01 21:30
+
+# Include observer location (enables parallactic rotation and horizon display)
+pnpm run render:demo 2025-01-01 21:30 --lat 40.7128 --lon -74.0060
+
+# With elevation (meters)
+pnpm run render:demo 2025-01-01 21:30 --lat 37.7749 --lon -122.4194 --elevation 25
+
+# Just observer location (uses current date/time)
+pnpm run render:demo --lat 40.7128 --lon -74.0060
 ```
 
 Render an animation:
 ```sh
 pnpm run render:demo_animate 2025-01-01 2025-12-30
+
+# Include observer coordinates (latitude/longitude degrees, optional elevation meters)
+pnpm run render:demo_animate 2025-07-25 2025-08-23 --lat 37.7749 --lon -122.4194 --elevation 25
 ```
 
 Both demo scripts now include the moon phase name in their output.