tuiweather 0.3.7 → 0.5.0

package/README.md

@@ -5,12 +5,14 @@ Keyboard-driven terminal weather app: Dark Sky-style rain nowcasting, hourly and
 ## Features
 
 - **Rain nowcast** — minute-level "umbrella in N min" warnings derived from 15-minute precipitation buckets (Open-Meteo only; NWS has no minute-level precipitation feed — the nowcast panel hides and the watch bell stays inactive under `provider = "nws"`, nothing renders a false "Dry")
-- **Hourly + daily forecast** — sparkline temperature strip, emoji condition icons, precipitation probabilities, and (md+ widths) a UV/humidity/visibility summary row
+- **Hourly + daily forecast** — sparkline temperature strip, emoji condition icons, precipitation probabilities, and a day-detail view with hourly temperature, precipitation, wind/gust, UV, and daylight context
+- **Go out / heads up** — on medium and wide terminals, a "go out" line names the best dry, comfortable 2+ hour window in the next 24h, and a "heads up" line flags the worst hazardous (rainy or high-gust) one; either line is omitted when nothing in the forecast clears its bar
 - **Location search** — type `/`, search the Open-Meteo geocoder, enter to add; locations persist to config
 - **Guided first run** — choose units and find a location without editing a config file
 - **Units** — metric/imperial toggle persisted across runs
 - **Themes** — day/night accent palettes follow the forecast location's sunrise/sunset; text ink adapts to your terminal's background
 - **Air quality** — US AQI with category label in the details grid, from the Open-Meteo Air Quality API
+- **Status rail** — on wide terminals (96+ columns) the sidebar carries the location list plus a live nowcast card and a bottom-anchored today summary (range, rain, sunrise/sunset, UV and AQI)
 - **Responsive layout** — four breakpoint tiers down to 32 columns; clamps gracefully below that
 - **One-line mode** — a single status line for tmux bars and prompts
 
@@ -30,7 +32,20 @@ or with the Bun package manager:
 bun install --global tuiweather
 ```
 
-Standalone binaries for macOS and Linux are attached to each [GitHub release](https://github.com/brndnsh-labs/tuiweather/releases).
+or run without installing:
+
+```sh
+npx tuiweather --version
+bunx tuiweather --version
+```
+
+Standalone binaries for macOS, Linux, and Windows (x64) are attached to each [GitHub release](https://github.com/brndnsh-labs/tuiweather/releases). On Windows (no Node or Bun required), in cmd.exe or any shell with `curl.exe` on PATH:
+
+```sh
+curl.exe -Lo tuiweather-windows-x64.tar.gz https://github.com/brndnsh-labs/tuiweather/releases/latest/download/tuiweather-windows-x64.tar.gz
+tar -xzf tuiweather-windows-x64.tar.gz
+.\tuiweather.exe --version
+```
 
 ### macOS Gatekeeper
 
@@ -45,8 +60,9 @@ xattr -d com.apple.quarantine /path/to/tuiweather
 Run `tuiweather` with no arguments for the full TUI.
 
 On the first run, tuiweather opens a short keyboard tour, asks for metric or imperial units, and
-lets you search for your first location. The completed setup is written atomically to the normal
-config path before weather data loads.
+lets you search for your first location. Press `s` on the welcome step to skip for now and see the
+empty main view, or `o` from the help overlay to re-run setup later. The completed setup is written
+atomically to the normal config path before weather data loads.
 
 Use `tuiweather --help` for command-line options and `tuiweather --version` to print the installed version.
 
@@ -54,6 +70,9 @@ Use `tuiweather --help` for command-line options and `tuiweather --version` to p
 | --- | --- |
 | `r` | Refresh current location (bypasses cache) |
 | `[` / `]` | Previous / next location |
+| `←` / `→` | Select a day in the daily list |
+| `v` | Inspect the selected day (defaults to today) |
+| `,` / `.` | Page the daily list backward / forward through the fetched range |
 | `l` | Open the locations overlay: switch, set default, delete, reorder |
 | `1`–`9` | Jump to location N by sidebar order (1-based; no-op out of range) |
 | `u` | Toggle metric / imperial units |
@@ -65,13 +84,16 @@ Use `tuiweather --help` for command-line options and `tuiweather --version` to p
 | `J` / `K` | Move focused location down/up in sidebar order (lg tier) |
 | `↑` / `↓` | Scroll the main panel when content overflows |
 | `?` | Toggle help overlay |
-| `esc` | Clear sidebar focus if set; otherwise close help overlay or quit |
+| `o` | Re-run setup (from help overlay) |
+| `esc` | Close day detail first; otherwise clear sidebar focus or close the help overlay |
 | `q` | Quit |
 
 While the search overlay is open it owns the keyboard: type to search, up/down to move the cursor, enter to add the highlighted result, esc to cancel. Number, focus, and reorder keys are ignored while the search input is focused (same as `d`/`r`).
 
 The locations overlay (`l`) also owns the keyboard while open: up/down (or `j`/`k`) to move the cursor, enter or `1`–`9` to switch, `s` to set the cursor row as default, `d` twice to delete it, `J`/`K` to reorder it, `/` to jump into search, esc to close.
 
+Use left/right to move the daily-list cursor, then `v` to open that local day's hourly story. The day-detail overlay owns the keyboard while open; up/down scrolls compact views and esc returns to the unchanged main view.
+
 ### One-line mode
 
 `tuiweather --one-line` prints a single line and exits — designed for tmux status bars and shell prompts:
@@ -127,10 +149,11 @@ bell. The bell depends on the minute-level nowcast, which is Open-Meteo only: un
 Config lives at `~/.config/tuiweather/config.toml` (respects `XDG_CONFIG_HOME`). Every field is optional unless marked required; unknown fields are ignored.
 
 ```toml
