timely-calendar 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6828a89cb80defec08b9eadaa1e03cf98e45e90d01efe6770423be86f14d8692
+  data.tar.gz: c0857481b8a83267cd5289111e333a07d62c5cebf59a7d509e4a0ddceac80346
+SHA512:
+  metadata.gz: c62100cb41044387038866e90e8061061be47c1c3e79c77771d60880133ea63312f325cc66084dddb905594f6951535b9cef98383e10386882836a63ff68a76e
+  data.tar.gz: ce4f9e135b9c64afe3c6a195a8da0f2f3dd688a523051e31dd42af0764181f17710504d805ead890271b44c9660227cab6fe1986c98535fabcf0d4d879fcfc40

data/.gitignore

@@ -0,0 +1,39 @@
+# Timely data
+~/.timely/
+*.db
+*.db-shm
+*.db-wal
+
+# Secrets and credentials
+.env
+.env.*
+*.pem
+*.key
+credentials.json
+token.json
+*_secret*
+*_token*
+
+# Ruby
+*.gem
+*.rbc
+/pkg/
+/tmp/
+
+# Editor
+*.swp
+*.swo
+*~
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude
+CLAUDE.md
+.claude/
+
+# Logs
+*.log

data/CLAUDE.md

@@ -0,0 +1,95 @@
+# CLAUDE.md - Development Notes for Timely
+
+## Project Vision
+
+**Timely** - Terminal calendar companion to Heathrow.
+
+A TUI calendar application built on rcurses, following the same patterns as Heathrow. View, navigate, and manage calendars with month, week, day, and year views.
+
+## Architecture
+
+Built on rcurses (Ruby TUI library). Same pane layout as Heathrow and RTFM.
+
+### File Structure
+```
+timely/
+  bin/timely              # Entry point
+  lib/timely.rb           # Module loader
+  lib/timely/
+    version.rb            # Version constant
+    database.rb           # SQLite database (events, calendars, settings)
+    config.rb             # YAML config manager (~/.timely/config.yml)
+    event.rb              # Event model
+    astronomy.rb          # Moon phase calculations
+    ui/
+      panes.rb            # Pane layout (top, left, right, bottom)
+      application.rb      # Main app class, input loop, rendering
+      views/
+        month.rb          # Month calendar grid
+        year.rb           # 12 mini-months
+        week.rb           # 7-column hourly grid
+        day.rb            # 30-min time slots
+    sources/              # Calendar source plugins (future)
+    sync/                 # Sync engines (future)
+  docs/                   # Documentation
+```
+
+### Key Bindings
+- h/l or LEFT/RIGHT: navigate days/months
+- j/k or DOWN/UP: navigate weeks/hours
+- 1-6: switch views (year, quarter, month, week, workweek, day)
+- T: go to today
+- g: go to specific date
+- n: new event (placeholder)
+- w: cycle pane width
+- B: toggle border
+- q: quit
+
+## Critical rcurses Notes
+
+### Key Input
+rcurses returns special keys as STRINGS:
+- "UP", "DOWN", "LEFT", "RIGHT"
+- "ENTER", "ESC", "SPACE"
+- "PgUP", "PgDOWN", "HOME", "END"
+- "BACK" (backspace)
+
+### Pane API
+- `Rcurses::Pane.new(x, y, w, h, fg, bg)` - create pane
+- `pane.text = string` then `pane.refresh` - set and display content
+- `pane.ask(prompt, default)` - get user input
+- `pane.border = true/false`
+- `pane.ix = 0` - scroll position
+
+### String Extensions
+- `"text".fg(color)` - foreground color (256-color int)
+- `"text".bg(color)` - background color
+- `"text".b` - bold
+- `"text".u` - underline
+- `"text".r` - reverse video
+
+### Initialization
+- Call `Rcurses.init!` before anything
+- Terminal size: `IO.console.winsize` returns `[height, width]`
+- Flush stdin: `$stdin.getc while $stdin.wait_readable(0)`
+
+### Rules
+- No raw ANSI codes; use rcurses methods only
+- Use `require 'rcurses'` (the gem)
+- All dates use Ruby's Date class
+- All times stored as Unix timestamps in DB
+
+## Current Status
+
+**Phase 0:** Foundation (complete)
+- Core architecture, database, config
+- Month, week, day, year views
+- Moon phase display
+- Navigation and view switching
+
+**Future Phases:**
+1. CalDAV sync (Google Calendar, iCloud, etc.)
+2. Event creation and editing
+3. Recurring events
+4. Weather integration
+5. Notifications and reminders

