From b74b98f177d92d50ddbede900ba41212e07c5f63 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sat, 21 Feb 2026 07:06:50 -0600
Subject: feat: unified cache and staleness handling for mode-line and buffer

Replace TTL-based cache invalidation with proactive scheduled refresh.
Both mode-line and buffer systems now follow: timer refreshes cache,
display reads from cache, staleness indicated when data is old.

Phase 1 - Mode-line cache formalization + staleness display:
- Replace wttrin--mode-line-tooltip-data with wttrin--mode-line-cache
  as (timestamp . data) cons cell matching buffer cache pattern
- Add wttrin--format-age helper for human-readable age strings
- Rewrite wttrin--mode-line-update-display to take no arguments,
  read from cache, compute staleness (age > 2x refresh interval),
  dim emoji gray when stale, show staleness info in tooltip
- Rewrite wttrin--mode-line-fetch-weather to write cache on success,
  show stale display on failure with cache, error placeholder without
- Add wttrin--mode-line-update-placeholder-error for first-launch failure

Phase 2 - Remove TTL, add proactive buffer refresh:
- Rename wttrin-cache-ttl to wttrin-refresh-interval (default 3600s)
  with define-obsolete-variable-alias for backward compatibility
- Change wttrin-mode-line-refresh-interval default from 900 to 3600
- Remove TTL check from wttrin--get-cached-or-fetch; serve cached data
  regardless of age, background timer keeps it fresh
- Add buffer refresh timer (wttrin--buffer-cache-refresh)

Phase 3 - Buffer staleness display:
- Add wttrin--format-staleness-header for buffer age display
- Insert staleness line in wttrin--display-weather before instructions

Phase 4 - Cleanup:
- Remove all references to wttrin--mode-line-tooltip-data
- Update README.org cache settings and mode-line documentation
- Update tests for new API (198 tests across 21 files, all passing)
---
 tests/test-wttrin--mode-line-map.el | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

(limited to 'tests/test-wttrin--mode-line-map.el')

diff --git a/tests/test-wttrin--mode-line-map.el b/tests/test-wttrin--mode-line-map.el
index 2328300..ef8f0d2 100644
--- a/tests/test-wttrin--mode-line-map.el
+++ b/tests/test-wttrin--mode-line-map.el
@@ -75,16 +75,17 @@
   "Test that mode-line display uses wttrin--mode-line-map after refactoring.
 This test verifies the refactoring eliminated inline keymap construction."
   ;; Set up minimal mode-line state
-  (let ((wttrin-favorite-location "Test, CA")
-        (wttrin--mode-line-tooltip-data "Test weather"))
-    ;; Update the mode-line display
-    (wttrin--mode-line-update-display "☀️")
+  (let ((wttrin-favorite-location "Test, CA"))
+    (cl-letf (((symbol-function 'float-time) (lambda () 1000.0)))
+      (setq wttrin--mode-line-cache (cons 1000.0 "Test, CA: ☀️ +61°F Clear"))
+      (wttrin--mode-line-update-display))
 
     ;; Extract the keymap property from wttrin-mode-line-string
     (let ((keymap-prop (get-text-property 0 'local-map wttrin-mode-line-string)))
       ;; After refactoring, should use the shared wttrin--mode-line-map
       ;; Not a freshly constructed keymap on each call
-      (should (eq keymap-prop wttrin--mode-line-map)))))
+      (should (eq keymap-prop wttrin--mode-line-map)))
+    (setq wttrin--mode-line-cache nil)))
 
 (provide 'test-wttrin--mode-line-map)
 ;;; test-wttrin--mode-line-map.el ends here
-- 
cgit v1.2.3