-schema_version = 3
+schema_version = 4
 time_format = "auto"
 refresh_minutes = 10
 theme = "auto"
+ink = "auto"
 provider = "openmeteo"
 daily_days = 7
 hourly_hours = 24
@@ -157,24 +180,26 @@ longitude = -122.6765
 
 | Field | Type | Default | Constraints |
 | --- | --- | --- | --- |
-| `schema_version` | integer | `3` | Required; currently always `3`. Version 1 and 2 files are migrated in place on load |
+| `schema_version` | integer | `4` | Required; currently always `4`. Version 1, 2, and 3 files are migrated in place on load |
 | `time_format` | `12h` / `24h` / `auto` | `"auto"` | `auto` picks 12h when temperature units are imperial, else 24h |
 | `refresh_minutes` | integer | `10` | Minimum `1` |
-| `theme` | `day` / `night` / `auto` | `"auto"` | Accent palette; `auto` follows the location's sunrise/sunset. Text ink always adapts to your terminal's background |
+| `reduced_motion` | boolean | `false` | Replace the animated loading spinner with a static indicator |
+| `theme` | `day` / `night` / `auto` | `"auto"` | Accent palette; `auto` follows the location's sunrise/sunset. Text ink adapts via `ink` |
+| `ink` | `auto` / `light` / `dark` | `"auto"` | Terminal ink override; `auto` detects the background via an OSC query (300ms timeout, fallback dark), `light`/`dark` skips detection and uses that ink directly |
 | `provider` | `openmeteo` / `nws` | `"openmeteo"` | Weather data source. Open-Meteo is the default full-feature experience; NWS is the official US source fallback — works: conditions, temperatures, precipitation probabilities; goes quiet: minute-level nowcast (panel hides, watch bell inactive), hourly/daily precip amounts (blank bars/chips), air quality |