data/README.md

@@ -0,0 +1,188 @@
+# Timely
+
+<img src="img/timely.svg" align="right" width="150">
+
+**Your terminal calendar. Where time meets the stars.**
+
+![Ruby](https://img.shields.io/badge/language-Ruby-red) [![Gem Version](https://badge.fury.io/rb/timely-calendar.svg)](https://badge.fury.io/rb/timely-calendar) ![Unlicense](https://img.shields.io/badge/license-Unlicense-green) [![Heathrow](https://img.shields.io/badge/companion-Heathrow-blue)](https://github.com/isene/heathrow) ![Stay Amazing](https://img.shields.io/badge/Stay-Amazing-important)
+
+A unified TUI calendar that brings Google Calendar, Outlook/365, and local events into one terminal interface. Built on [rcurses](https://github.com/isene/rcurses), companion to [Heathrow](https://github.com/isene/heathrow).
+
+## Why Timely?
+
+Google Calendar in a browser tab. Outlook in another. Work meetings in Teams. Personal events on your phone. Sound familiar?
+
+Timely puts everything in one terminal view with moon phases, planet visibility, weather, and full keyboard control.
+
+## Features
+
+**Calendar Sources:**
+- Google Calendar (OAuth2, full read/write/RSVP)
+- Microsoft Outlook/365 (device code auth, Graph API)
+- ICS file import with RRULE recurring event expansion
+- Local events with create/edit/delete
+
+**Three-Pane Layout:**
+- **Top:** Horizontal month strip with week numbers and event markers
+- **Middle:** Selected week with half-hour time slots and all-day events
+- **Bottom:** Event details with organizer, attendees, description
+
+**Astronomy:**
+- Moon phases with emoji symbols and illumination percentage
+- Visible planet indicators (Mercury through Saturn) via [ruby-ephemeris](https://github.com/isene/ephemeris)
+- Sunrise/sunset times
+- Solstices, equinoxes, meteor shower peak dates
+
+**Weather:**
+- 7-day forecast from met.no (free, no API key)
+- Temperature and conditions shown above each day column
+
+**Integration:**
+- Bidirectional with [Heathrow](https://github.com/isene/heathrow) (Z key sends calendar invite to Timely, r replies via Heathrow)
+- ICS auto-import from `~/.timely/incoming/`
+- Desktop notifications via notify-send (libnotify)
+- Cross-source deduplication (no duplicates from ICS + Google)
+
+**UI:**
+- Visual 256-color picker for all colors
+- Calendar manager (toggle, recolor, remove calendars)
+- Preferences popup for colors, work hours, defaults
+- Scrollable event detail popup
+- Weekend colors (Saturday orange, Sunday red)
+
+## Installation
+
+```bash
+gem install timely-calendar
+```
+
+### Requirements
+
+- Ruby >= 2.7
+- [rcurses](https://github.com/isene/rcurses) gem (>= 5.0)
+- sqlite3 gem (>= 1.4)
+- Optional: [ruby-ephemeris](https://github.com/isene/ephemeris) for planet data
+- Optional: notify-send for desktop notifications
+
+## Quick Start
+
+```bash
+timely
+```
+
+### Connect Google Calendar
+
+1. Press `G`, enter your Google email
+2. Credentials: place your OAuth2 JSON + refresh token in the configured `safe_dir`
+   (default: `~/.config/timely/credentials/`)
+3. Requires both `https://mail.google.com/` and `https://www.googleapis.com/auth/calendar` scopes
+
+### Connect Outlook/365
+
+1. Register an app in [Azure Portal](https://portal.azure.com/) > App Registrations
+2. Add `Calendars.ReadWrite` and `offline_access` (delegated) permissions
+3. Enable "Allow public client flows" in Authentication
+4. Press `O` in Timely, enter the client ID and tenant ID
+5. Follow the device code flow (visit URL, enter code)
+
+## Key Bindings
+
+### Navigation
+| Key | Action |
+|-----|--------|
+| `d` / `RIGHT` | Next day |
+| `D` / `LEFT` | Previous day |
+| `w` / `W` | Next / previous week |
+| `m` / `M` | Next / previous month |
+| `y` / `Y` | Next / previous year |
+| `UP` / `DOWN` | Select time slot (scrolls) |
+| `PgUp` / `PgDn` | Jump 10 time slots |
+| `HOME` | Top (all-day area) |
+| `END` | Bottom (23:30) |
+| `e` / `E` | Jump to next / previous event |
+| `t` | Go to today |
+| `g` | Go to date (yyyy-mm-dd, Mar, 21, 2026) |
+
+### Events
+| Key | Action |
+|-----|--------|
+| `n` | New event |
+| `ENTER` | Edit event |
+| `x` / `DEL` | Delete event |
+| `v` | View event details (scrollable popup) |
+| `a` | Accept invite (pushes RSVP to Google/Outlook) |
+| `Ctrl-Y` | Copy event to clipboard |
+| `r` | Reply via Heathrow |
+
+### Sources & Settings
+| Key | Action |
+|-----|--------|
+| `i` | Import ICS file |
+| `G` | Setup Google Calendar |
+| `O` | Setup Outlook/365 |
+| `S` | Sync now (background) |
+| `C` | Calendar manager |
+| `P` | Preferences |
+| `?` | Help |
+| `q` | Quit |
+
+## Configuration
+
+Config file: `~/.timely/config.yml`
+
+```yaml
+location:
+  lat: 59.9139
+  lon: 10.7522
+timezone_offset: 1
+work_hours:
+  start: 8
+  end: 17
+week_starts_on: monday
+default_view: month
+default_calendar: 1
+
+google:
+  safe_dir: ~/.config/timely/credentials
+  sync_interval: 300
+
+outlook:
+  client_id: ''
+  tenant_id: common
+
+notifications:
+  enabled: true
+  default_alarm: 15
+
+colors:
+  selected_bg_a: 235
+  selected_bg_b: 234
+  alt_bg_a: 233
+  alt_bg_b: 0
+  current_month_bg: 233
+  saturday: 208
+  sunday: 167
+  today_fg: 232
+  today_bg: 246
+  slot_selected_bg: 237
+  info_bg: 235
+  status_bg: 235
+```
+
+## Heathrow Integration
+
+Timely is the calendar companion to [Heathrow](https://github.com/isene/heathrow), the unified messaging TUI.
+
+**From Heathrow:** Press `Z` on a calendar invite email to open it in Timely. The ICS data is auto-imported and Timely jumps to the event date.
+
+**From Timely:** Press `r` on an event to compose a reply via Heathrow.
+
+**Auto-import:** Drop `.ics` files in `~/.timely/incoming/` and they're imported on next Timely startup.
+
+## License
+
+Released into the Public Domain ([Unlicense](LICENSE)).
+
+## Author
+
+[Geir Isene](https://isene.com) with [Claude Code](https://claude.ai/claude-code)

data/bin/timely

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Timely - Terminal Calendar
+# A TUI calendar application built on rcurses
+# Author: Geir Isene with Claude Code
+# License: Public Domain
+
+CRASH_LOG = '/tmp/timely-crash.log'
+
+require_relative '../lib/timely'
+
+begin
+  app = Timely::Application.new
+  app.run
+rescue Interrupt
+  # Restore terminal
+  system('stty sane 2>/dev/null')
+  print "\e[?25h\e[0m\e[2J\e[H"
+  $stdout.flush
+  exit 0
+rescue => e
+  # Log full crash details
+  crash = "#{Time.now.strftime('%Y-%m-%d %H:%M:%S')} CRASH in #{e.backtrace&.first}\n"
+  crash << "  #{e.class}: #{e.message}\n"
+  crash << "  Backtrace:\n"
+  e.backtrace&.first(20)&.each { |l| crash << "    #{l}\n" }
+  crash << "\n"
+  File.write(CRASH_LOG, crash, mode: 'a')
+
+  # Restore terminal
+  system('stty sane 2>/dev/null')
+  print "\e[?25h\e[0m\e[2J\e[H"
+  $stdout.flush
+
+  loc = e.backtrace&.first&.sub(/^.*lib\/timely\//, '')
+  $stderr.puts "Timely crashed: #{e.class}: #{e.message}"
+  $stderr.puts "  at #{loc}"
+  $stderr.puts "  Full log: #{CRASH_LOG}"
+  exit 1
+end

data/img/timely.svg

@@ -0,0 +1,111 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#0a0a1a"/>
+      <stop offset="100%" style="stop-color:#1a1a3e"/>
+    </linearGradient>
+    <linearGradient id="face-glow" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#3a7bd5"/>
+      <stop offset="100%" style="stop-color:#1a4a8a"/>
+    </linearGradient>
+    <linearGradient id="hand-glow" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#e8d9a0"/>
+      <stop offset="100%" style="stop-color:#c08040"/>
+    </linearGradient>
+    <radialGradient id="moon-glow" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" style="stop-color:#ffffcc;stop-opacity:0.3"/>
+      <stop offset="100%" style="stop-color:#ffffcc;stop-opacity:0"/>
+    </radialGradient>
+  </defs>
+
+  <style>
+    @keyframes tick { 0% { transform: rotate(0deg); } 100% { transform: rotate(360deg); } }
+    @keyframes pulse { 0%,100% { opacity: 0.4; } 50% { opacity: 0.9; } }
+    @keyframes moon-orbit { 0% { transform: rotate(0deg); } 100% { transform: rotate(360deg); } }
+    @keyframes twinkle1 { 0%,100% { opacity: 0.2; } 50% { opacity: 1; } }
+    @keyframes twinkle2 { 0%,100% { opacity: 0.8; } 50% { opacity: 0.1; } }
+    @keyframes twinkle3 { 0%,100% { opacity: 0.5; } 50% { opacity: 1; } }
+    .minute-hand { animation: tick 60s linear infinite; transform-origin: 128px 128px; }
+    .hour-hand { animation: tick 720s linear infinite; transform-origin: 128px 128px; }
+    .outer-glow { animation: pulse 4s ease-in-out infinite; }
+    .moon-orbit { animation: moon-orbit 30s linear infinite; transform-origin: 128px 128px; }
+    .star1 { animation: twinkle1 3s ease-in-out infinite; }
+    .star2 { animation: twinkle2 4s ease-in-out infinite; }
+    .star3 { animation: twinkle3 2.5s ease-in-out infinite; }
+    .star4 { animation: twinkle1 3.5s ease-in-out 1s infinite; }
+    .star5 { animation: twinkle2 2s ease-in-out 0.5s infinite; }
+  </style>
+
+  <!-- Background -->
+  <rect width="256" height="256" rx="32" fill="url(#bg)"/>
+
+  <!-- Stars -->
+  <circle cx="30" cy="35" r="1.5" fill="#fff" class="star1"/>
+  <circle cx="220" cy="25" r="1" fill="#fff" class="star2"/>
+  <circle cx="45" cy="210" r="1.2" fill="#fff" class="star3"/>
+  <circle cx="200" cy="220" r="1" fill="#fff" class="star4"/>
+  <circle cx="180" cy="45" r="1.3" fill="#fff" class="star5"/>
+  <circle cx="60" cy="70" r="0.8" fill="#fff" class="star2"/>
+  <circle cx="210" cy="180" r="0.8" fill="#fff" class="star1"/>
+  <circle cx="35" cy="150" r="1" fill="#fff" class="star3"/>
+
+  <!-- Outer glow ring -->
+  <circle cx="128" cy="128" r="95" fill="none" stroke="#3a7bd5" stroke-width="1" opacity="0.3" class="outer-glow"/>
+  <circle cx="128" cy="128" r="100" fill="none" stroke="#3a7bd5" stroke-width="0.5" opacity="0.15" class="outer-glow"/>
+
+  <!-- Clock face -->
+  <circle cx="128" cy="128" r="85" fill="url(#face-glow)" opacity="0.15"/>
+  <circle cx="128" cy="128" r="85" fill="none" stroke="#4a8ad5" stroke-width="2" opacity="0.7"/>
+
+  <!-- Hour markers -->
+  <g opacity="0.6">
+    <line x1="128" y1="48" x2="128" y2="56" stroke="#e8d9a0" stroke-width="2"/>
+    <line x1="128" y1="200" x2="128" y2="208" stroke="#e8d9a0" stroke-width="2"/>
+    <line x1="48" y1="128" x2="56" y2="128" stroke="#e8d9a0" stroke-width="2"/>
+    <line x1="200" y1="128" x2="208" y2="128" stroke="#e8d9a0" stroke-width="2"/>
+    <!-- Diagonal markers -->
+    <line x1="71.4" y1="71.4" x2="77" y2="77" stroke="#e8d9a0" stroke-width="1.5"/>
+    <line x1="184.6" y1="71.4" x2="179" y2="77" stroke="#e8d9a0" stroke-width="1.5"/>
+    <line x1="71.4" y1="184.6" x2="77" y2="179" stroke="#e8d9a0" stroke-width="1.5"/>
+    <line x1="184.6" y1="184.6" x2="179" y2="179" stroke="#e8d9a0" stroke-width="1.5"/>
+  </g>
+
+  <!-- Calendar grid (small, bottom-right of clock face) -->
+  <g transform="translate(145, 145)" opacity="0.5">
+    <rect x="0" y="0" width="28" height="24" rx="3" fill="none" stroke="#e8d9a0" stroke-width="0.8"/>
+    <line x1="0" y1="6" x2="28" y2="6" stroke="#e8d9a0" stroke-width="0.5"/>
+    <line x1="7" y1="6" x2="7" y2="24" stroke="#e8d9a0" stroke-width="0.3"/>
+    <line x1="14" y1="6" x2="14" y2="24" stroke="#e8d9a0" stroke-width="0.3"/>
+    <line x1="21" y1="6" x2="21" y2="24" stroke="#e8d9a0" stroke-width="0.3"/>
+    <line x1="0" y1="12" x2="28" y2="12" stroke="#e8d9a0" stroke-width="0.3"/>
+    <line x1="0" y1="18" x2="28" y2="18" stroke="#e8d9a0" stroke-width="0.3"/>
+    <!-- "Today" highlight -->
+    <rect x="14.5" y="12.5" width="6" height="5" rx="1" fill="#e8d9a0" opacity="0.4"/>
+  </g>
+
+  <!-- Moon in orbit -->
+  <g class="moon-orbit">
+    <circle cx="128" cy="30" r="10" fill="#e8d9a0" opacity="0.8"/>
+    <circle cx="123" cy="28" r="8" fill="url(#bg)"/>
+    <circle cx="128" cy="30" r="14" fill="url(#moon-glow)"/>
+  </g>
+
+  <!-- Hour hand -->
+  <g class="hour-hand">
+    <line x1="128" y1="128" x2="128" y2="78" stroke="url(#hand-glow)" stroke-width="4" stroke-linecap="round"/>
+  </g>
+
+  <!-- Minute hand -->
+  <g class="minute-hand">
+    <line x1="128" y1="128" x2="128" y2="58" stroke="#e8d9a0" stroke-width="2" stroke-linecap="round"/>
+  </g>
+
+  <!-- Center dot -->
+  <circle cx="128" cy="128" r="4" fill="#e8d9a0"/>
+  <circle cx="128" cy="128" r="2" fill="#fff"/>
+
+  <!-- Planet dots along the outer ring -->
+  <circle cx="128" cy="22" r="3" fill="#BC2732" opacity="0.7" class="star1"/> <!-- Mars -->
+  <circle cx="220" cy="100" r="3.5" fill="#C08040" opacity="0.7" class="star3"/> <!-- Jupiter -->
+  <circle cx="50" cy="170" r="2.5" fill="#E6B07C" opacity="0.7" class="star2"/> <!-- Venus -->
+</svg>

data/lib/timely/astronomy.rb

@@ -0,0 +1,180 @@
+module Timely
+  module Astronomy
+    PHASE_NAMES = [
+      'New Moon', 'Waxing Crescent', 'First Quarter', 'Waxing Gibbous',
+      'Full Moon', 'Waning Gibbous', 'Last Quarter', 'Waning Crescent'
+    ].freeze
+
+    PHASE_SYMBOLS = [
+      "\u{1F311}", "\u{1F312}", "\u{1F313}", "\u{1F314}",
+      "\u{1F315}", "\u{1F316}", "\u{1F317}", "\u{1F318}"
+    ].freeze
+
+    # Calculate moon phase for a given Date.
+    # Returns a hash with :illumination (0.0-1.0), :phase_name, :symbol, :phase_index
+    def self.moon_phase(date)
+      # Julian date calculation
+      y = date.year
+      m = date.month
+      d = date.day
+
+      jd = 367 * y - (7 * (y + ((m + 9) / 12))) / 4 + (275 * m) / 9 + d + 1721013.5
+
+      # Days since known new moon (Jan 6, 2000 18:14 UTC)
+      # Reference epoch: JD 2451550.1 (known new moon)
+      days_since = jd - 2451550.1
+      synodic_month = 29.530588853
+
+      # Normalize to 0.0 - 1.0 within synodic month
+      phase = (days_since / synodic_month) % 1.0
+      phase = phase + 1.0 if phase < 0
+
+      # Map phase position to illumination (0 = new, 0.5 = full)
+      # Illumination follows a cosine curve
+      illumination = (1.0 - Math.cos(phase * 2 * Math::PI)) / 2.0
+
+      # Determine phase index (0-7)
+      phase_index = (phase * 8).floor % 8
+
+      {
+        illumination: illumination.round(4),
+        phase: phase.round(4),
+        phase_name: PHASE_NAMES[phase_index],
+        symbol: PHASE_SYMBOLS[phase_index],
+        phase_index: phase_index
+      }
+    end
+
+    # Return a short symbol for display in calendar cells
+    def self.moon_symbol(date)
+      moon_phase(date)[:symbol]
+    end
+
+    # Check if this is a notable phase (new, first quarter, full, last quarter).
+    # Only returns true on the day closest to the exact phase transition.
+    def self.notable_phase?(date)
+      today_phase = moon_phase(date)
+      index = today_phase[:phase_index]
+      return false unless [0, 2, 4, 6].include?(index)
+
+      # Check if yesterday had a different phase index
+      yesterday = moon_phase(date - 1)
+      yesterday[:phase_index] != index
+    end
+
+    # Find all notable moon phase dates within a month.
+    # Returns array of { date:, phase_name:, symbol: }
+    def self.notable_phases_in_month(year, month)
+      last_day = Date.new(year, month, -1).day
+      result = []
+      (1..last_day).each do |d|
+        date = Date.new(year, month, d)
+        if notable_phase?(date)
+          p = moon_phase(date)
+          result << { date: date, day: d, phase_name: p[:phase_name], symbol: p[:symbol] }
+        end
+      end
+      result
+    end
+
+    # Sunrise/sunset for a given date and location.
+    # Returns { rise: "HH:MM", set: "HH:MM" }
+    def self.sun_times(date, lat = 59.9139, lon = 10.7522, tz = 1)
+      load_ephemeris
+      return nil unless defined?(Ephemeris)
+      eph = Ephemeris.new(date.strftime('%Y-%m-%d'), lat, lon, tz)
+      rise, _, sett = eph.rts(eph.sun[0], eph.sun[1])
+      { rise: rise.is_a?(String) ? rise[0..4] : rise.to_s,
+        set: sett.is_a?(String) ? sett[0..4] : sett.to_s }
+    rescue => e
+      nil
+    end
+
+    def self.load_ephemeris
+      return if defined?(Ephemeris)
+      begin
+        require 'ephemeris'
+      rescue LoadError
+        path = File.expand_path('~/Main/G/GIT-isene/ephemeris/lib/ephemeris.rb')
+        require path if File.exist?(path)
+      end
+    end
+
+    PLANET_SYMBOLS = {
+      'mercury' => "\u263F", 'venus' => "\u2640", 'mars' => "\u2642",
+      'jupiter' => "\u2643", 'saturn' => "\u2644"
+    }.freeze
+
+    # RGB colors matching astropanel
+    BODY_COLORS = {
+      'sun'     => 'FFD700',
+      'moon'    => '888888',
+      'mercury' => '8F6E54',
+      'venus'   => 'E6B07C',
+      'mars'    => 'BC2732',
+      'jupiter' => 'C08040',
+      'saturn'  => 'E8D9A0'
+    }.freeze
+
+    # Returns array of planet names visible at night for the given date/location.
+    # A planet is "visible" if altitude > 5 degrees at any hour between 20:00-04:00.
+    def self.visible_planets(date, lat = 59.9139, lon = 10.7522, tz = 1)
+      load_ephemeris
+      return [] unless defined?(Ephemeris)
+
+      date_str = date.strftime('%Y-%m-%d')
+      eph = Ephemeris.new(date_str, lat, lon, tz)
+      visible = []
+
+      %w[mercury venus mars jupiter saturn].each do |planet|
+        # Check altitude at evening/night hours
+        [20.0, 21.0, 22.0, 23.0, 0.0, 1.0, 2.0, 3.0, 4.0].any? do |h|
+          alt, _ = eph.body_alt_az(planet, h)
+          if alt > 5
+            body = eph.send(planet)
+            visible << {
+              name: planet.capitalize,
+              symbol: PLANET_SYMBOLS[planet],
+              rise: body[5].is_a?(String) ? body[5][0..4] : body[5].to_s,
+              set: body[7].is_a?(String) ? body[7][0..4] : body[7].to_s
+            }
+            true
+          end
+        end
+      end
+      visible
+    rescue => e
+      []
+    end
+
+    # Notable astronomical events for a date (simple rule-based).
+    # Returns array of event description strings.
+    def self.astro_events(date, lat = 59.9139, lon = 10.7522, tz = 1)
+      events = []
+
+      # Check for notable moon phase
+      phase = moon_phase(date)
+      if notable_phase?(date)
+        events << "#{phase[:symbol]} #{phase[:phase_name]}"
+      end
+
+      # Check for solstices and equinoxes
+      m, d = date.month, date.day
+      events << "\u2600 Summer Solstice" if m == 6 && d == 21
+      events << "\u2744 Winter Solstice" if m == 12 && d == 21
+      events << "\u2600 Vernal Equinox" if m == 3 && d == 20
+      events << "\u2600 Autumnal Equinox" if m == 9 && d == 22
+
+      # Major meteor showers (peak dates)
+      events << "\u2604 Quadrantids peak" if m == 1 && d == 3
+      events << "\u2604 Lyrids peak" if m == 4 && d == 22
+      events << "\u2604 Eta Aquariids peak" if m == 5 && d == 6
+      events << "\u2604 Perseids peak" if m == 8 && d == 12
+      events << "\u2604 Orionids peak" if m == 10 && d == 21
+      events << "\u2604 Leonids peak" if m == 11 && d == 17
+      events << "\u2604 Geminids peak" if m == 12 && d == 14
+
+      events
+    end
+  end
+end