-| `daily_days` | integer | `7` | `1`–`16` forecast days |
+| `daily_days` | integer | `7` | `1`–`16` forecast days requested from NWS; Open-Meteo always requests 14 days and pages the daily list with `,`/`.` regardless of this setting |
 | `hourly_hours` | integer | `24` | `12`–`48` forecast hours |
 | `default_location` | string | none | Must match a `[[locations]]` slug |
-| `units.temp` | `metric` / `imperial` | legacy `units` | Display unit for temperatures |
-| `units.wind` | `metric` / `imperial` | legacy `units` | Display unit for wind speed and visibility |
-| `units.precip` | `metric` / `imperial` | legacy `units` | Display unit for precipitation amounts |
-| `units.pressure` | `metric` / `imperial` | legacy `units` | Display unit for pressure; `metric` → hPa (rounded), `imperial` → inHg to 2 decimals; defaults via legacy `units` |
-| `panels.nowcast` | boolean | `true` | Show/hide the nowcast banner |
-| `panels.details` | boolean | `true` | Show/hide the details grid |
+| `units.temp` | `metric` / `imperial` | legacy `units`, else `imperial` | Display unit for temperatures |
+| `units.wind` | `metric` / `imperial` | legacy `units`, else `imperial` | Display unit for wind speed and visibility |
+| `units.precip` | `metric` / `imperial` | legacy `units`, else `imperial` | Display unit for precipitation amounts |
+| `units.pressure` | `metric` / `imperial` | legacy `units`, else `imperial` | Display unit for pressure; `metric` → hPa (rounded), `imperial` → inHg to 2 decimals; falls back to `imperial` when unset |
+| `panels.nowcast` | boolean | `true` | Show/hide the nowcast banner, and the status rail's `now` card at the lg tier |
+| `panels.details` | boolean | `true` | Show/hide the details grid, and the status rail's `today` card at the lg tier (it repeats the grid's sunrise/sunset and UV) |
 | `panels.hourly` | boolean | `true` | Show/hide the hourly strip |
 | `panels.daily` | boolean | `true` | Show/hide the daily list |
 
-Each `[units]` field can be set independently, so mixed display such as °C temperatures with mph wind works everywhere including one-line mode. The legacy top-level `units = "metric" | "imperial"` scalar is still accepted and acts as the fallback for any `[units]` field you omit; because TOML forbids a key and table with the same name, saved configs contain either the scalar (uniform prefs) or the full `[units]` table (mixed prefs), never both.
+Each `[units]` field can be set independently, so mixed display such as °C temperatures with mph wind works everywhere including one-line mode. The legacy top-level `units = "metric" | "imperial"` scalar is still accepted and acts as the fallback for any `[units]` field you omit; when neither the field nor the legacy scalar is set, the unit falls back to `imperial`. Because TOML forbids a key and table with the same name, saved configs contain either the scalar (uniform prefs) or the full `[units]` table (mixed prefs), never both.
 
 Each `[[locations]]` entry:
 
@@ -198,6 +223,7 @@ Requires [Bun](https://bun.sh) >= 1.3.
 ```sh
 bun install
 bun run dev        # run the TUI
+bun run preview    # offline interface demo with recorded Portland + Tokyo weather
 bun run test       # unit + snapshot tests
 bun run typecheck  # tsc --noEmit
 bun run lint       # biome check
@@ -205,6 +231,15 @@ bun run lint       # biome check
 
 See [AGENTS.md](AGENTS.md) for architecture and conventions, [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow.
 
+The interface adapts from a compact weather summary to an observatory with large temperatures,
+weather artwork, an hourly chart, and seven forecast cards. Light and dark terminal appearances
+both use contrast-adjusted text. Use `←` / `→` and `v` to inspect a day, `i` to inspect an hour,
+and `?` for all shortcuts.
+
+The preview uses a temporary config and recorded fixtures; it does not load or change your
+normal locations. Try `bun run preview --light` for the light appearance. To export a terminal
+frame as SVG, run `bun run preview --capture /tmp/weather.svg --width 120 --height 40`.
+
 ## License
 
 [MIT](LICENSE)