release: v1.21 (versionCode 22) — WebView hardening

The WebView holds the claude.ai session cookie; lock down every path a loaded
page could use to reach local files. No effect on the login/SSO flow.

.gitea/workflows/build.yml

@@ -0,0 +1,117 @@
+name: Build APK
+
+# Push to master / open a PR  → builds a DEBUG apk (smoke test, no secrets needed).
+# Push a tag like v1.14       → builds a SIGNED RELEASE apk and attaches it to the
+#                               Gitea release for that tag.
+on:
+  push:
+    branches: [master]
+    tags: ['v*']
+  pull_request:
+    branches: [master]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '17'
+
+      - name: Install Android SDK
+        run: |
+          set -e
+          SDK="$GITHUB_WORKSPACE/android-sdk"
+          mkdir -p "$SDK/cmdline-tools"
+          curl -sSL -o /tmp/cmdtools.zip \
+            https://dl.google.com/android/repository/commandlinetools-linux-9862592_latest.zip
+          unzip -q /tmp/cmdtools.zip -d "$SDK/cmdline-tools"
+          mv "$SDK/cmdline-tools/cmdline-tools" "$SDK/cmdline-tools/latest"
+          # Feed "y" via process substitution, not a pipe: `yes |` triggers SIGPIPE (exit 141)
+          # once sdkmanager stops reading, and the step shell runs with `-eo pipefail`.
+          "$SDK/cmdline-tools/latest/bin/sdkmanager" --sdk_root="$SDK" --licenses >/dev/null < <(yes)
+          "$SDK/cmdline-tools/latest/bin/sdkmanager" --sdk_root="$SDK" \
+            "platform-tools" "platforms;android-34" "build-tools;34.0.0" >/dev/null
+
+      - name: Point Gradle at the SDK
+        run: echo "sdk.dir=$GITHUB_WORKSPACE/android-sdk" > local.properties
+
+      # ── Debug build: every push/PR that is NOT a tag ───────────────────────
+      - name: Build debug APK
+        if: ${{ !startsWith(github.ref, 'refs/tags/') }}
+        run: ./gradlew :app:assembleDebug --no-daemon
+
+      # ── Release build: tags only (needs the KEYSTORE_BASE64 secret) ────────
+      - name: Decode signing keystore
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          if [ -z "${{ secrets.KEYSTORE_BASE64 }}" ]; then
+            echo "::error::KEYSTORE_BASE64 secret is not set — cannot build a signed release."
+            exit 1
+          fi
+          echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 -d > app/claude-widget-release.keystore
+
+      # Signing passwords are no longer hardcoded in build.gradle.kts — inject them at build time.
+      - name: Write signing credentials
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          if [ -z "${{ secrets.KEYSTORE_PASSWORD }}" ] || [ -z "${{ secrets.KEY_PASSWORD }}" ]; then
+            echo "::error::KEYSTORE_PASSWORD / KEY_PASSWORD secrets not set — cannot sign release."
+            exit 1
+          fi
+          {
+            echo "storePassword=${{ secrets.KEYSTORE_PASSWORD }}"
+            echo "keyPassword=${{ secrets.KEY_PASSWORD }}"
+            echo "keyAlias=${{ secrets.KEY_ALIAS || 'claudewidget' }}"
+          } > keystore.properties
+
+      - name: Build release APK
+        if: startsWith(github.ref, 'refs/tags/')
+        run: ./gradlew :app:assembleRelease --no-daemon
+
+      # ── Stage whichever APK was produced ───────────────────────────────────
+      - name: Stage APK
+        run: |
+          mkdir -p out
+          if [ -f app/build/outputs/apk/release/app-release.apk ]; then
+            cp app/build/outputs/apk/release/app-release.apk out/claude-usage-widget.apk
+          else
+            cp app/build/outputs/apk/debug/app-debug.apk out/claude-usage-widget-debug.apk
+          fi
+          ls -la out/
+
+      - name: Upload APK artifact
+        uses: actions/upload-artifact@v3
+        continue-on-error: true
+        with:
+          name: apk
+          path: out/*.apk
+
+      # ── Attach the signed APK to the Gitea release on tag ──────────────────
+      - name: Publish APK to Gitea release
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          TAG="${GITHUB_REF#refs/tags/}"
+          API="${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}"
+          # Create the release if it doesn't exist yet (ignore "already exists").
+          curl -s -X POST "$API/releases" \
+            -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
+            -d "{\"tag_name\":\"$TAG\",\"name\":\"$TAG\",\"body\":\"Automated build of $TAG\"}" >/dev/null || true
+          RID=$(curl -s "$API/releases/tags/$TAG" -H "Authorization: token $TOKEN" \
+            | python3 -c "import sys,json;print(json.load(sys.stdin)['id'])")
+          # Replace any existing asset of the same name, then upload.
+          curl -s "$API/releases/$RID/assets" -H "Authorization: token $TOKEN" \
+            | python3 -c "import sys,json;[print(a['id']) for a in json.load(sys.stdin) if a['name']=='claude-usage-widget.apk']" \
+            | while read AID; do curl -s -X DELETE "$API/releases/$RID/assets/$AID" -H "Authorization: token $TOKEN"; done
+          curl -s -X POST "$API/releases/$RID/assets?name=claude-usage-widget.apk" \
+            -H "Authorization: token $TOKEN" \
+            -F "attachment=@out/claude-usage-widget.apk" >/dev/null
+          echo "Attached claude-usage-widget.apk to release $TAG"

.gitignore

@@ -10,3 +10,4 @@ captures/
 .cxx/
 *.keystore
 *.jks
+keystore.properties

LICENSE

@@ -0,0 +1,45 @@
+Claude Usage Widget Source-Available License
+Copyright (c) 2026 Amir Khodak. All rights reserved.
+
+This is NOT an OSI-approved open-source license. The source code is made
+publicly viewable ("source-available"), but the rights granted are limited as
+described below. Where this license is silent, all rights are reserved.
+
+1. DEFINITIONS
+   "Software" means the Claude Usage Widget source code, assets, and
+   documentation in this repository. "You" means anyone other than the
+   copyright holder.
+
+2. WHAT YOU MAY DO
+   a. View, read, and study the Software.
+   b. Clone or fork the repository for your own private, personal,
+      non-commercial use and experimentation.
+   c. Build the Software from source and run it on devices you personally own.
+   d. Submit contributions (pull requests) back to this repository; by doing so
+      you license your contribution to the copyright holder under these terms.
+
+3. WHAT YOU MAY NOT DO (without the copyright holder's prior written permission)
+   a. Redistribute, publish, or make available the Software or any derivative
+      work — in source or binary/APK form — to any third party or app store
+      (including but not limited to Google Play, F-Droid, Amazon Appstore,
+      Gitea/GitHub releases, or any website).
+   b. Use the Software, in whole or in part, for any commercial purpose.
+   c. Sell, sublicense, rent, or offer the Software as a service.
+   d. Use the names, app identity ("Claude Usage Widget"), package identifier
+      ("me.khodak.claudeusage"), logos, or signing keys of the original work.
+   e. Remove or alter this license or the copyright notice.
+
+4. RESERVED RIGHTS
+   All publishing and distribution rights are reserved exclusively to the
+   copyright holder. Only the copyright holder may publish official builds.
+
+5. TRADEMARK NOTE
+   "Claude" is a trademark of Anthropic. This is an unofficial, independent
+   utility and is not affiliated with or endorsed by Anthropic.
+
+6. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
+   DAMAGES, OR OTHER LIABILITY ARISING FROM THE SOFTWARE OR ITS USE.
+
+To request permission for anything in section 3, contact the copyright holder.

README.md

@@ -15,10 +15,20 @@ Android home screen widget that shows your Claude Pro usage at a glance.
   yellow → orange → red → purple (burning way too fast), with an "X% over/under pace" label.
 - **Peak-hours indicator** — a Claude burst icon that lights up 🔥 during Anthropic's peak window
   (5–11 AM Pacific, Mon–Fri), when tokens burn faster, with a countdown to the window close.
+- **Usage history chart** — the app plots your session and weekly utilization over the past 7 days,
+  so you can see your consumption trend, not just the current snapshot.
+- **Usage alerts** — opt-in notifications when session or weekly usage crosses a threshold you set
+  (sliders, 50–100%). Each alert fires at most once per limit window, so you're never spammed.
 - Tap the widget to open the app; tap ⟳ to force-refresh
 - Responsive: works as 4×1 (compact) or 4×2 (full)
 - Auto-refreshes every 5 minutes in the background
 
+## Screenshots
+
+<p align="center">
+  <img src="docs/screenshots/signin.png" width="240" alt="Sign in">
+</p>
+
 ## Install
 
 1. Download `claude-usage-widget.apk` from the [latest release](../../releases/latest)

app/build.gradle.kts

@@ -1,8 +1,21 @@
+import java.util.Properties
+
 plugins {
     id("com.android.application")
     id("org.jetbrains.kotlin.android")
 }
 
+// Signing credentials are NEVER committed. They are read from (in order):
+//   1. environment variables  (KEYSTORE_PASSWORD / KEY_PASSWORD / KEY_ALIAS)  — used by CI
+//   2. keystore.properties at the repo root (gitignored)                      — used locally
+// See keystore.properties.example. Debug builds need none of this.
+val keystoreProps = Properties().apply {
+    val f = rootProject.file("keystore.properties")
+    if (f.exists()) f.inputStream().use { load(it) }
+}
+fun signingCred(envName: String, propName: String): String? =
+    System.getenv(envName) ?: keystoreProps.getProperty(propName)
+
 android {
     namespace = "me.khodak.claudeusage"
     compileSdk = 34
@@ -11,16 +24,26 @@ android {
         applicationId = "me.khodak.claudeusage"
         minSdk = 26
         targetSdk = 34
-        versionCode = 12
+        versionCode = 22
-        versionName = "1.11"
+        versionName = "1.21"
     }
 
+    val releaseStorePassword = signingCred("KEYSTORE_PASSWORD", "storePassword")
+    val releaseKeyPassword = signingCred("KEY_PASSWORD", "keyPassword")
+    val releaseKeyAlias = signingCred("KEY_ALIAS", "keyAlias") ?: "claudewidget"
+    val hasSigningCreds = releaseStorePassword != null && releaseKeyPassword != null
+
     signingConfigs {
         create("release") {
+            // Only wire the keystore when credentials are present, so debug builds and
+            // credential-less checkouts configure cleanly. Same keystore file + alias as before —
+            // signing identity is unchanged; only the password source moved out of version control.
+            if (hasSigningCreds) {
                 storeFile = file("claude-widget-release.keystore")
-            storePassword = "ClaudeWidget2026!"
+                storePassword = releaseStorePassword
-            keyAlias = "claudewidget"
+                keyAlias = releaseKeyAlias
-            keyPassword = "ClaudeWidget2026!"
+                keyPassword = releaseKeyPassword
+            }
         }
     }
 
@@ -29,7 +52,13 @@ android {
             isMinifyEnabled = true
             isShrinkResources = true
             proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+            // Sign only when creds were supplied; otherwise fail loudly at assembleRelease rather
+            // than silently shipping an unsigned APK. Tag builds in CI inject creds (see workflow).
+            if (hasSigningCreds) {
                 signingConfig = signingConfigs.getByName("release")
+            } else {
+                logger.warn("No signing credentials (KEYSTORE_PASSWORD/keystore.properties) — release APK will be unsigned.")
+            }
         }
     }
 
@@ -72,4 +101,7 @@ dependencies {
 
     // Lifecycle
     implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")
+
+    // Unit tests (pure JVM — no Robolectric, no Android framework)
+    testImplementation("junit:junit:4.13.2")
 }

app/src/main/AndroidManifest.xml

@@ -3,6 +3,7 @@
 
     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 
     <application
         android:allowBackup="false"
@@ -31,9 +32,11 @@
         <receiver
             android:name=".ClaudeUsageWidget"
             android:exported="true">
+            <!-- Only the system APPWIDGET_UPDATE action is exposed. ACTION_REFRESH is delivered via
+                 the widget's own explicit PendingIntent (explicit broadcasts need no intent-filter),
+                 so other apps can no longer trigger refreshes by sending that action externally. -->
             <intent-filter>
                 <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
-                <action android:name="me.khodak.claudeusage.ACTION_REFRESH" />
             </intent-filter>
             <meta-data
                 android:name="android.appwidget.provider"

app/src/main/java/me/khodak/claudeusage/BarRenderer.kt

@@ -19,7 +19,7 @@ object BarRenderer {
         usedPct: Int,
         markerPct: Int?,
         fillColor: Int,
-        tierColor: Int?,
+        markerColor: Int?,
         wPx: Int = 500,
         hPx: Int = 14,
         cornerPx: Float = 7f
@@ -42,14 +42,16 @@ object BarRenderer {
             canvas.drawRoundRect(fill, cornerPx, cornerPx, paint)
         }
 
-        // Pace tick — "where you should be right now"
+        // Pace marker — a single clean tick showing "where you should be right now".
-        if (markerPct != null && tierColor != null) {
+        // One color (no tiers); rounded ends to match the bar.
+        if (markerPct != null && markerColor != null) {
             val m = markerPct.coerceIn(0, 100)
-            val tickW = (wPx * 0.012f).coerceIn(3f, 7f)
+            val tickW = (wPx * 0.016f).coerceIn(6f, 10f)
             var x = wPx * m / 100f
             x = x.coerceIn(tickW / 2f, wPx - tickW / 2f)
-            paint.color = tierColor
+            paint.color = markerColor
-            canvas.drawRect(x - tickW / 2f, 0f, x + tickW / 2f, hPx.toFloat(), paint)
+            val tick = RectF(x - tickW / 2f, 0f, x + tickW / 2f, hPx.toFloat())
+            canvas.drawRoundRect(tick, tickW / 2f, tickW / 2f, paint)
         }
 
         return bmp

app/src/main/java/me/khodak/claudeusage/ClaudeUsageWidget.kt

@@ -42,6 +42,15 @@ class ClaudeUsageWidget : AppWidgetProvider() {
         @Volatile internal var isRefreshing = false
         @Volatile internal var currentRotation = 0f
 
+        /** Redraw every placed widget from the current cached data (call after a refresh). */
+        fun notifyDataChanged(context: Context) {
+            val manager = AppWidgetManager.getInstance(context)
+            val ids = manager.getAppWidgetIds(
+                android.content.ComponentName(context, ClaudeUsageWidget::class.java)
+            )
+            ids.forEach { updateWidget(context, manager, it) }
+        }
+
         fun updateWidget(context: Context, manager: AppWidgetManager, widgetId: Int) {
             val prefs = PreferencesManager(context)
             val apiData = prefs.getUsageData()
@@ -75,17 +84,26 @@ class ClaudeUsageWidget : AppWidgetProvider() {
                 return v
             }
 
+            // Full-size builder follows the user's chosen style; the compact (1-cell-tall) size
+            // always uses bars, since two rings don't fit that height.
+            val rings = prefs.getWidgetStyle() == PreferencesManager.STYLE_RINGS
+            fun buildFull() =
+                if (rings) buildRingViews(context, prefs, apiData)
+                else buildViews(context, prefs, apiData)
+
             return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
                 RemoteViews(mapOf(
                     SizeF(50f, 50f)  to attach(buildSmallViews(context, prefs, apiData)),
-                    SizeF(50f, 120f) to attach(buildViews(context, prefs, apiData))
+                    SizeF(50f, 120f) to attach(buildFull())
                 ))
             } else {
-                attach(buildViews(context, prefs, apiData))
+                attach(buildFull())
             }
         }
 
         private fun buildSmallViews(context: Context, prefs: PreferencesManager, apiData: UsageData?): RemoteViews {
+            val SESSION_FILL = ThemeColors.sessionFill(context, prefs)
+            val WEEKLY_FILL = ThemeColors.weeklyFill(context, prefs)
             val v = RemoteViews(context.packageName, R.layout.widget_layout_small)
             applyPeak(v, showText = false)
             if (!prefs.isLoggedIn()) {
@@ -104,11 +122,9 @@ class ClaudeUsageWidget : AppWidgetProvider() {
             when {
                 hasUtilization -> {
                     val pct = apiData!!.fiveHourUtilization.toInt()
-                    val pace = PaceCalc.compute(apiData.fiveHourUtilization, apiData.utilizationResetAtEpoch, PaceCalc.SESSION_WINDOW_MS)
                     v.setTextViewText(R.id.tv_session_value, "$pct%")
-                    v.setImageViewBitmap(R.id.bar_session, BarRenderer.render(pct, pace?.markerPct, SESSION_FILL, pace?.tierColor))
+                    v.setImageViewBitmap(R.id.bar_session, BarRenderer.render(pct, null, SESSION_FILL, null))
-                    v.setTextViewText(R.id.tv_session_label,
+                    v.setTextViewText(R.id.tv_session_label, formatReset(apiData.utilizationResetAtEpoch))
-                        if (pace != null) PaceCalc.shortTag(apiData.fiveHourUtilization, pace) else formatReset(apiData.utilizationResetAtEpoch))
                 }
                 hasApiMessages -> {
                     val rem = apiData!!.effectiveRemaining
@@ -136,9 +152,8 @@ class ClaudeUsageWidget : AppWidgetProvider() {
                 val wPct = apiData!!.weeklyUtilization.toInt()
                 val pace = PaceCalc.compute(apiData.weeklyUtilization, apiData.weeklyResetAtEpoch, PaceCalc.WEEKLY_WINDOW_MS)
                 v.setTextViewText(R.id.tv_weekly_value, "$wPct%")
-                v.setImageViewBitmap(R.id.bar_weekly, BarRenderer.render(wPct, pace?.markerPct, WEEKLY_FILL, pace?.tierColor))
+                v.setImageViewBitmap(R.id.bar_weekly, BarRenderer.render(wPct, pace?.markerPct, WEEKLY_FILL, if (pace != null) MARKER_COLOR else null))
-                v.setTextViewText(R.id.tv_weekly_label,
+                v.setTextViewText(R.id.tv_weekly_label, formatResetShort(apiData.weeklyResetAtEpoch))
-                    if (pace != null) PaceCalc.shortTag(apiData.weeklyUtilization, pace) else formatReset(apiData.weeklyResetAtEpoch))
             } else {
                 val weeklyDays = Integer.bitCount(prefs.getWeeklyMask())
                 v.setTextViewText(R.id.tv_weekly_value, "${weeklyDays}d")
@@ -161,6 +176,8 @@ class ClaudeUsageWidget : AppWidgetProvider() {
         }
 
         private fun buildViews(context: Context, prefs: PreferencesManager, apiData: UsageData?): RemoteViews {
+            val SESSION_FILL = ThemeColors.sessionFill(context, prefs)
+            val WEEKLY_FILL = ThemeColors.weeklyFill(context, prefs)
             val v = RemoteViews(context.packageName, R.layout.widget_layout)
             applyPeak(v, showText = true)
 
@@ -184,10 +201,9 @@ class ClaudeUsageWidget : AppWidgetProvider() {
             when {
                 hasUtilization -> {
                     val pct = apiData!!.fiveHourUtilization.toInt()
-                    val pace = PaceCalc.compute(apiData.fiveHourUtilization, apiData.utilizationResetAtEpoch, PaceCalc.SESSION_WINDOW_MS)
                     v.setTextViewText(R.id.tv_session_value, "$pct%")
-                    v.setImageViewBitmap(R.id.bar_session, BarRenderer.render(pct, pace?.markerPct, SESSION_FILL, pace?.tierColor))
+                    v.setImageViewBitmap(R.id.bar_session, BarRenderer.render(pct, null, SESSION_FILL, null))
-                    v.setTextViewText(R.id.tv_session_label, resetWithPace(apiData.utilizationResetAtEpoch, apiData.fiveHourUtilization, pace))
+                    v.setTextViewText(R.id.tv_session_label, formatReset(apiData.utilizationResetAtEpoch))
                 }
                 hasApiMessages -> {
                     val rem = apiData!!.effectiveRemaining
@@ -218,8 +234,8 @@ class ClaudeUsageWidget : AppWidgetProvider() {
                 val wPct = apiData!!.weeklyUtilization.toInt()
                 val pace = PaceCalc.compute(apiData.weeklyUtilization, apiData.weeklyResetAtEpoch, PaceCalc.WEEKLY_WINDOW_MS)
                 v.setTextViewText(R.id.tv_weekly_value, "$wPct%")
-                v.setImageViewBitmap(R.id.bar_weekly, BarRenderer.render(wPct, pace?.markerPct, WEEKLY_FILL, pace?.tierColor))
+                v.setImageViewBitmap(R.id.bar_weekly, BarRenderer.render(wPct, pace?.markerPct, WEEKLY_FILL, if (pace != null) MARKER_COLOR else null))
-                v.setTextViewText(R.id.tv_weekly_label, resetWithPace(apiData.weeklyResetAtEpoch, apiData.weeklyUtilization, pace))
+                v.setTextViewText(R.id.tv_weekly_label, formatResetDay(apiData.weeklyResetAtEpoch))
             } else {
                 val weeklyDays = Integer.bitCount(prefs.getWeeklyMask())
                 v.setTextViewText(R.id.tv_weekly_value, "$weeklyDays d")
@@ -247,8 +263,85 @@ class ClaudeUsageWidget : AppWidgetProvider() {
             return v
         }
 
+        /**
+         * Ring style of the full widget — same data/branching as [buildViews] but each metric is a
+         * circular [RingRenderer] gauge (percentage drawn in the center) instead of a bar.
+         */
+        private fun buildRingViews(context: Context, prefs: PreferencesManager, apiData: UsageData?): RemoteViews {
+            val SESSION_FILL = ThemeColors.sessionFill(context, prefs)
+            val WEEKLY_FILL = ThemeColors.weeklyFill(context, prefs)
+            val v = RemoteViews(context.packageName, R.layout.widget_layout_rings)
+            applyPeak(v, showText = true)
+
+            if (!prefs.isLoggedIn()) {
+                v.setImageViewBitmap(R.id.ring_session, RingRenderer.render(0, null, SESSION_FILL, null, "—", "SESSION"))
+                v.setImageViewBitmap(R.id.ring_weekly, RingRenderer.render(0, null, WEEKLY_FILL, null, "—", "WEEKLY"))
+                v.setTextViewText(R.id.tv_session_label, "Not signed in")
+                v.setTextViewText(R.id.tv_weekly_label, "Open app to sign in")
+                v.setTextViewText(R.id.tv_status, "")
+                return v
+            }
+
+            // ── 5-hour session ring ──────────────────────────────────────────
+            val hasUtilization = apiData != null && apiData.fiveHourUtilization >= 0f
+            val hasApiMessages = apiData != null && apiData.effectiveRemaining >= 0 && apiData.messagesLimit > 0
+            val sessionStart = prefs.getSessionStart()
+            when {
+                hasUtilization -> {
+                    val pct = apiData!!.fiveHourUtilization.toInt()
+                    v.setImageViewBitmap(R.id.ring_session, RingRenderer.render(pct, null, SESSION_FILL, null, "$pct%", "SESSION"))
+                    v.setTextViewText(R.id.tv_session_label, formatReset(apiData.utilizationResetAtEpoch))
+                }
+                hasApiMessages -> {
+                    val pct = apiData!!.progressPercent
+                    v.setImageViewBitmap(R.id.ring_session, RingRenderer.render(pct, null, SESSION_FILL, null, "$pct%", "SESSION"))
+                    v.setTextViewText(R.id.tv_session_label, formatReset(apiData.resetAtEpoch))
+                }
+                sessionStart > 0 -> {
+                    v.setImageViewBitmap(R.id.ring_session, RingRenderer.render(0, null, SESSION_FILL, null, "·", "SESSION"))
+                    v.setTextViewText(R.id.tv_session_label, "session active")
+                }
+                else -> {
+                    v.setImageViewBitmap(R.id.ring_session, RingRenderer.render(0, null, SESSION_FILL, null, "—", "SESSION"))
+                    v.setTextViewText(R.id.tv_session_label, "")
+                }
+            }
+
+            // ── 7-day weekly ring (with pace tick) ───────────────────────────
+            val hasWeekly = apiData != null && apiData.weeklyUtilization >= 0f
+            if (hasWeekly) {
+                val wPct = apiData!!.weeklyUtilization.toInt()
+                val pace = PaceCalc.compute(apiData.weeklyUtilization, apiData.weeklyResetAtEpoch, PaceCalc.WEEKLY_WINDOW_MS)
+                v.setImageViewBitmap(
+                    R.id.ring_weekly,
+                    RingRenderer.render(wPct, pace?.markerPct, WEEKLY_FILL, if (pace != null) MARKER_COLOR else null, "$wPct%", "WEEKLY")
+                )
+                v.setTextViewText(R.id.tv_weekly_label, formatResetDay(apiData.weeklyResetAtEpoch))
+            } else {
+                val weeklyDays = Integer.bitCount(prefs.getWeeklyMask())
+                v.setImageViewBitmap(R.id.ring_weekly, RingRenderer.render(0, null, WEEKLY_FILL, null, "${weeklyDays}d", "WEEKLY"))
+                v.setTextViewText(R.id.tv_weekly_label, "active this week")
+            }
+
+            // ── Footer ───────────────────────────────────────────────────────
+            val resetEpoch = apiData?.effectiveResetEpoch ?: -1L
+            val status = when {
+                isRefreshing -> "Refreshing…"
+                apiData?.isRateLimited == true -> "Rate limited · ${formatReset(resetEpoch)}"
+                else -> ""
+            }
+            val updatedMs = apiData?.lastUpdated ?: 0L
+            v.setTextViewText(R.id.tv_status,
+                if (status.isNotBlank()) status else if (updatedMs > 0) formatTime(updatedMs) else "")
+            v.setInt(R.id.btn_refresh, "setColorFilter",
+                if (isRefreshing) 0xFFCC785C.toInt() else 0xFF999999.toInt())
+            v.setFloat(R.id.btn_refresh, "setRotation", currentRotation)
+            return v
+        }
+
         private const val SESSION_FILL = 0xFFCC785C.toInt()
         private const val WEEKLY_FILL = 0xFF7B8FCC.toInt()
+        private const val MARKER_COLOR = 0xFFFFFFFF.toInt()   // single-color pace marker (weekly only)
 
         /** Tints the header burst icon and (optionally) the PEAK text by current peak state. */
         private fun applyPeak(v: RemoteViews, showText: Boolean) {
@@ -260,14 +353,6 @@ class ClaudeUsageWidget : AppWidgetProvider() {
             }
         }
 
-        /** "Resets at 3:00 PM · 8% under pace" — reset line with the pace tag appended. */
-        private fun resetWithPace(resetEpoch: Long, usedPct: Float, pace: PaceCalc.Pace?): CharSequence {
-            val reset = formatReset(resetEpoch)
-            if (pace == null) return reset
-            val tag = PaceCalc.shortTag(usedPct, pace)
-            return if (reset.isBlank()) tag else "$reset · $tag"
-        }
-
         private fun formatReset(epochMs: Long): String {
             if (epochMs <= 0) return ""
             val now = System.currentTimeMillis()
@@ -281,6 +366,23 @@ class ClaudeUsageWidget : AppWidgetProvider() {
             }
         }
 
+        /** Weekly reset with weekday + date ("Resets Friday, Jun 6 · 3:00 PM"), never "tomorrow". */
+        private fun formatResetDay(epochMs: Long): String {
+            if (epochMs <= 0) return ""
+            if (epochMs <= System.currentTimeMillis()) return "Resets soon"
+            val day = SimpleDateFormat("EEEE", Locale.US).format(Date(epochMs))
+            val date = SimpleDateFormat("MMM d", Locale.US).format(Date(epochMs))
+            val timeStr = SimpleDateFormat("h:mm a", Locale.US).format(Date(epochMs))
+            return "Resets $day, $date · $timeStr"
+        }
+
+        /** Compact weekly reset for the space-tight small widget: "Fri, Jun 6". */
+        private fun formatResetShort(epochMs: Long): String {
+            if (epochMs <= 0) return ""
+            if (epochMs <= System.currentTimeMillis()) return "soon"
+            return SimpleDateFormat("EEE, MMM d", Locale.US).format(Date(epochMs))
+        }
+
         private fun formatTime(ms: Long) =
             SimpleDateFormat("h:mm a", Locale.US).format(Date(ms))
     }

app/src/main/java/me/khodak/claudeusage/HistoryChartView.kt

@@ -0,0 +1,131 @@
+package me.khodak.claudeusage
+
+import android.content.Context
+import android.graphics.Canvas
+import android.graphics.Paint
+import android.graphics.Path
+import android.util.AttributeSet
+import android.view.View
+import me.khodak.claudeusage.data.UsageSnapshot
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+
+/**
+ * Lightweight line chart for usage history, hand-drawn on Canvas to stay dependency-free
+ * and consistent with [BarRenderer]. Plots session (orange) and weekly (blue) utilization
+ * 0-100% over time. Gaps longer than [GAP_MS] are not connected, so an offline stretch
+ * shows as a break rather than a misleading straight line.
+ */
+class HistoryChartView @JvmOverloads constructor(
+    context: Context,
+    attrs: AttributeSet? = null,
+    defStyle: Int = 0
+) : View(context, attrs, defStyle) {
+
+    private var points: List<UsageSnapshot> = emptyList()
+
+    private val gridPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+        color = 0xFF2A2A2A.toInt(); strokeWidth = dp(1f); style = Paint.Style.STROKE
+    }
+    private val labelPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+        color = 0xFF666666.toInt(); textSize = sp(10f)
+    }
+    private val sessionPaint = linePaint(0xFFCC785C.toInt())
+    private val weeklyPaint = linePaint(0xFF7B8FCC.toInt())
+    private val emptyPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+        color = 0xFF666666.toInt(); textSize = sp(13f); textAlign = Paint.Align.CENTER
+    }
+
+    private val padL = dp(28f)
+    private val padR = dp(8f)
+    private val padT = dp(10f)
+    private val padB = dp(18f)
+
+    fun setData(data: List<UsageSnapshot>) {
+        points = data
+        invalidate()
+    }
+
+    override fun onDraw(canvas: Canvas) {
+        super.onDraw(canvas)
+        val left = padL
+        val top = padT
+        val right = width - padR
+        val bottom = height - padB
+        if (right <= left || bottom <= top) return
+
+        // Y gridlines + labels at 0 / 50 / 100%
+        for (pct in intArrayOf(0, 50, 100)) {
+            val y = bottom - (pct / 100f) * (bottom - top)
+            canvas.drawLine(left, y, right, y, gridPaint)
+            canvas.drawText("$pct", dp(4f), y + sp(3.5f), labelPaint)
+        }
+
+        val plottable = points.filter { it.sessionPct >= 0f || it.weeklyPct >= 0f }
+        if (plottable.size < 2) {
+            canvas.drawText(
+                "Collecting history… check back later",
+                (left + right) / 2f, (top + bottom) / 2f, emptyPaint
+            )
+            return
+        }
+
+        val tMin = plottable.first().epochMs
+        val tMax = plottable.last().epochMs
+        val tSpan = (tMax - tMin).coerceAtLeast(1L)
+
+        fun x(ms: Long) = left + (ms - tMin).toFloat() / tSpan * (right - left)
+        fun y(pct: Float) = bottom - (pct / 100f) * (bottom - top)
+
+        drawSeries(canvas, plottable, sessionPaint, ::x, ::y) { it.sessionPct }
+        drawSeries(canvas, plottable, weeklyPaint, ::x, ::y) { it.weeklyPct }
+
+        // X axis time labels (start … end)
+        val fmt = SimpleDateFormat("MMM d, h a", Locale.US)
+        labelPaint.textAlign = Paint.Align.LEFT
+        canvas.drawText(fmt.format(Date(tMin)), left, height - dp(4f), labelPaint)
+        labelPaint.textAlign = Paint.Align.RIGHT
+        canvas.drawText(fmt.format(Date(tMax)), right, height - dp(4f), labelPaint)
+        labelPaint.textAlign = Paint.Align.LEFT
+    }
+
+    private inline fun drawSeries(
+        canvas: Canvas,
+        data: List<UsageSnapshot>,
+        paint: Paint,
+        x: (Long) -> Float,
+        y: (Float) -> Float,
+        value: (UsageSnapshot) -> Float
+    ) {
+        val path = Path()
+        var penDown = false
+        var prevMs = 0L
+        for (p in data) {
+            val v = value(p)
+            if (v < 0f) { penDown = false; continue }
+            val px = x(p.epochMs); val py = y(v)
+            if (!penDown || p.epochMs - prevMs > GAP_MS) {
+                path.moveTo(px, py)
+            } else {
+                path.lineTo(px, py)
+            }
+            penDown = true
+            prevMs = p.epochMs
+        }
+        canvas.drawPath(path, paint)
+    }
+
+    private fun linePaint(c: Int) = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+        color = c; strokeWidth = dp(2f); style = Paint.Style.STROKE
+        strokeJoin = Paint.Join.ROUND; strokeCap = Paint.Cap.ROUND
+    }
+
+    private fun dp(v: Float) = v * resources.displayMetrics.density
+    private fun sp(v: Float) = v * resources.displayMetrics.scaledDensity
+
+    companion object {
+        // Don't connect points separated by more than ~35 min (a missed refresh cycle or two).
+        private const val GAP_MS = 35 * 60 * 1000L
+    }
+}

app/src/main/java/me/khodak/claudeusage/LoginActivity.kt

@@ -75,6 +75,15 @@ class LoginActivity : AppCompatActivity() {
                 databaseEnabled = false
                 javaScriptCanOpenWindowsAutomatically = false
                 setSupportMultipleWindows(false)
+                // Hardening: this WebView holds the claude.ai session, so lock down every path a
+                // page could use to reach the device. None of these affect the login flow.
+                allowFileAccess = false
+                allowContentAccess = false
+                @Suppress("DEPRECATION")
+                allowFileAccessFromFileURLs = false
+                @Suppress("DEPRECATION")
+                allowUniversalAccessFromFileURLs = false
+                setGeolocationEnabled(false)
                 // Standard Android Chrome UA — less suspicious than desktop
                 userAgentString = "Mozilla/5.0 (Linux; Android 13; Pixel 7) " +
                     "AppleWebKit/537.36 (KHTML, like Gecko) " +
@@ -85,9 +94,19 @@ class LoginActivity : AppCompatActivity() {
 
             webViewClient = object : WebViewClient() {
                 override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
-                    val url = request.url.toString()
+                    val uri = request.url
+                    val url = uri.toString()
+                    // Keep blocking app-redirect schemes outright.
                     if (url.startsWith("market://") || url.startsWith("intent://")) return true
-                    return false
+                    val scheme = uri.scheme?.lowercase()
+                    // about:blank and data: URIs are used by the login page itself (e.g. blank
+                    // bootstrap frames, inline images). They have no host to allow-list, so let them load.
+                    if (scheme == "about" || scheme == "data") return false
+                    // Host ALLOW-LIST: only navigate to claude.ai and its SSO/CDN providers.
+                    // OAuth runs as full-page redirects in THIS WebView (multiple windows disabled,
+                    // JS-opened windows disabled), so the list MUST include the Google/Apple SSO
+                    // and Cloudflare challenge hosts or sign-in breaks. Anything else is blocked.
+                    return !isHostAllowed(uri.host)
                 }
 
                 override fun onPageStarted(view: WebView, url: String, favicon: android.graphics.Bitmap?) {
@@ -169,4 +188,35 @@ class LoginActivity : AppCompatActivity() {
         binding.webView.destroy()
         super.onDestroy()
     }
+
+    /**
+     * True if [host] belongs to an allowed domain (exact match or a subdomain via dot-suffix).
+     * A null/blank host is never allowed. accounts.google.com, challenges.cloudflare.com, etc. are
+     * covered by their parent-domain suffixes (google.com, cloudflare.com).
+     */
+    private fun isHostAllowed(host: String?): Boolean {
+        if (host.isNullOrBlank()) return false
+        val h = host.lowercase()
+        return ALLOWED_DOMAINS.any { d -> h == d || h.endsWith(".$d") }
+    }
+
+    companion object {
+        // WebView host allow-list. Login navigation is restricted to claude.ai and the SSO/CDN
+        // hosts it redirects through. This MUST include the SSO providers (Google, Apple) and
+        // Cloudflare challenge hosts — OAuth happens as same-WebView full-page redirects, so
+        // dropping any of these breaks sign-in. Subdomains are matched by dot-suffix.
+        private val ALLOWED_DOMAINS = listOf(
+            "claude.ai",
+            "anthropic.com",
+            "google.com",            // covers accounts.google.com
+            "gstatic.com",
+            "googleusercontent.com",
+            "googleapis.com",
+            "apple.com",
+            "icloud.com",
+            "cloudflare.com",        // covers challenges.cloudflare.com
+            "cloudflareinsights.com",
+            "recaptcha.net"
+        )
+    }
 }

app/src/main/java/me/khodak/claudeusage/MainActivity.kt

@@ -1,10 +1,18 @@
 package me.khodak.claudeusage
 
+import android.Manifest
 import android.content.Intent
+import android.content.pm.PackageManager
+import android.os.Build
 import android.os.Bundle
 import android.view.View
+import androidx.activity.result.contract.ActivityResultContracts
 import androidx.appcompat.app.AppCompatActivity
+import androidx.core.content.ContextCompat
 import androidx.lifecycle.lifecycleScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.isActive
 import kotlinx.coroutines.launch
 import me.khodak.claudeusage.data.PreferencesManager
 import me.khodak.claudeusage.data.UsageData
@@ -19,6 +27,39 @@ class MainActivity : AppCompatActivity() {
     private lateinit var prefs: PreferencesManager
     private lateinit var repo: UsageRepository
 
+    private val notifPermLauncher =
+        registerForActivityResult(ActivityResultContracts.RequestPermission()) { /* result handled silently */ }
+
+    /** SAF: pick a destination file and write the current settings JSON to it. */
+    private val exportLauncher =
+        registerForActivityResult(ActivityResultContracts.CreateDocument("application/json")) { uri ->
+            if (uri == null) return@registerForActivityResult
+            try {
+                contentResolver.openOutputStream(uri)?.use { it.write(prefs.exportSettings().toByteArray()) }
+                toast("Settings exported")
+            } catch (_: Exception) { toast("Export failed") }
+        }
+
+    /** SAF: pick a backup file and apply it. */
+    private val importLauncher =
+        registerForActivityResult(ActivityResultContracts.OpenDocument()) { uri ->
+            if (uri == null) return@registerForActivityResult
+            try {
+                val json = contentResolver.openInputStream(uri)?.bufferedReader()?.use { it.readText() } ?: ""
+                if (prefs.importSettings(json)) {
+                    toast("Settings restored")
+                    // Reflect restored prefs immediately: re-sync switches and redraw any widgets.
+                    binding.switchNotify.isChecked = prefs.isNotifyEnabled()
+                    binding.switchRingStyle.isChecked = prefs.getWidgetStyle() == PreferencesManager.STYLE_RINGS
+                    binding.switchMaterialYou.isChecked = prefs.isMaterialYou()
+                    ClaudeUsageWidget.notifyDataChanged(this)
+                } else toast("Not a valid settings file")
+            } catch (_: Exception) { toast("Import failed") }
+        }
+
+    /** Live refresh loop that runs only while the app is in the foreground. */
+    private var autoRefreshJob: Job? = null
+
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         binding = ActivityMainBinding.inflate(layoutInflater)
@@ -51,6 +92,11 @@ class MainActivity : AppCompatActivity() {
             })
         }
 
+        setupNotificationSettings()
+        setupWidgetStyleSetting()
+        setupMaterialYouSetting()
+        setupBackupRestore()
+
         binding.btnDebug.setOnClickListener {
             if (binding.tvDebugInfo.visibility == android.view.View.GONE) {
                 binding.tvDebugInfo.text = repo.lastDebugInfo.ifBlank { "No debug info yet — tap Refresh first" }
@@ -65,32 +111,105 @@ class MainActivity : AppCompatActivity() {
 
     override fun onResume() {
         super.onResume()
-        val cached = prefs.getUsageData()
+        updateUI(prefs.getUsageData())  // show cached instantly — never a blank screen
-        updateUI(cached)
+        if (prefs.isLoggedIn()) startAutoRefresh()
-        if (prefs.isLoggedIn()) {
+    }
-            val staleMs = 5 * 60 * 1000L
+
-            if ((cached?.lastUpdated ?: 0L) < System.currentTimeMillis() - staleMs) {
+    override fun onPause() {
-                refreshUsage()
+        super.onPause()
+        autoRefreshJob?.cancel()
+    }
+
+    /** Refresh immediately on open, then every [REFRESH_INTERVAL_MS] while foregrounded. */
+    private fun startAutoRefresh() {
+        autoRefreshJob?.cancel()
+        autoRefreshJob = lifecycleScope.launch {
+            while (isActive) {
+                doRefresh(silent = true)
+                delay(REFRESH_INTERVAL_MS)
             }
         }
     }
 
+    private fun setupNotificationSettings() {
+        binding.switchNotify.isChecked = prefs.isNotifyEnabled()
+        binding.switchNotify.setOnCheckedChangeListener { _, checked ->
+            prefs.setNotifyEnabled(checked)
+            if (checked) requestNotificationPermission()
+        }
+        // Alerts default on, so prompt for the runtime permission once on first launch
+        // (a user who never toggles the switch would otherwise never be asked).
+        if (prefs.isNotifyEnabled()) requestNotificationPermission()
+    }
+
+    /** Bars ⇄ Rings switch for the home-screen widget; redraws any placed widgets immediately. */
+    private fun setupWidgetStyleSetting() {
+        binding.switchRingStyle.isChecked = prefs.getWidgetStyle() == PreferencesManager.STYLE_RINGS
+        binding.switchRingStyle.setOnCheckedChangeListener { _, checked ->
+            prefs.setWidgetStyle(if (checked) PreferencesManager.STYLE_RINGS else PreferencesManager.STYLE_BARS)
+            ClaudeUsageWidget.notifyDataChanged(this)
+        }
+    }
+
+    /** Material You toggle — switches the bars/rings to wallpaper-derived accents (Android 12+). */
+    private fun setupMaterialYouSetting() {
+        binding.switchMaterialYou.isChecked = prefs.isMaterialYou()
+        binding.switchMaterialYou.setOnCheckedChangeListener { _, checked ->
+            prefs.setMaterialYou(checked)
+            ClaudeUsageWidget.notifyDataChanged(this)
+        }
+    }
+
+    /** Export/Import settings via the Storage Access Framework (no extra permissions needed). */
+    private fun setupBackupRestore() {
+        binding.btnExportSettings.setOnClickListener {
+            exportLauncher.launch("claude-usage-settings.json")
+        }
+        binding.btnImportSettings.setOnClickListener {
+            importLauncher.launch(arrayOf("application/json", "text/*", "*/*"))
+        }
+    }
+
+    private fun toast(msg: String) =
+        android.widget.Toast.makeText(this, msg, android.widget.Toast.LENGTH_SHORT).show()
+
+    private fun requestNotificationPermission() {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) return
+        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS)
+            != PackageManager.PERMISSION_GRANTED
+        ) {
+            notifPermLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
+        }
+    }
+
+    /** Manual "Refresh Now" button — shows the spinner. */
     private fun refreshUsage() {
+        lifecycleScope.launch { doRefresh(silent = false) }
+    }
+
+    private suspend fun doRefresh(silent: Boolean) {
+        if (!silent) {
             binding.btnRefresh.isEnabled = false
             binding.progressIndicator.visibility = View.VISIBLE
-        lifecycleScope.launch {
+        }
-            val data = try {
+        val fresh = try {
             repo.fetchUsage()
         } catch (e: Exception) {
             if (e is kotlinx.coroutines.CancellationException) throw e
-                prefs.getUsageData()?.copy(errorMessage = "Network error")
+            UsageData(errorMessage = "Network error")
-                    ?: UsageData(errorMessage = "Network error")
         }
-            prefs.saveUsageData(data)
+        // Preserve last-good data so a failed/partial fetch never blanks the UI or widget.
-            updateUI(data)
+        val merged = fresh.mergedWith(prefs.getUsageData())
+        prefs.saveUsageData(merged)
+        prefs.recordHistory(fresh)
+        // Note: alerts fire only from the background worker, not here — no point pinging you
+        // with a notification while you're already looking at the app.
+        updateUI(merged)
+        ClaudeUsageWidget.notifyDataChanged(this)  // opening the app refreshes the widget too
         if (binding.tvDebugInfo.visibility == View.VISIBLE) {
             binding.tvDebugInfo.text = repo.lastDebugInfo
         }
+        if (!silent) {
             binding.btnRefresh.isEnabled = true
             binding.progressIndicator.visibility = View.GONE
         }
@@ -113,31 +232,28 @@ class MainActivity : AppCompatActivity() {
         else
             "Off-peak · ${peak.windowLabel}"
 
-        // ── Session (5-hour) bar + pace ──────────────────────────────────────
+        // ── Session (5-hour) bar — no pace marker ────────────────────────────
-        val sessionPct = data.progressPercent
-        val sessionPace = if (data.fiveHourUtilization >= 0f)
-            PaceCalc.compute(data.fiveHourUtilization, data.utilizationResetAtEpoch, PaceCalc.SESSION_WINDOW_MS)
-        else null
         binding.barSession.setImageBitmap(
-            BarRenderer.render(sessionPct, sessionPace?.markerPct, SESSION_FILL, sessionPace?.tierColor)
+            BarRenderer.render(data.progressPercent, null, SESSION_FILL, null)
         )
-        binding.tvSessionPace.text = paceSentence(data.fiveHourUtilization, sessionPace)
 
-        // ── Weekly (7-day) bar + pace ────────────────────────────────────────
+        // ── Weekly (7-day) bar — single-color pace marker ────────────────────
         if (data.weeklyUtilization >= 0f) {
             val wPct = data.weeklyUtilization.toInt()
             val weeklyPace = PaceCalc.compute(data.weeklyUtilization, data.weeklyResetAtEpoch, PaceCalc.WEEKLY_WINDOW_MS)
             binding.barWeekly.setImageBitmap(
-                BarRenderer.render(wPct, weeklyPace?.markerPct, WEEKLY_FILL, weeklyPace?.tierColor)
+                BarRenderer.render(wPct, weeklyPace?.markerPct, WEEKLY_FILL, if (weeklyPace != null) MARKER_COLOR else null)
             )
             binding.tvWeeklyUsage.text = "$wPct% this week"
-            binding.tvWeeklyPace.text = paceSentence(data.weeklyUtilization, weeklyPace)
         } else {
             binding.barWeekly.setImageBitmap(BarRenderer.render(0, null, WEEKLY_FILL, null))
             binding.tvWeeklyUsage.text = "—"
-            binding.tvWeeklyPace.text = ""
         }
 
+        // Pace text removed per design — bars carry the signal.
+        binding.tvSessionPace.visibility = View.GONE
+        binding.tvWeeklyPace.visibility = View.GONE
+
         binding.tvUsage.text = when {
             data.fiveHourUtilization >= 0f -> {
                 val pct = data.fiveHourUtilization.toInt()
@@ -153,19 +269,15 @@ class MainActivity : AppCompatActivity() {
         }
 
         binding.tvReset.text = formatReset(data.effectiveResetEpoch)
-        binding.tvWeeklyReset.text = formatReset(data.weeklyResetAtEpoch)
+        binding.tvWeeklyReset.text = formatResetDay(data.weeklyResetAtEpoch)
         binding.tvUpdated.text = if (data.lastUpdated > 0)
             "Last updated: ${SimpleDateFormat("h:mm a, MMM d", Locale.US).format(Date(data.lastUpdated))}"
         else ""
 
         binding.tvError.text = data.errorMessage
         binding.tvError.visibility = if (data.errorMessage.isNotBlank()) View.VISIBLE else View.GONE
-    }
 
-    /** "20% over pace · will likely hit limit" — empty when no projection is available yet. */
+        binding.historyChart.setData(prefs.getHistory())
-    private fun paceSentence(usedPct: Float, pace: PaceCalc.Pace?): String {
-        if (pace == null) return ""
-        return "${PaceCalc.shortTag(usedPct, pace)} · ${pace.label}"
     }
 
     private fun formatReset(epochMs: Long): String {
@@ -181,9 +293,21 @@ class MainActivity : AppCompatActivity() {
         }
     }
 
+    /** Weekly reset shown with the weekday name ("Resets Friday 3:00 PM"), never "tomorrow". */
+    private fun formatResetDay(epochMs: Long): String {
+        if (epochMs <= 0) return ""
+        if (epochMs <= System.currentTimeMillis()) return "Resets soon"
+        val day = SimpleDateFormat("EEEE", Locale.US).format(Date(epochMs))
+        val date = SimpleDateFormat("MMM d", Locale.US).format(Date(epochMs))
+        val timeStr = SimpleDateFormat("h:mm a", Locale.US).format(Date(epochMs))
+        return "Resets $day, $date · $timeStr"
+    }
+
     companion object {
+        private const val REFRESH_INTERVAL_MS = 30_000L   // live refresh cadence while app is open
         private const val SESSION_FILL = 0xFFCC785C.toInt()
         private const val WEEKLY_FILL = 0xFF7B8FCC.toInt()
+        private const val MARKER_COLOR = 0xFFFFFFFF.toInt()   // single-color weekly pace marker
         private const val PEAK_ON = 0xFFCC785C.toInt()
         private const val PEAK_OFF = 0xFF666666.toInt()
     }

app/src/main/java/me/khodak/claudeusage/MainActivity.kt.tmp.283970.ad8df417b08b

@@ -0,0 +1,310 @@
+package me.khodak.claudeusage
+
+import android.Manifest
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.os.Build
+import android.os.Bundle
+import android.view.View
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.appcompat.app.AppCompatActivity
+import androidx.core.content.ContextCompat
+import androidx.lifecycle.lifecycleScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+import me.khodak.claudeusage.data.PreferencesManager
+import me.khodak.claudeusage.data.UsageData
+import me.khodak.claudeusage.databinding.ActivityMainBinding
+import java.text.SimpleDateFormat
+import java.util.*
+import java.util.concurrent.TimeUnit
+
+class MainActivity : AppCompatActivity() {
+
+    private lateinit var binding: ActivityMainBinding
+    private lateinit var prefs: PreferencesManager
+    private lateinit var repo: UsageRepository
+
+    private val notifPermLauncher =
+        registerForActivityResult(ActivityResultContracts.RequestPermission()) { /* result handled silently */ }
+
+    /** SAF: pick a destination file and write the current settings JSON to it. */
+    private val exportLauncher =
+        registerForActivityResult(ActivityResultContracts.CreateDocument("application/json")) { uri ->
+            if (uri == null) return@registerForActivityResult
+            try {
+                contentResolver.openOutputStream(uri)?.use { it.write(prefs.exportSettings().toByteArray()) }
+                toast("Settings exported")
+            } catch (_: Exception) { toast("Export failed") }
+        }
+
+    /** SAF: pick a backup file and apply it. */
+    private val importLauncher =
+        registerForActivityResult(ActivityResultContracts.OpenDocument()) { uri ->
+            if (uri == null) return@registerForActivityResult
+            try {
+                val json = contentResolver.openInputStream(uri)?.bufferedReader()?.use { it.readText() } ?: ""
+                if (prefs.importSettings(json)) {
+                    toast("Settings restored")
+                    // Reflect restored prefs immediately: re-sync switches and redraw any widgets.
+                    binding.switchNotify.isChecked = prefs.isNotifyEnabled()
+                    binding.switchRingStyle.isChecked = prefs.getWidgetStyle() == PreferencesManager.STYLE_RINGS
+                    binding.switchMaterialYou.isChecked = prefs.isMaterialYou()
+                    ClaudeUsageWidget.notifyDataChanged(this)
+                } else toast("Not a valid settings file")
+            } catch (_: Exception) { toast("Import failed") }
+        }
+
+    /** Live refresh loop that runs only while the app is in the foreground. */
+    private var autoRefreshJob: Job? = null
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        binding = ActivityMainBinding.inflate(layoutInflater)
+        setContentView(binding.root)
+
+        prefs = PreferencesManager(this)
+        repo = UsageRepository(prefs)
+
+        binding.btnLogin.setOnClickListener {
+            startActivity(Intent(this, LoginActivity::class.java))
+        }
+
+        // If already logged in, go straight to logged-in state without re-opening login
+        if (prefs.isLoggedIn()) {
+            updateUI(prefs.getUsageData())
+        }
+
+        binding.btnLogout.setOnClickListener {
+            prefs.clearSession()
+            updateUI(null)
+        }
+
+        binding.btnRefresh.setOnClickListener {
+            refreshUsage()
+        }
+
+        binding.tvWidgetHint.setOnClickListener {
+            startActivity(Intent(Intent.ACTION_MAIN).apply {
+                addCategory(Intent.CATEGORY_HOME)
+            })
+        }
+
+        setupNotificationSettings()
+        setupWidgetStyleSetting()
+        setupMaterialYouSetting()
+        setupBackupRestore()
+
+        binding.btnDebug.setOnClickListener {
+            if (binding.tvDebugInfo.visibility == android.view.View.GONE) {
+                binding.tvDebugInfo.text = repo.lastDebugInfo.ifBlank { "No debug info yet — tap Refresh first" }
+                binding.tvDebugInfo.visibility = android.view.View.VISIBLE
+                binding.btnDebug.text = "Hide API Debug"
+            } else {
+                binding.tvDebugInfo.visibility = android.view.View.GONE
+                binding.btnDebug.text = "Show API Debug"
+            }
+        }
+    }
+
+    override fun onResume() {
+        super.onResume()
+        updateUI(prefs.getUsageData())  // show cached instantly — never a blank screen
+        if (prefs.isLoggedIn()) startAutoRefresh()
+    }
+
+    override fun onPause() {
+        super.onPause()
+        autoRefreshJob?.cancel()
+    }
+
+    /** Refresh immediately on open, then every [REFRESH_INTERVAL_MS] while foregrounded. */
+    private fun startAutoRefresh() {
+        autoRefreshJob?.cancel()
+        autoRefreshJob = lifecycleScope.launch {
+            while (isActive) {
+                doRefresh(silent = true)
+                delay(REFRESH_INTERVAL_MS)
+            }
+        }
+    }
+
+    private fun setupNotificationSettings() {
+        binding.switchNotify.isChecked = prefs.isNotifyEnabled()
+        binding.switchNotify.setOnCheckedChangeListener { _, checked ->
+            prefs.setNotifyEnabled(checked)
+            if (checked) requestNotificationPermission()
+        }
+        // Alerts default on, so prompt for the runtime permission once on first launch
+        // (a user who never toggles the switch would otherwise never be asked).
+        if (prefs.isNotifyEnabled()) requestNotificationPermission()
+    }
+
+    /** Bars ⇄ Rings switch for the home-screen widget; redraws any placed widgets immediately. */
+    private fun setupWidgetStyleSetting() {
+        binding.switchRingStyle.isChecked = prefs.getWidgetStyle() == PreferencesManager.STYLE_RINGS
+        binding.switchRingStyle.setOnCheckedChangeListener { _, checked ->
+            prefs.setWidgetStyle(if (checked) PreferencesManager.STYLE_RINGS else PreferencesManager.STYLE_BARS)
+            ClaudeUsageWidget.notifyDataChanged(this)
+        }
+    }
+
+    /** Material You toggle — redraws placed widgets so the new accent applies immediately. */
+    private fun setupMaterialYouSetting() {
+        binding.switchMaterialYou.isChecked = prefs.isMaterialYou()
+        binding.switchMaterialYou.setOnCheckedChangeListener { _, checked ->
+            prefs.setMaterialYou(checked)
+            ClaudeUsageWidget.notifyDataChanged(this)
+            updateUI(prefs.getUsageData())   // refresh the in-app bars too
+        }
+    }
+
+    private fun setupBackupRestore() {
+        binding.btnExportSettings.setOnClickListener { exportLauncher.launch("claude-usage-settings.json") }
+        binding.btnImportSettings.setOnClickListener { importLauncher.launch(arrayOf("application/json", "text/plain", "*/*")) }
+    }
+
+    private fun toast(msg: String) =
+        android.widget.Toast.makeText(this, msg, android.widget.Toast.LENGTH_SHORT).show()
+
+    private fun requestNotificationPermission() {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) return
+        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS)
+            != PackageManager.PERMISSION_GRANTED
+        ) {
+            notifPermLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
+        }
+    }
+
+    /** Manual "Refresh Now" button — shows the spinner. */
+    private fun refreshUsage() {
+        lifecycleScope.launch { doRefresh(silent = false) }
+    }
+
+    private suspend fun doRefresh(silent: Boolean) {
+        if (!silent) {
+            binding.btnRefresh.isEnabled = false
+            binding.progressIndicator.visibility = View.VISIBLE
+        }
+        val fresh = try {
+            repo.fetchUsage()
+        } catch (e: Exception) {
+            if (e is kotlinx.coroutines.CancellationException) throw e
+            UsageData(errorMessage = "Network error")
+        }
+        // Preserve last-good data so a failed/partial fetch never blanks the UI or widget.
+        val merged = fresh.mergedWith(prefs.getUsageData())
+        prefs.saveUsageData(merged)
+        prefs.recordHistory(fresh)
+        // Note: alerts fire only from the background worker, not here — no point pinging you
+        // with a notification while you're already looking at the app.
+        updateUI(merged)
+        ClaudeUsageWidget.notifyDataChanged(this)  // opening the app refreshes the widget too
+        if (binding.tvDebugInfo.visibility == View.VISIBLE) {
+            binding.tvDebugInfo.text = repo.lastDebugInfo
+        }
+        if (!silent) {
+            binding.btnRefresh.isEnabled = true
+            binding.progressIndicator.visibility = View.GONE
+        }
+    }
+
+    private fun updateUI(data: UsageData?) {
+        val loggedIn = prefs.isLoggedIn()
+
+        binding.layoutLoggedOut.visibility = if (loggedIn) View.GONE else View.VISIBLE
+        binding.layoutLoggedIn.visibility = if (loggedIn) View.VISIBLE else View.GONE
+
+        if (!loggedIn || data == null) return
+
+        // ── Peak-hours row ───────────────────────────────────────────────────
+        val peak = PeakHours.state()
+        binding.imgPeak.setColorFilter(if (peak.active) PEAK_ON else PEAK_OFF)
+        binding.tvPeak.setTextColor(if (peak.active) PEAK_ON else 0xFFAAAAAA.toInt())
+        binding.tvPeak.text = if (peak.active)
+            "🔥 Peak hours — ${peak.endsInLabel} · ${peak.windowLabel}"
+        else
+            "Off-peak · ${peak.windowLabel}"
+
+        // ── Session (5-hour) bar — no pace marker ────────────────────────────
+        binding.barSession.setImageBitmap(
+            BarRenderer.render(data.progressPercent, null, SESSION_FILL, null)
+        )
+
+        // ── Weekly (7-day) bar — single-color pace marker ────────────────────
+        if (data.weeklyUtilization >= 0f) {
+            val wPct = data.weeklyUtilization.toInt()
+            val weeklyPace = PaceCalc.compute(data.weeklyUtilization, data.weeklyResetAtEpoch, PaceCalc.WEEKLY_WINDOW_MS)
+            binding.barWeekly.setImageBitmap(
+                BarRenderer.render(wPct, weeklyPace?.markerPct, WEEKLY_FILL, if (weeklyPace != null) MARKER_COLOR else null)
+            )
+            binding.tvWeeklyUsage.text = "$wPct% this week"
+        } else {
+            binding.barWeekly.setImageBitmap(BarRenderer.render(0, null, WEEKLY_FILL, null))
+            binding.tvWeeklyUsage.text = "—"
+        }
+
+        // Pace text removed per design — bars carry the signal.
+        binding.tvSessionPace.visibility = View.GONE
+        binding.tvWeeklyPace.visibility = View.GONE
+
+        binding.tvUsage.text = when {
+            data.fiveHourUtilization >= 0f -> {
+                val pct = data.fiveHourUtilization.toInt()
+                "$pct% of limit used"
+            }
+            data.messagesLimit > 0 && data.effectiveUsed >= 0 ->
+                "${data.effectiveUsed} of ${data.messagesLimit} messages used"
+            data.effectiveRemaining >= 0 && data.messagesLimit > 0 ->
+                "${data.effectiveRemaining} of ${data.messagesLimit} remaining"
+            data.effectiveRemaining >= 0 ->
+                "${data.effectiveRemaining} messages remaining"
+            else -> "Usage data unavailable"
+        }
+
+        binding.tvReset.text = formatReset(data.effectiveResetEpoch)
+        binding.tvWeeklyReset.text = formatResetDay(data.weeklyResetAtEpoch)
+        binding.tvUpdated.text = if (data.lastUpdated > 0)
+            "Last updated: ${SimpleDateFormat("h:mm a, MMM d", Locale.US).format(Date(data.lastUpdated))}"
+        else ""
+
+        binding.tvError.text = data.errorMessage
+        binding.tvError.visibility = if (data.errorMessage.isNotBlank()) View.VISIBLE else View.GONE
+
+        binding.historyChart.setData(prefs.getHistory())
+    }
+
+    private fun formatReset(epochMs: Long): String {
+        if (epochMs <= 0) return ""
+        val now = System.currentTimeMillis()
+        if (epochMs <= now) return "Resets soon"
+        val diffH = TimeUnit.MILLISECONDS.toHours(epochMs - now)
+        val timeStr = SimpleDateFormat("h:mm a", Locale.US).format(Date(epochMs))
+        return when {
+            diffH < 24 -> "Resets at $timeStr"
+            diffH < 48 -> "Resets tomorrow $timeStr"
+            else -> "Resets ${SimpleDateFormat("EEE", Locale.US).format(Date(epochMs))} $timeStr"
+        }
+    }
+
+    /** Weekly reset shown with the weekday name ("Resets Friday 3:00 PM"), never "tomorrow". */
+    private fun formatResetDay(epochMs: Long): String {
+        if (epochMs <= 0) return ""
+        if (epochMs <= System.currentTimeMillis()) return "Resets soon"
+        val day = SimpleDateFormat("EEEE", Locale.US).format(Date(epochMs))
+        val date = SimpleDateFormat("MMM d", Locale.US).format(Date(epochMs))
+        val timeStr = SimpleDateFormat("h:mm a", Locale.US).format(Date(epochMs))
+        return "Resets $day, $date · $timeStr"
+    }
+
+    companion object {
+        private const val REFRESH_INTERVAL_MS = 30_000L   // live refresh cadence while app is open
+        private const val SESSION_FILL = 0xFFCC785C.toInt()
+        private const val WEEKLY_FILL = 0xFF7B8FCC.toInt()
+        private const val MARKER_COLOR = 0xFFFFFFFF.toInt()   // single-color weekly pace marker
+        private const val PEAK_ON = 0xFFCC785C.toInt()
+        private const val PEAK_OFF = 0xFF666666.toInt()
+    }
+}

app/src/main/java/me/khodak/claudeusage/Notifier.kt

@@ -0,0 +1,161 @@
+package me.khodak.claudeusage
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import me.khodak.claudeusage.data.PreferencesManager
+import me.khodak.claudeusage.data.UsageData
+
+/**
+ * Fires exactly two alerts per metric — one at 90% and one at 100% — and no more.
+ *
+ * Uses hysteresis, not the API's reset timestamp: each level fires once when usage first
+ * crosses it, and only re-arms after usage drops back below that level (i.e. a new window /
+ * usage reset). That keeps it quiet even if the reset time drifts between fetches. Only the
+ * background worker calls this — never the in-app refresh loop — so you're not pinged while
+ * you're already looking at the app.
+ */
+object Notifier {
+
+    private const val CHANNEL_ID = "usage_alerts"
+    private const val AUTH_CHANNEL_ID = "session_alerts"
+    private const val AUTH_NOTIF_ID = 3000
+    private val LEVELS = intArrayOf(90, 100)
+
+    /**
+     * Fired once when the saved claude.ai session is cleared after repeated 401/403s — without
+     * this the widget would just silently go stale and the user would have to notice the dead
+     * data themselves. Tapping opens LoginActivity straight to the cookie re-paste flow. Posts on
+     * its own channel so it can be muted independently of usage alerts, and is not gated on the
+     * usage-alert toggle: a dead widget is a functional failure the user needs to know about.
+     */
+    fun notifySessionExpired(context: Context) {
+        val mgr = NotificationManagerCompat.from(context)
+        if (!mgr.areNotificationsEnabled()) return
+        ensureAuthChannel(context)
+        val intent = Intent(context, LoginActivity::class.java)
+            .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
+        val pi = PendingIntent.getActivity(
+            context, 1, intent,
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+        )
+        val notif = NotificationCompat.Builder(context, AUTH_CHANNEL_ID)
+            .setSmallIcon(R.drawable.ic_claude_burst)
+            .setContentTitle("Claude sign-in expired")
+            .setContentText("Tap to sign in again — the widget can't update until you do.")
+            .setPriority(NotificationCompat.PRIORITY_HIGH)
+            .setAutoCancel(true)
+            .setContentIntent(pi)
+            .build()
+        try {
+            mgr.notify(AUTH_NOTIF_ID, notif)
+        } catch (_: SecurityException) {
+            // Notifications revoked between the check and post — nothing to do.
+        }
+    }
+
+    fun checkAndNotify(context: Context, prefs: PreferencesManager, data: UsageData) {
+        if (!prefs.isNotifyEnabled()) return
+        val mgr = NotificationManagerCompat.from(context)
+        if (!mgr.areNotificationsEnabled()) return  // OS-level or runtime permission off
+        ensureChannel(context)
+
+        evaluate(context, mgr, prefs, "session", data.fiveHourUtilization, "5-hour session")
+        evaluate(context, mgr, prefs, "weekly", data.weeklyUtilization, "weekly")
+    }
+
+    private fun evaluate(
+        context: Context,
+        mgr: NotificationManagerCompat,
+        prefs: PreferencesManager,
+        metric: String,
+        utilization: Float,
+        label: String
+    ) {
+        if (utilization < 0f) return
+        val util = utilization.toInt()
+        for ((i, level) in LEVELS.withIndex()) {
+            val key = "${metric}_$level"
+            if (util >= level) {
+                if (!prefs.wasNotified(key)) {
+                    fire(context, mgr, notifId(metric, i), level, label, util)
+                    prefs.setNotified(key, true)
+                }
+            } else if (prefs.wasNotified(key)) {
+                prefs.setNotified(key, false)  // dropped below the line → re-arm for next window
+            }
+        }
+    }
+
+    private fun fire(
+        context: Context,
+        mgr: NotificationManagerCompat,
+        notifId: Int,
+        level: Int,
+        label: String,
+        util: Int
+    ) {
+        val title: String
+        val body: String
+        if (level >= 100) {
+            title = "${label.replaceFirstChar { it.uppercase() }} limit reached"
+            body = "You've hit 100% of your $label limit."
+        } else {
+            title = "${label.replaceFirstChar { it.uppercase() }} at $util%"
+            body = "You're at $level% of your $label limit."
+        }
+        val notif = NotificationCompat.Builder(context, CHANNEL_ID)
+            .setSmallIcon(R.drawable.ic_claude_burst)
+            .setContentTitle(title)
+            .setContentText(body)
+            .setPriority(NotificationCompat.PRIORITY_DEFAULT)
+            .setAutoCancel(true)
+            .setContentIntent(openAppIntent(context))
+            .build()
+        try {
+            mgr.notify(notifId, notif)
+        } catch (_: SecurityException) {
+            // Notifications revoked between the check and post — nothing to do.
+        }
+    }
+
+    // Stable id per (metric, level) so re-posts replace rather than stack.
+    private fun notifId(metric: String, levelIndex: Int) =
+        2000 + (if (metric == "weekly") 10 else 0) + levelIndex
+
+    private fun ensureAuthChannel(context: Context) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+        val mgr = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        if (mgr.getNotificationChannel(AUTH_CHANNEL_ID) != null) return
+        mgr.createNotificationChannel(
+            NotificationChannel(
+                AUTH_CHANNEL_ID, "Sign-in alerts", NotificationManager.IMPORTANCE_HIGH
+            ).apply { description = "Tells you when your claude.ai session expires and needs re-auth" }
+        )
+    }
+
+    private fun ensureChannel(context: Context) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+        val mgr = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        if (mgr.getNotificationChannel(CHANNEL_ID) != null) return
+        mgr.createNotificationChannel(
+            NotificationChannel(
+                CHANNEL_ID, "Usage alerts", NotificationManager.IMPORTANCE_DEFAULT
+            ).apply { description = "Alerts at 90% and 100% of your Claude usage limits" }
+        )
+    }
+
+    private fun openAppIntent(context: Context): PendingIntent {
+        val intent = Intent(context, MainActivity::class.java)
+            .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
+        return PendingIntent.getActivity(
+            context, 0, intent,
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+        )
+    }
+}

app/src/main/java/me/khodak/claudeusage/PaceCalc.kt

@@ -62,14 +62,4 @@ object PaceCalc {
         }
         return Pace(markerPct, projected, color, label)
     }
-
-    /** Short tag for the widget reset line, e.g. "8% under pace" / "20% over pace" / "on pace". */
-    fun shortTag(usedPct: Float, pace: Pace): String {
-        val delta = usedPct.toInt() - pace.markerPct
-        return when {
-            delta >= 2 -> "$delta% over pace"
-            delta <= -2 -> "${-delta}% under pace"
-            else -> "on pace"
-        }
-    }
 }

app/src/main/java/me/khodak/claudeusage/RingRenderer.kt

@@ -0,0 +1,120 @@
+package me.khodak.claudeusage
+
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Paint
+import android.graphics.RectF
+import android.graphics.Typeface
+import kotlin.math.cos
+import kotlin.math.sin
+
+/**
+ * Draws a usage gauge as a circular ring Bitmap: rounded track ring + colored progress arc
+ * (sweeping clockwise from 12 o'clock) + an optional radial pace tick + center percentage and
+ * label. The ring counterpart to [BarRenderer] — same Bitmap contract, so it drops into both the
+ * home-screen widget (setImageViewBitmap) and the in-app card and renders identically.
+ *
+ * Design mirrors hamed-elfayome/Claude-Usage-Tracker's ring gauges, using this app's existing
+ * palette (SESSION_FILL clay / WEEKLY_FILL periwinkle, #252525 track, white pace marker).
+ */
+object RingRenderer {
+
+    private const val TRACK_COLOR = 0xFF252525.toInt()
+    private const val CENTER_TEXT_COLOR = 0xFFFFFFFF.toInt()
+    private const val LABEL_TEXT_COLOR = 0xFF999999.toInt()
+
+    /**
+     * @param usedPct      0..100 fill of the ring
+     * @param markerPct    where you "should be" right now (pace), or null for no tick
+     * @param fillColor    ARGB progress-arc color (e.g. SESSION_FILL / WEEKLY_FILL)
+     * @param markerColor  ARGB pace-tick color, or null
+     * @param centerText   big text in the middle, e.g. "47%" (caller formats it)
+     * @param labelText    small caption under the number, e.g. "SESSION" (null hides it)
+     * @param sizePx       square bitmap edge; ring scales to fit
+     * @param strokePx     ring thickness
+     */
+    fun render(
+        usedPct: Int,
+        markerPct: Int?,
+        fillColor: Int,
+        markerColor: Int?,
+        centerText: String,
+        labelText: String? = null,
+        sizePx: Int = 360,
+        strokePx: Float = 36f
+    ): Bitmap {
+        val bmp = Bitmap.createBitmap(sizePx, sizePx, Bitmap.Config.ARGB_8888)
+        val canvas = Canvas(bmp)
+        val cx = sizePx / 2f
+        val cy = sizePx / 2f
+        val pad = strokePx / 2f + 2f
+        val arcRect = RectF(pad, pad, sizePx - pad, sizePx - pad)
+        val radius = (sizePx - strokePx) / 2f - 2f
+
+        // Track ring (full circle).
+        val track = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            style = Paint.Style.STROKE
+            strokeWidth = strokePx
+            strokeCap = Paint.Cap.ROUND
+            color = TRACK_COLOR
+        }
+        canvas.drawArc(arcRect, 0f, 360f, false, track)
+
+        // Progress arc — clockwise from 12 o'clock (-90°).
+        val pct = usedPct.coerceIn(0, 100)
+        if (pct > 0) {
+            val fill = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+                style = Paint.Style.STROKE
+                strokeWidth = strokePx
+                strokeCap = Paint.Cap.ROUND
+                color = fillColor
+            }
+            canvas.drawArc(arcRect, -90f, pct / 100f * 360f, false, fill)
+        }
+
+        // Pace tick — a short radial mark across the ring at the "should be here" angle.
+        if (markerPct != null && markerColor != null) {
+            val m = markerPct.coerceIn(0, 100)
+            val ang = Math.toRadians((-90f + m / 100f * 360f).toDouble())
+            val rInner = radius - strokePx / 2f - 1f
+            val rOuter = radius + strokePx / 2f + 1f
+            val tick = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+                style = Paint.Style.STROKE
+                strokeWidth = strokePx * 0.18f
+                strokeCap = Paint.Cap.ROUND
+                color = markerColor
+            }
+            canvas.drawLine(
+                cx + (rInner * cos(ang)).toFloat(), cy + (rInner * sin(ang)).toFloat(),
+                cx + (rOuter * cos(ang)).toFloat(), cy + (rOuter * sin(ang)).toFloat(),
+                tick
+            )
+        }
+
+        // Center percentage.
+        val hasLabel = !labelText.isNullOrEmpty()
+        val valuePaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            color = CENTER_TEXT_COLOR
+            textAlign = Paint.Align.CENTER
+            textSize = sizePx * 0.27f
+            typeface = Typeface.create(Typeface.DEFAULT, Typeface.BOLD)
+        }
+        val vfm = valuePaint.fontMetrics
+        val valueBaselineShift = -(vfm.ascent + vfm.descent) / 2f
+        val valueY = cy + valueBaselineShift - (if (hasLabel) sizePx * 0.07f else 0f)
+        canvas.drawText(centerText, cx, valueY, valuePaint)
+
+        if (hasLabel) {
+            val labelPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+                color = LABEL_TEXT_COLOR
+                textAlign = Paint.Align.CENTER
+                textSize = sizePx * 0.105f
+                letterSpacing = 0.12f
+                typeface = Typeface.create(Typeface.DEFAULT, Typeface.BOLD)
+            }
+            canvas.drawText(labelText!!.uppercase(), cx, cy + sizePx * 0.17f, labelPaint)
+        }
+
+        return bmp
+    }
+}

app/src/main/java/me/khodak/claudeusage/ThemeColors.kt

@@ -0,0 +1,30 @@
+package me.khodak.claudeusage
+
+import android.content.Context
+import android.os.Build
+import me.khodak.claudeusage.data.PreferencesManager
+
+/**
+ * Central source of the two accent colors used by the bars/rings (session + weekly).
+ *
+ * Default = the Claude brand palette. When the user enables Material You *and* the device is
+ * Android 12+ (where the wallpaper-derived `system_accent*` palette exists), the fills switch to
+ * the dynamic system accents so the widget matches the rest of the home screen. On older devices
+ * the toggle is a no-op and the brand colors are always used.
+ */
+object ThemeColors {
+
+    const val SESSION_DEFAULT = 0xFFCC785C.toInt()   // Claude orange
+    const val WEEKLY_DEFAULT = 0xFF7B8FCC.toInt()    // Claude periwinkle
+
+    private fun dynamicAvailable(prefs: PreferencesManager): Boolean =
+        prefs.isMaterialYou() && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
+
+    fun sessionFill(context: Context, prefs: PreferencesManager): Int =
+        if (dynamicAvailable(prefs)) context.getColor(android.R.color.system_accent1_300)
+        else SESSION_DEFAULT
+
+    fun weeklyFill(context: Context, prefs: PreferencesManager): Int =
+        if (dynamicAvailable(prefs)) context.getColor(android.R.color.system_accent2_300)
+        else WEEKLY_DEFAULT
+}

app/src/main/java/me/khodak/claudeusage/UsageRepository.kt

@@ -54,16 +54,15 @@ class UsageRepository(private val prefs: PreferencesManager) {
 
         if (orgId == null) return@withContext base.copy(errorMessage = "Can't reach claude.ai")
 
-        if (orgUsageData?.hasRateLimitData == true) {
+        // NOTE: message-count data from the org endpoint (orgUsageData) is a FALLBACK only — do
-            return@withContext base.copy(
+        // NOT return here. The /usage utilization endpoint below is the preferred signal and the
-                messagesUsed = orgUsageData.messagesUsed,
+        // one the weekly bar + in-app history chart depend on, so it must be attempted whenever we
-                messagesLimit = orgUsageData.messagesLimit,
+        // have an org id. Returning early here was why the history chart stayed empty: any account
-                messagesRemaining = orgUsageData.messagesRemaining,
+        // whose org JSON carried a message limit short-circuited before /usage, so
-                resetAtEpoch = orgUsageData.resetAtEpoch
+        // fiveHourUtilization/weeklyUtilization never got populated and recordHistory() had nothing
-            )
+        // to store. The org message data is used only if /usage yields nothing (fallback below).
-        }
 
-        // Step 2: /usage endpoint — returns utilization percentages
+        // Step 2: /usage endpoint — returns utilization percentages (preferred signal)
         try {
             val usageUrl = "https://claude.ai/api/organizations/$orgId/usage"
             val resp = client.newCall(buildRequest(usageUrl, cookies)).execute()
@@ -77,6 +76,7 @@ class UsageRepository(private val prefs: PreferencesManager) {
             if (BuildConfig.DEBUG) debugBuf.append("$usageUrl\n→ $code: ${body.take(400)}\n\n")
             val utilData = tryParseUtilizationBody(body)
             if (utilData != null) {
+                prefs.resetAuthFailCount()
                 return@withContext base.copy(
                     fiveHourUtilization = utilData.fiveHourUtilization,
                     weeklyUtilization = utilData.weeklyUtilization,
@@ -85,7 +85,19 @@ class UsageRepository(private val prefs: PreferencesManager) {
                 )
             }
         } catch (e: Exception) {
-            Log.w(TAG, "/usage failed: ${e.message}")
+            if (BuildConfig.DEBUG) Log.w(TAG, "/usage failed: ${e.message}")
+        }
+
+        // /usage gave no utilization → fall back to the message-count data the org endpoint
+        // already returned (this is the early-return that used to live before Step 2).
+        if (orgUsageData?.hasRateLimitData == true) {
+            prefs.resetAuthFailCount()
+            return@withContext base.copy(
+                messagesUsed = orgUsageData.messagesUsed,
+                messagesLimit = orgUsageData.messagesLimit,
+                messagesRemaining = orgUsageData.messagesRemaining,
+                resetAtEpoch = orgUsageData.resetAtEpoch
+            )
         }
 
         // Step 3: fallback endpoints (message-count style)
@@ -102,9 +114,14 @@ class UsageRepository(private val prefs: PreferencesManager) {
                 if (BuildConfig.DEBUG) Log.d(TAG, "GET $url → $code")
 
                 if (code == 401 || code == 403) {
+                    if (prefs.incAuthFailCount() >= AUTH_FAIL_LIMIT) {
                         prefs.clearSession()
+                        prefs.resetAuthFailCount()
                         return@withContext UsageData(errorMessage = "Session expired — please sign in again")
                     }
+                    // Transient auth failure — keep showing last-good data instead of logging out.
+                    return@withContext base
+                }
 
                 val rateLimitData = extractRateLimitHeaders(resp.headers)
                 val body = resp.body?.string() ?: ""
@@ -341,5 +358,8 @@ class UsageRepository(private val prefs: PreferencesManager) {
 
     companion object {
         private const val TAG = "UsageRepo"
+        // Clear the session only after this many consecutive 401/403s, so one transient
+        // auth failure (Cloudflare challenge, brief edge hiccup) doesn't sign the user out.
+        private const val AUTH_FAIL_LIMIT = 3
     }
 }

app/src/main/java/me/khodak/claudeusage/UsageUpdateWorker.kt

@@ -31,7 +31,16 @@ class UsageUpdateWorker(
             val animJob = launch { rotateRefreshIcon() }
             try {
                 val data = UsageRepository(prefs).fetchUsage()
-                prefs.saveUsageData(data)
+                // We passed the isLoggedIn() guard above, so if the session is gone now the
+                // cookie just expired this cycle — tell the user once (next cycle returns early).
+                if (!prefs.isLoggedIn()) {
+                    Notifier.notifySessionExpired(context)
+                } else {
+                    // Preserve last-good data so a failed/partial fetch never blanks the widget.
+                    prefs.saveUsageData(data.mergedWith(prefs.getUsageData()))
+                    prefs.recordHistory(data)       // history records only fresh readings
+                    Notifier.checkAndNotify(context, prefs, data)
+                }
             } catch (_: Exception) {}
             animJob.cancel()
             animJob.join()

app/src/main/java/me/khodak/claudeusage/data/PreferencesManager.kt

@@ -4,6 +4,7 @@ import android.content.Context
 import androidx.security.crypto.EncryptedSharedPreferences
 import androidx.security.crypto.MasterKey
 import com.google.gson.Gson
+import com.google.gson.reflect.TypeToken
 import java.util.Calendar
 
 class PreferencesManager(context: Context) {
@@ -23,9 +24,14 @@ class PreferencesManager(context: Context) {
         } catch (_: Exception) {}
     }
 
-    fun getCookies(): String? = try {
+    fun getCookies(): String? {
+        // Cookies are never written in fallback (plaintext) mode — make that invariant explicit on
+        // the read side too, so any future write that bypasses the guard still can't surface here.
+        if (usingFallbackPrefs) return null
+        return try {
             securePrefs.getString(KEY_COOKIES, null)
         } catch (_: Exception) { null }
+    }
 
     fun clearSession() {
         try { securePrefs.edit().clear().apply() } catch (_: Exception) {}
@@ -73,6 +79,114 @@ class PreferencesManager(context: Context) {
 
     fun isLoggedIn(): Boolean = !getCookies().isNullOrBlank()
 
+    // Consecutive 401/403 counter — we only clear the session after several in a row, so a
+    // single transient auth failure (e.g. a Cloudflare challenge) doesn't log the user out.
+    fun getAuthFailCount(): Int = prefs.getInt(KEY_AUTH_FAILS, 0)
+    fun incAuthFailCount(): Int {
+        val n = getAuthFailCount() + 1
+        prefs.edit().putInt(KEY_AUTH_FAILS, n).apply()
+        return n
+    }
+    fun resetAuthFailCount() {
+        if (getAuthFailCount() != 0) prefs.edit().putInt(KEY_AUTH_FAILS, 0).apply()
+    }
+
+    // ── Usage history (for the in-app chart) ─────────────────────────────────
+
+    /**
+     * Append a history point if [data] carries a real reading.
+     * The session line uses [UsageData.sessionReadingPct] (utilization preferred, message-count
+     * progress as fallback) so accounts that only expose message counts still build history.
+     * De-duplicates rapid double-fires (manual refresh + background worker landing
+     * together) by skipping points within [MIN_HISTORY_GAP_MS] of the last one, and
+     * prunes anything older than [HISTORY_RETENTION_MS] / beyond [MAX_HISTORY_POINTS].
+     */
+    fun recordHistory(data: UsageData) {
+        val sessionPct = data.sessionReadingPct
+        if (sessionPct < 0f && data.weeklyUtilization < 0f) return
+        val now = System.currentTimeMillis()
+        val history = getHistory().toMutableList()
+        // Throttle to at most one point per MIN_HISTORY_GAP_MS by SKIPPING a too-soon reading.
+        // (Previously we deleted the last point and re-added in place — but the foreground loop
+        // refreshes every 30s, well inside this 2-min window, so history could never grow past a
+        // single point while the app was open and the chart stayed on "Collecting history…".)
+        if (!shouldRecordHistory(history.lastOrNull()?.epochMs, now, MIN_HISTORY_GAP_MS)) return
+        history.add(
+            UsageSnapshot(
+                epochMs = now,
+                sessionPct = sessionPct,
+                weeklyPct = data.weeklyUtilization
+            )
+        )
+        val cutoff = now - HISTORY_RETENTION_MS
+        val pruned = history.filter { it.epochMs >= cutoff }
+            .takeLast(MAX_HISTORY_POINTS)
+        prefs.edit().putString(KEY_HISTORY, gson.toJson(pruned)).apply()
+    }
+
+    fun getHistory(): List<UsageSnapshot> {
+        val json = prefs.getString(KEY_HISTORY, null) ?: return emptyList()
+        return try {
+            val type = object : TypeToken<List<UsageSnapshot>>() {}.type
+            gson.fromJson<List<UsageSnapshot>>(json, type) ?: emptyList()
+        } catch (e: Exception) { emptyList() }
+    }
+
+    // ── Widget style ─────────────────────────────────────────────────────────
+
+    /** Home-screen widget visual style: [STYLE_BARS] (default) or [STYLE_RINGS]. */
+    fun getWidgetStyle(): String = prefs.getString(KEY_WIDGET_STYLE, STYLE_BARS) ?: STYLE_BARS
+    fun setWidgetStyle(style: String) = prefs.edit().putString(KEY_WIDGET_STYLE, style).apply()
+
+    // ── Notification settings ────────────────────────────────────────────────
+
+    fun isNotifyEnabled(): Boolean = prefs.getBoolean(KEY_NOTIFY_ENABLED, true)
+    fun setNotifyEnabled(v: Boolean) = prefs.edit().putBoolean(KEY_NOTIFY_ENABLED, v).apply()
+
+    // ── Material You (dynamic color) ─────────────────────────────────────────
+
+    /** When on (and Android 12+), bars/rings use the wallpaper-derived system accents. */
+    fun isMaterialYou(): Boolean = prefs.getBoolean(KEY_MATERIAL_YOU, false)
+    fun setMaterialYou(v: Boolean) = prefs.edit().putBoolean(KEY_MATERIAL_YOU, v).apply()
+
+    // ── Settings backup / restore ────────────────────────────────────────────
+
+    /**
+     * Serialize the user-tunable settings (NOT the session cookie or usage data) to JSON, so a
+     * reinstall doesn't lose preferences. Cookies are deliberately excluded — they're sensitive and
+     * device-bound, so a backup file stays safe to store anywhere.
+     */
+    fun exportSettings(): String = gson.toJson(
+        mapOf(
+            "version" to 1,
+            KEY_NOTIFY_ENABLED to isNotifyEnabled(),
+            KEY_WIDGET_STYLE to getWidgetStyle(),
+            KEY_MATERIAL_YOU to isMaterialYou()
+        )
+    )
+
+    /** Apply a settings JSON produced by [exportSettings]. Returns true if it parsed and applied. */
+    fun importSettings(json: String): Boolean = try {
+        @Suppress("UNCHECKED_CAST")
+        val map = gson.fromJson(json, Map::class.java) as Map<String, Any?>
+        val e = prefs.edit()
+        (map[KEY_NOTIFY_ENABLED] as? Boolean)?.let { e.putBoolean(KEY_NOTIFY_ENABLED, it) }
+        (map[KEY_MATERIAL_YOU] as? Boolean)?.let { e.putBoolean(KEY_MATERIAL_YOU, it) }
+        (map[KEY_WIDGET_STYLE] as? String)?.let {
+            if (it == STYLE_BARS || it == STYLE_RINGS) e.putString(KEY_WIDGET_STYLE, it)
+        }
+        e.apply()
+        true
+    } catch (_: Exception) { false }
+
+    /**
+     * Per-level "already alerted" flag (e.g. "session_90"). Set when the level is crossed,
+     * cleared when usage drops back below it — so each level fires once per window.
+     */
+    fun wasNotified(key: String): Boolean = prefs.getBoolean("notified_$key", false)
+    fun setNotified(key: String, v: Boolean) =
+        prefs.edit().putBoolean("notified_$key", v).apply()
+
     companion object {
         private const val KEY_COOKIES = "session_cookies"
         private const val KEY_ORG_ID = "org_id"
@@ -80,6 +194,29 @@ class PreferencesManager(context: Context) {
         private const val KEY_USAGE_DATA = "usage_data"
         private const val KEY_ACTIVE_WEEK = "active_week"
         private const val KEY_ACTIVE_MASK = "active_mask"
+        private const val KEY_HISTORY = "usage_history"
+        private const val KEY_NOTIFY_ENABLED = "notify_enabled"
+        private const val KEY_AUTH_FAILS = "auth_fail_count"
+        private const val KEY_WIDGET_STYLE = "widget_style"
+        private const val KEY_MATERIAL_YOU = "material_you"
+
+        const val STYLE_BARS = "bars"
+        const val STYLE_RINGS = "rings"
+
+        internal const val MIN_HISTORY_GAP_MS = 2 * 60 * 1000L      // collapse readings <2 min apart
+        private const val HISTORY_RETENTION_MS = 7 * 24 * 60 * 60 * 1000L  // keep 7 days
+        private const val MAX_HISTORY_POINTS = 600
+
+        /**
+         * Pure throttle decision for [recordHistory]: should a new point be appended?
+         * Returns false only when a previous point exists ([lastEpochMs] != null) AND the gap to
+         * [now] is below [minGapMs]; true otherwise (including the first-ever point, lastEpochMs == null).
+         * No Android dependencies — kept separate so the throttle rule is unit-testable.
+         */
+        internal fun shouldRecordHistory(lastEpochMs: Long?, now: Long, minGapMs: Long): Boolean {
+            if (lastEpochMs == null) return true
+            return now - lastEpochMs >= minGapMs
+        }
 
         fun createSecurePrefs(context: Context, onFallback: (() -> Unit)? = null): android.content.SharedPreferences {
             return try {

app/src/main/java/me/khodak/claudeusage/data/UsageData.kt

@@ -43,10 +43,55 @@ data class UsageData(
 
     val weeklyActiveDays: Int get() = Integer.bitCount(weeklyActiveDaysMask)
 
+    /**
+     * Session utilization as a 0-100 reading for the history chart, preferring the /usage
+     * utilization endpoint and falling back to message-count progress. Returns -1f when there is
+     * no usable reading — so message-only accounts (no utilization endpoint) still build history
+     * instead of leaving the chart permanently on "Collecting history…".
+     */
+    val sessionReadingPct: Float get() = when {
+        fiveHourUtilization >= 0f -> fiveHourUtilization
+        messagesLimit > 0 && effectiveUsed >= 0 ->
+            ((effectiveUsed.toFloat() / messagesLimit.toFloat()) * 100f).coerceIn(0f, 100f)
+        else -> -1f
+    }
+
     // The best reset time we have (utilization endpoint is preferred)
     val effectiveResetEpoch: Long get() = when {
         utilizationResetAtEpoch > 0 -> utilizationResetAtEpoch
         resetAtEpoch > 0 -> resetAtEpoch
         else -> -1L
     }
+
+    /** True if this fetch produced any usable usage reading at all. */
+    val hasAnyReading: Boolean get() =
+        fiveHourUtilization >= 0f || weeklyUtilization >= 0f || hasRateLimitData
+
+    /**
+     * Merge a fresh fetch over the last cached reading so a failed or partial refresh never
+     * blanks the widget. If this fetch got nothing usable, the whole previous snapshot is kept
+     * (with its original timestamp, so the footer shows the data's true age). Otherwise each
+     * metric this fetch didn't return falls back to the previous value.
+     */
+    fun mergedWith(previous: UsageData?): UsageData {
+        if (previous == null || !previous.hasAnyReading) return this
+        if (!hasAnyReading) {
+            // Keep last-good data; only carry this attempt's login/session context forward.
+            return previous.copy(
+                isLoggedIn = isLoggedIn,
+                sessionStartEpoch = if (sessionStartEpoch > 0) sessionStartEpoch else previous.sessionStartEpoch,
+                weeklyActiveDaysMask = if (weeklyActiveDaysMask != 0) weeklyActiveDaysMask else previous.weeklyActiveDaysMask
+            )
+        }
+        return copy(
+            fiveHourUtilization = if (fiveHourUtilization >= 0f) fiveHourUtilization else previous.fiveHourUtilization,
+            utilizationResetAtEpoch = if (fiveHourUtilization >= 0f) utilizationResetAtEpoch else previous.utilizationResetAtEpoch,
+            weeklyUtilization = if (weeklyUtilization >= 0f) weeklyUtilization else previous.weeklyUtilization,
+            weeklyResetAtEpoch = if (weeklyUtilization >= 0f) weeklyResetAtEpoch else previous.weeklyResetAtEpoch,
+            messagesLimit = if (messagesLimit > 0) messagesLimit else previous.messagesLimit,
+            messagesUsed = if (messagesUsed >= 0) messagesUsed else previous.messagesUsed,
+            messagesRemaining = if (messagesRemaining >= 0) messagesRemaining else previous.messagesRemaining,
+            resetAtEpoch = if (resetAtEpoch > 0) resetAtEpoch else previous.resetAtEpoch
+        )
+    }
 }

app/src/main/java/me/khodak/claudeusage/data/UsageSnapshot.kt

@@ -0,0 +1,11 @@
+package me.khodak.claudeusage.data
+
+/**
+ * A single point-in-time reading of usage, stored for the in-app history chart.
+ * Percentages are 0-100; -1 means "no reading for this metric at this time".
+ */
+data class UsageSnapshot(
+    val epochMs: Long = 0L,
+    val sessionPct: Float = -1f,
+    val weeklyPct: Float = -1f
+)

app/src/main/res/layout/activity_main.xml

@@ -229,6 +229,248 @@
 
             </LinearLayout>
 
+            <!-- History card -->
+            <LinearLayout
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:orientation="vertical"
+                android:background="@drawable/widget_background"
+                android:padding="20dp"
+                android:layout_marginTop="16dp">
+
+                <TextView
+                    android:layout_width="wrap_content"
+                    android:layout_height="wrap_content"
+                    android:text="HISTORY"
+                    android:textColor="#888888"
+                    android:textSize="11sp"
+                    android:letterSpacing="0.1" />
+
+                <me.khodak.claudeusage.HistoryChartView
+                    android:id="@+id/historyChart"
+                    android:layout_width="match_parent"
+                    android:layout_height="140dp"
+                    android:layout_marginTop="12dp" />
+
+                <!-- Legend -->
+                <LinearLayout
+                    android:layout_width="wrap_content"
+                    android:layout_height="wrap_content"
+                    android:orientation="horizontal"
+                    android:layout_marginTop="10dp"
+                    android:gravity="center_vertical">
+
+                    <View
+                        android:layout_width="12dp"
+                        android:layout_height="3dp"
+                        android:background="#CC785C" />
+
+                    <TextView
+                        android:layout_width="wrap_content"
+                        android:layout_height="wrap_content"
+                        android:layout_marginStart="6dp"
+                        android:layout_marginEnd="16dp"
+                        android:text="Session"
+                        android:textColor="#AAAAAA"
+                        android:textSize="12sp" />
+
+                    <View
+                        android:layout_width="12dp"
+                        android:layout_height="3dp"
+                        android:background="#7B8FCC" />
+
+                    <TextView
+                        android:layout_width="wrap_content"
+                        android:layout_height="wrap_content"
+                        android:layout_marginStart="6dp"
+                        android:text="Weekly"
+                        android:textColor="#AAAAAA"
+                        android:textSize="12sp" />
+
+                </LinearLayout>
+
+            </LinearLayout>
+
+            <!-- Widget style card -->
+            <LinearLayout
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:orientation="vertical"
+                android:background="@drawable/widget_background"
+                android:padding="20dp"
+                android:layout_marginTop="16dp">
+
+                <LinearLayout
+                    android:layout_width="match_parent"
+                    android:layout_height="wrap_content"
+                    android:orientation="horizontal"
+                    android:gravity="center_vertical">
+
+                    <TextView
+                        android:layout_width="0dp"
+                        android:layout_height="wrap_content"
+                        android:layout_weight="1"
+                        android:text="RING WIDGET STYLE"
+                        android:textColor="#888888"
+                        android:textSize="11sp"
+                        android:letterSpacing="0.1" />
+
+                    <com.google.android.material.switchmaterial.SwitchMaterial
+                        android:id="@+id/switchRingStyle"
+                        android:layout_width="wrap_content"
+                        android:layout_height="wrap_content" />
+
+                </LinearLayout>
+
+                <TextView
+                    android:layout_width="match_parent"
+                    android:layout_height="wrap_content"
+                    android:layout_marginTop="12dp"
+                    android:text="Show usage as circular rings instead of bars on the full-size home-screen widget."
+                    android:textColor="#AAAAAA"
+                    android:textSize="13sp"
+                    android:lineSpacingExtra="3dp" />
+
+            </LinearLayout>
+
+            <!-- Material You card -->
+            <LinearLayout
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:orientation="vertical"
+                android:background="@drawable/widget_background"
+                android:padding="20dp"
+                android:layout_marginTop="16dp">
+
+                <LinearLayout
+                    android:layout_width="match_parent"
+                    android:layout_height="wrap_content"
+                    android:orientation="horizontal"
+                    android:gravity="center_vertical">
+
+                    <TextView
+                        android:layout_width="0dp"
+                        android:layout_height="wrap_content"
+                        android:layout_weight="1"
+                        android:text="MATERIAL YOU COLORS"
+                        android:textColor="#888888"
+                        android:textSize="11sp"
+                        android:letterSpacing="0.1" />
+
+                    <com.google.android.material.switchmaterial.SwitchMaterial
+                        android:id="@+id/switchMaterialYou"
+                        android:layout_width="wrap_content"
+                        android:layout_height="wrap_content" />
+
+                </LinearLayout>
+
+                <TextView
+                    android:layout_width="match_parent"
+                    android:layout_height="wrap_content"
+                    android:layout_marginTop="12dp"
+                    android:text="Use your wallpaper-derived system accent colors for the bars/rings (Android 12+). Off = Claude brand colors."
+                    android:textColor="#AAAAAA"
+                    android:textSize="13sp"
+                    android:lineSpacingExtra="3dp" />
+
+            </LinearLayout>
+
+            <!-- Notifications card -->
+            <LinearLayout
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:orientation="vertical"
+                android:background="@drawable/widget_background"
+                android:padding="20dp"
+                android:layout_marginTop="16dp">
+
+                <LinearLayout
+                    android:layout_width="match_parent"
+                    android:layout_height="wrap_content"
+                    android:orientation="horizontal"
+                    android:gravity="center_vertical">
+
+                    <TextView
+                        android:layout_width="0dp"
+                        android:layout_height="wrap_content"
+                        android:layout_weight="1"
+                        android:text="USAGE ALERTS"
+                        android:textColor="#888888"
+                        android:textSize="11sp"
+                        android:letterSpacing="0.1" />
+
+                    <com.google.android.material.switchmaterial.SwitchMaterial
+                        android:id="@+id/switchNotify"
+                        android:layout_width="wrap_content"
+                        android:layout_height="wrap_content" />
+
+                </LinearLayout>
+
+                <TextView
+                    android:layout_width="match_parent"
+                    android:layout_height="wrap_content"
+                    android:layout_marginTop="12dp"
+                    android:text="One alert at 90% and one at 100%, for both your session and weekly limits. Each fires once until usage resets."
+                    android:textColor="#AAAAAA"
+                    android:textSize="13sp"
+                    android:lineSpacingExtra="3dp" />
+
+            </LinearLayout>
+
+            <!-- Backup & Restore card -->
+            <LinearLayout
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:orientation="vertical"
+                android:background="@drawable/widget_background"
+                android:padding="20dp"
+                android:layout_marginTop="16dp">
+
+                <TextView
+                    android:layout_width="match_parent"
+                    android:layout_height="wrap_content"
+                    android:text="BACKUP &amp; RESTORE"
+                    android:textColor="#888888"
+                    android:textSize="11sp"
+                    android:letterSpacing="0.1" />
+
+                <TextView
+                    android:layout_width="match_parent"
+                    android:layout_height="wrap_content"
+                    android:layout_marginTop="12dp"
+                    android:text="Save your settings (widget style, Material You, alerts) to a file so a reinstall doesn't lose them. The Claude session cookie is never included."
+                    android:textColor="#AAAAAA"
+                    android:textSize="13sp"
+                    android:lineSpacingExtra="3dp" />
+
+                <LinearLayout
+                    android:layout_width="match_parent"
+                    android:layout_height="wrap_content"
+                    android:orientation="horizontal"
+                    android:layout_marginTop="14dp">
+
+                    <Button
+                        android:id="@+id/btnExportSettings"
+                        android:layout_width="0dp"
+                        android:layout_weight="1"
+                        android:layout_height="wrap_content"
+                        android:layout_marginEnd="6dp"
+                        android:text="Export"
+                        style="?attr/materialButtonOutlinedStyle" />
+
+                    <Button
+                        android:id="@+id/btnImportSettings"
+                        android:layout_width="0dp"
+                        android:layout_weight="1"
+                        android:layout_height="wrap_content"
+                        android:layout_marginStart="6dp"
+                        android:text="Import"
+                        style="?attr/materialButtonOutlinedStyle" />
+
+                </LinearLayout>
+
+            </LinearLayout>
+
             <Button
                 android:id="@+id/btnRefresh"
                 android:layout_width="match_parent"

app/src/main/res/layout/widget_layout.xml

@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools"
     android:id="@+id/widget_root"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
@@ -48,6 +49,7 @@
             android:src="@android:drawable/ic_menu_rotate"
             android:background="@android:color/transparent"
             android:tint="#999999"
+            tools:ignore="UseAppTint"
             android:contentDescription="Refresh" />
 
     </LinearLayout>

app/src/main/res/layout/widget_layout_rings.xml

@@ -0,0 +1,169 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Ring style of the full (4x2) widget. Header + footer mirror widget_layout.xml (same view
+     IDs) so ClaudeUsageWidget can attach the same click intents and peak/refresh state; the middle
+     swaps the two horizontal bars for two circular RingRenderer gauges side by side. -->
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools"
+    android:id="@+id/widget_root"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:orientation="vertical"
+    android:background="@drawable/widget_background"
+    android:padding="14dp">
+
+    <!-- Header -->
+    <LinearLayout
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:orientation="horizontal"
+        android:gravity="center_vertical">
+
+        <TextView
+            android:layout_width="0dp"
+            android:layout_height="wrap_content"
+            android:layout_weight="1"
+            android:text="Claude Pro"
+            android:textColor="#FFFFFF"
+            android:textSize="13sp"
+            android:textStyle="bold" />
+
+        <ImageView
+            android:id="@+id/img_peak"
+            android:layout_width="16dp"
+            android:layout_height="16dp"
+            android:layout_marginEnd="4dp"
+            android:src="@drawable/ic_claude_burst"
+            android:contentDescription="Peak hours" />
+
+        <TextView
+            android:id="@+id/tv_peak"
+            android:layout_width="wrap_content"
+            android:layout_height="wrap_content"
+            android:layout_marginEnd="6dp"
+            android:text=""
+            android:textColor="#CC785C"
+            android:textSize="9sp"
+            android:textStyle="bold" />
+
+        <ImageButton
+            android:id="@+id/btn_refresh"
+            android:layout_width="32dp"
+            android:layout_height="32dp"
+            android:src="@android:drawable/ic_menu_rotate"
+            android:background="@android:color/transparent"
+            android:tint="#999999"
+            tools:ignore="UseAppTint"
+            android:contentDescription="Refresh" />
+
+    </LinearLayout>
+
+    <!-- Divider -->
+    <TextView
+        android:layout_width="match_parent"
+        android:layout_height="1dp"
+        android:layout_marginTop="8dp"
+        android:layout_marginBottom="6dp"
+        android:background="#2A2A2A" />
+
+    <!-- Two ring gauges side by side — each fills its half so the ring grows as large as the
+         placed widget allows (limited by the available height), instead of a fixed 86dp. -->
+    <LinearLayout
+        android:layout_width="match_parent"
+        android:layout_height="0dp"
+        android:layout_weight="1"
+        android:orientation="horizontal"
+        android:gravity="center"
+        android:weightSum="2">
+
+        <LinearLayout
+            android:layout_width="0dp"
+            android:layout_height="match_parent"
+            android:layout_weight="1"
+            android:orientation="vertical"
+            android:gravity="center_horizontal">
+
+            <ImageView
+                android:id="@+id/ring_session"
+                android:layout_width="match_parent"
+                android:layout_height="0dp"
+                android:layout_weight="1"
+                android:scaleType="fitCenter"
+                android:adjustViewBounds="false"
+                android:contentDescription="Session usage ring" />
+
+            <TextView
+                android:id="@+id/tv_session_label"
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:layout_marginTop="2dp"
+                android:gravity="center"
+                android:text=""
+                android:textColor="#999999"
+                android:textSize="10sp"
+                android:textStyle="bold" />
+
+        </LinearLayout>
+
+        <LinearLayout
+            android:layout_width="0dp"
+            android:layout_height="match_parent"
+            android:layout_weight="1"
+            android:orientation="vertical"
+            android:gravity="center_horizontal">
+
+            <ImageView
+                android:id="@+id/ring_weekly"
+                android:layout_width="match_parent"
+                android:layout_height="0dp"
+                android:layout_weight="1"
+                android:scaleType="fitCenter"
+                android:adjustViewBounds="false"
+                android:contentDescription="Weekly usage ring" />
+
+            <TextView
+                android:id="@+id/tv_weekly_label"
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:layout_marginTop="2dp"
+                android:gravity="center"
+                android:text=""
+                android:textColor="#999999"
+                android:textSize="10sp"
+                android:textStyle="bold" />
+
+        </LinearLayout>
+
+    </LinearLayout>
+
+    <!-- Footer -->
+    <LinearLayout
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:orientation="horizontal"
+        android:layout_marginTop="6dp"
+        android:gravity="center_vertical">
+
+        <TextView
+            android:id="@+id/tv_status"
+            android:layout_width="0dp"
+            android:layout_height="wrap_content"
+            android:layout_weight="1"
+            android:text=""
+            android:textColor="#FFFFFF"
+            android:textSize="9sp"
+            android:textStyle="bold"
+            android:singleLine="true"
+            android:ellipsize="end" />
+
+        <TextView
+            android:id="@+id/tv_updated"
+            android:layout_width="wrap_content"
+            android:layout_height="wrap_content"
+            android:text=""
+            android:textColor="#FFFFFF"
+            android:textSize="9sp"
+            android:textStyle="bold" />
+
+    </LinearLayout>
+
+</LinearLayout>

app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/ic_launcher_bg" />
+    <foreground android:drawable="@mipmap/ic_launcher_foreground" />
+</adaptive-icon>

app/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/ic_launcher_bg" />
+    <foreground android:drawable="@mipmap/ic_launcher_foreground" />
+</adaptive-icon>

app/src/main/res/mipmap-hdpi/ic_launcher.xml

@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@color/claude_orange" />
-    <foreground>
-        <inset
-            xmlns:android="http://schemas.android.com/apk/res/android"
-            android:drawable="@drawable/ic_launcher_fg"
-            android:inset="25%" />
-    </foreground>
-</adaptive-icon>

app/src/main/res/mipmap-hdpi/ic_launcher_round.xml

@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@color/claude_orange" />
-    <foreground>
-        <inset
-            xmlns:android="http://schemas.android.com/apk/res/android"
-            android:drawable="@drawable/ic_launcher_fg"
-            android:inset="25%" />
-    </foreground>
-</adaptive-icon>

app/src/main/res/mipmap-mdpi/ic_launcher.xml

@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@color/claude_orange" />
-    <foreground>
-        <inset
-            xmlns:android="http://schemas.android.com/apk/res/android"
-            android:drawable="@drawable/ic_launcher_fg"
-            android:inset="25%" />
-    </foreground>
-</adaptive-icon>

app/src/main/res/mipmap-mdpi/ic_launcher_round.xml

@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@color/claude_orange" />
-    <foreground>
-        <inset
-            xmlns:android="http://schemas.android.com/apk/res/android"
-            android:drawable="@drawable/ic_launcher_fg"
-            android:inset="25%" />
-    </foreground>
-</adaptive-icon>

app/src/main/res/mipmap-xhdpi/ic_launcher.xml

@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@color/claude_orange" />
-    <foreground>
-        <inset
-            xmlns:android="http://schemas.android.com/apk/res/android"
-            android:drawable="@drawable/ic_launcher_fg"
-            android:inset="25%" />
-    </foreground>
-</adaptive-icon>

app/src/main/res/mipmap-xhdpi/ic_launcher_round.xml

@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@color/claude_orange" />
-    <foreground>
-        <inset
-            xmlns:android="http://schemas.android.com/apk/res/android"
-            android:drawable="@drawable/ic_launcher_fg"
-            android:inset="25%" />
-    </foreground>
-</adaptive-icon>

app/src/main/res/mipmap-xxhdpi/ic_launcher.xml

@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@color/claude_orange" />
-    <foreground>
-        <inset
-            xmlns:android="http://schemas.android.com/apk/res/android"
-            android:drawable="@drawable/ic_launcher_fg"
-            android:inset="25%" />
-    </foreground>
-</adaptive-icon>

app/src/main/res/mipmap-xxhdpi/ic_launcher_round.xml

@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@color/claude_orange" />
-    <foreground>
-        <inset
-            xmlns:android="http://schemas.android.com/apk/res/android"
-            android:drawable="@drawable/ic_launcher_fg"
-            android:inset="25%" />
-    </foreground>
-</adaptive-icon>

app/src/main/res/mipmap-xxxhdpi/ic_launcher.xml

@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@color/claude_orange" />
-    <foreground>
-        <inset
-            xmlns:android="http://schemas.android.com/apk/res/android"
-            android:drawable="@drawable/ic_launcher_fg"
-            android:inset="25%" />
-    </foreground>
-</adaptive-icon>

app/src/main/res/mipmap-xxxhdpi/ic_launcher_round.xml

@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@color/claude_orange" />
-    <foreground>
-        <inset
-            xmlns:android="http://schemas.android.com/apk/res/android"
-            android:drawable="@drawable/ic_launcher_fg"
-            android:inset="25%" />
-    </foreground>
-</adaptive-icon>

app/src/main/res/values/colors.xml

@@ -5,4 +5,5 @@
     <color name="surface_dark">#1E1E1E</color>
     <color name="text_primary">#FFFFFF</color>
     <color name="text_secondary">#888888</color>
+    <color name="ic_launcher_bg">#0B1D27</color>
 </resources>

app/src/test/java/me/khodak/claudeusage/HistoryThrottleTest.kt

@@ -0,0 +1,44 @@
+package me.khodak.claudeusage
+
+import me.khodak.claudeusage.data.PreferencesManager
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Pure-JVM tests for the history-throttle decision extracted from PreferencesManager.recordHistory.
+ * No Android Context — exercises only PreferencesManager.shouldRecordHistory.
+ */
+class HistoryThrottleTest {
+
+    private val gap = PreferencesManager.MIN_HISTORY_GAP_MS
+
+    @Test
+    fun returnsTrueWhenNoPreviousPoint() {
+        // First-ever reading (lastEpochMs == null) is always recorded.
+        assertTrue(PreferencesManager.shouldRecordHistory(null, now = 1_000_000L, minGapMs = gap))
+    }
+
+    @Test
+    fun returnsFalseWhenWithinGap() {
+        val last = 1_000_000L
+        // One millisecond before the gap elapses → throttled.
+        val now = last + gap - 1L
+        assertFalse(PreferencesManager.shouldRecordHistory(last, now, gap))
+    }
+
+    @Test
+    fun returnsTrueExactlyAtGapBoundary() {
+        val last = 1_000_000L
+        // Exactly at the gap (>= boundary is inclusive) → recorded.
+        val now = last + gap
+        assertTrue(PreferencesManager.shouldRecordHistory(last, now, gap))
+    }
+
+    @Test
+    fun returnsTrueAfterGap() {
+        val last = 1_000_000L
+        val now = last + gap + 1L
+        assertTrue(PreferencesManager.shouldRecordHistory(last, now, gap))
+    }
+}

app/src/test/java/me/khodak/claudeusage/PaceCalcTest.kt

@@ -0,0 +1,75 @@
+package me.khodak.claudeusage
+
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Pure-JVM tests for PaceCalc.compute. The clock is injected via the `now` parameter, so these are
+ * deterministic and require no Android framework.
+ */
+class PaceCalcTest {
+
+    private val window = PaceCalc.SESSION_WINDOW_MS // 5h
+
+    @Test
+    fun computeReturnsPaceForValidFutureReset() {
+        // Place "now" halfway through the window (elapsedFraction = 0.5, within [0.03, 1.0)).
+        val resetEpoch = 10_000_000_000L
+        val now = resetEpoch - window / 2
+        val pace = PaceCalc.compute(usedPct = 25f, resetEpoch = resetEpoch, windowMs = window, now = now)
+
+        assertNotNull(pace)
+        val p = pace!!
+        // markerPct mirrors elapsedFraction*100 → ~50, and must stay in 0..100.
+        assertTrue("markerPct in range", p.markerPct in 0..100)
+        assertEquals50(p.markerPct)
+    }
+
+    @Test
+    fun markerPctAlwaysInRangeNearWindowEnd() {
+        // Near the end of the window (95% elapsed, still < 1.0) marker approaches 100, never exceeds.
+        // Kept off the exact boundary so Float rounding of (window-elapsed)/window can't tip it to 1.0.
+        val resetEpoch = 10_000_000_000L
+        val now = resetEpoch - (window * 5L / 100L) // 95% elapsed
+        val pace = PaceCalc.compute(usedPct = 80f, resetEpoch = resetEpoch, windowMs = window, now = now)
+
+        assertNotNull(pace)
+        assertTrue(pace!!.markerPct in 0..100)
+    }
+
+    @Test
+    fun computeReturnsNullForPastReset() {
+        // Reset already passed → elapsedFraction >= 1.0 → null.
+        val resetEpoch = 10_000_000_000L
+        val now = resetEpoch + 60_000L
+        assertNull(PaceCalc.compute(usedPct = 50f, resetEpoch = resetEpoch, windowMs = window, now = now))
+    }
+
+    @Test
+    fun computeReturnsNullTooEarlyInWindow() {
+        // Less than 3% elapsed → not enough signal → null.
+        val resetEpoch = 10_000_000_000L
+        val now = resetEpoch - window + (window * 0.01f).toLong() // 1% elapsed
+        assertNull(PaceCalc.compute(usedPct = 5f, resetEpoch = resetEpoch, windowMs = window, now = now))
+    }
+
+    @Test
+    fun computeReturnsNullForNonPositiveReset() {
+        assertNull(PaceCalc.compute(usedPct = 50f, resetEpoch = 0L, windowMs = window))
+        assertNull(PaceCalc.compute(usedPct = 50f, resetEpoch = -1L, windowMs = window))
+    }
+
+    @Test
+    fun computeReturnsNullForNegativeUsedPct() {
+        val resetEpoch = 10_000_000_000L
+        val now = resetEpoch - window / 2
+        assertNull(PaceCalc.compute(usedPct = -1f, resetEpoch = resetEpoch, windowMs = window, now = now))
+    }
+
+    private fun assertEquals50(markerPct: Int) {
+        // elapsedFraction 0.5 → (0.5*100).toInt() == 50.
+        org.junit.Assert.assertEquals(50, markerPct)
+    }
+}

app/src/test/java/me/khodak/claudeusage/PeakHoursTest.kt

@@ -0,0 +1,58 @@
+package me.khodak.claudeusage
+
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import java.util.Calendar
+import java.util.GregorianCalendar
+import java.util.TimeZone
+
+/**
+ * Pure-JVM tests for PeakHours.isPeak. The clock is injected via `now`, and PeakHours evaluates the
+ * window in America/Los_Angeles regardless of the device timezone — so we build each instant in PT
+ * explicitly, making these deterministic without touching the system clock.
+ */
+class PeakHoursTest {
+
+    private val pt: TimeZone = TimeZone.getTimeZone("America/Los_Angeles")
+
+    /** Absolute epoch millis for the given wall-clock time in PT on a fixed reference date. */
+    private fun ptInstant(year: Int, month0: Int, day: Int, hour: Int): Long {
+        val cal = GregorianCalendar(pt)
+        cal.clear()
+        cal.set(year, month0, day, hour, 0, 0)
+        return cal.timeInMillis
+    }
+
+    @Test
+    fun activeOnWeekdayInsideWindow() {
+        // 2026-06-10 is a Wednesday. 8 AM PT is inside 5–11 AM.
+        assertTrue(PeakHours.isPeak(ptInstant(2026, Calendar.JUNE, 10, 8)))
+    }
+
+    @Test
+    fun inactiveAtStartBoundaryIsInclusiveButBeforeIsNot() {
+        // 5 AM PT is inside (inclusive start); 4 AM PT is outside.
+        assertTrue(PeakHours.isPeak(ptInstant(2026, Calendar.JUNE, 10, 5)))
+        assertFalse(PeakHours.isPeak(ptInstant(2026, Calendar.JUNE, 10, 4)))
+    }
+
+    @Test
+    fun inactiveAtEndBoundaryExclusive() {
+        // 11 AM PT is the exclusive end → not peak.
+        assertFalse(PeakHours.isPeak(ptInstant(2026, Calendar.JUNE, 10, 11)))
+    }
+
+    @Test
+    fun inactiveOnWeekendEvenInsideHours() {
+        // 2026-06-13 is a Saturday, 2026-06-14 is a Sunday. 8 AM PT, but weekend → not peak.
+        assertFalse(PeakHours.isPeak(ptInstant(2026, Calendar.JUNE, 13, 8)))
+        assertFalse(PeakHours.isPeak(ptInstant(2026, Calendar.JUNE, 14, 8)))
+    }
+
+    @Test
+    fun inactiveOnWeekdayEvening() {
+        // 8 PM PT Wednesday → outside the morning window.
+        assertFalse(PeakHours.isPeak(ptInstant(2026, Calendar.JUNE, 10, 20)))
+    }
+}

app/src/test/java/me/khodak/claudeusage/UsageDataTest.kt

@@ -0,0 +1,180 @@
+package me.khodak.claudeusage
+
+import me.khodak.claudeusage.data.UsageData
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertSame
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Pure-JVM tests for the UsageData data class: derived metrics and the mergedWith fallback logic.
+ * UsageData has no Android dependencies, so these run on the plain JVM.
+ */
+class UsageDataTest {
+
+    @Test
+    fun progressPercentMessagesPath() {
+        // messagesLimit > 0 and effectiveUsed derived from messagesUsed → 25/100 = 25%.
+        val d = UsageData(messagesUsed = 25, messagesLimit = 100)
+        assertEquals(25, d.progressPercent)
+    }
+
+    @Test
+    fun progressPercentMessagesPathCoercedTo100() {
+        // Used above limit must clamp to 100, never exceed.
+        val d = UsageData(messagesUsed = 150, messagesLimit = 100)
+        assertEquals(100, d.progressPercent)
+    }
+
+    @Test
+    fun progressPercentUtilizationPathWhenNoMessages() {
+        // No messages limit → fall through to utilization, truncated to Int and coerced.
+        val d = UsageData(fiveHourUtilization = 42.9f)
+        assertEquals(42, d.progressPercent)
+    }
+
+    @Test
+    fun progressPercentUtilizationCoercedTo100() {
+        val d = UsageData(fiveHourUtilization = 130f)
+        assertEquals(100, d.progressPercent)
+    }
+
+    @Test
+    fun progressPercentZeroWhenNoReadings() {
+        assertEquals(0, UsageData().progressPercent)
+    }
+
+    @Test
+    fun effectiveUsedPrefersMessagesUsed() {
+        assertEquals(30, UsageData(messagesUsed = 30, messagesLimit = 100).effectiveUsed)
+    }
+
+    @Test
+    fun effectiveUsedDerivedFromRemaining() {
+        // No messagesUsed, but remaining + limit present → limit - remaining.
+        val d = UsageData(messagesRemaining = 40, messagesLimit = 100)
+        assertEquals(60, d.effectiveUsed)
+    }
+
+    @Test
+    fun effectiveUsedUnknownIsNegativeOne() {
+        assertEquals(-1, UsageData().effectiveUsed)
+    }
+
+    @Test
+    fun effectiveRemainingPrefersRemaining() {
+        assertEquals(40, UsageData(messagesRemaining = 40, messagesLimit = 100).effectiveRemaining)
+    }
+
+    @Test
+    fun effectiveRemainingDerivedFromUsed() {
+        val d = UsageData(messagesUsed = 70, messagesLimit = 100)
+        assertEquals(30, d.effectiveRemaining)
+    }
+
+    @Test
+    fun effectiveRemainingUnknownIsNegativeOne() {
+        assertEquals(-1, UsageData().effectiveRemaining)
+    }
+
+    @Test
+    fun hasAnyReadingTrueWithUtilization() {
+        assertTrue(UsageData(fiveHourUtilization = 10f).hasAnyReading)
+        assertTrue(UsageData(weeklyUtilization = 5f).hasAnyReading)
+    }
+
+    @Test
+    fun hasAnyReadingTrueWithRateLimitData() {
+        // hasRateLimitData true when messagesLimit > 0.
+        assertTrue(UsageData(messagesLimit = 100).hasAnyReading)
+    }
+
+    @Test
+    fun hasAnyReadingFalseWhenEmpty() {
+        assertFalse(UsageData().hasAnyReading)
+    }
+
+    @Test
+    fun sessionReadingPctPrefersUtilization() {
+        // Utilization present → used verbatim (kept as Float, not truncated), even alongside messages.
+        val d = UsageData(fiveHourUtilization = 42.5f, messagesUsed = 10, messagesLimit = 100)
+        assertEquals(42.5f, d.sessionReadingPct, 0f)
+    }
+
+    @Test
+    fun sessionReadingPctFallsBackToMessages() {
+        // No utilization → derive from message counts so message-only accounts still get history.
+        val d = UsageData(messagesUsed = 30, messagesLimit = 120)
+        assertEquals(25f, d.sessionReadingPct, 0f)
+    }
+
+    @Test
+    fun sessionReadingPctMessagesCoercedTo100() {
+        val d = UsageData(messagesUsed = 150, messagesLimit = 100)
+        assertEquals(100f, d.sessionReadingPct, 0f)
+    }
+
+    @Test
+    fun sessionReadingPctNegativeWhenNoReading() {
+        // No utilization and no message data → -1f, so recordHistory skips the point.
+        assertEquals(-1f, UsageData().sessionReadingPct, 0f)
+    }
+
+    @Test
+    fun mergedWithEmptyFetchKeepsPreviousMetrics() {
+        // (a) previous has a reading; this fetch is empty (all defaults) → previous metrics kept.
+        val previous = UsageData(
+            fiveHourUtilization = 55f,
+            utilizationResetAtEpoch = 1_000L,
+            weeklyUtilization = 20f,
+            weeklyResetAtEpoch = 2_000L,
+            messagesLimit = 100,
+            messagesUsed = 40
+        )
+        val emptyFetch = UsageData(isLoggedIn = true)
+        val merged = emptyFetch.mergedWith(previous)
+
+        assertEquals(55f, merged.fiveHourUtilization, 0f)
+        assertEquals(20f, merged.weeklyUtilization, 0f)
+        assertEquals(100, merged.messagesLimit)
+        assertEquals(40, merged.messagesUsed)
+        assertEquals(1_000L, merged.utilizationResetAtEpoch)
+        assertEquals(2_000L, merged.weeklyResetAtEpoch)
+        // Login context from the fresh (empty) attempt is carried forward.
+        assertTrue(merged.isLoggedIn)
+    }
+
+    @Test
+    fun mergedWithPartialFetchUnionsBothWindows() {
+        // (b) previous only had five-hour; this fetch only has weekly → result has both.
+        val previous = UsageData(
+            fiveHourUtilization = 33f,
+            utilizationResetAtEpoch = 500L
+        )
+        val partial = UsageData(
+            weeklyUtilization = 77f,
+            weeklyResetAtEpoch = 900L
+        )
+        val merged = partial.mergedWith(previous)
+
+        assertEquals(33f, merged.fiveHourUtilization, 0f)
+        assertEquals(500L, merged.utilizationResetAtEpoch)
+        assertEquals(77f, merged.weeklyUtilization, 0f)
+        assertEquals(900L, merged.weeklyResetAtEpoch)
+    }
+
+    @Test
+    fun mergedWithNullPreviousReturnsThis() {
+        // (c) previous == null → returns this unchanged.
+        val fetch = UsageData(fiveHourUtilization = 12f)
+        assertSame(fetch, fetch.mergedWith(null))
+    }
+
+    @Test
+    fun mergedWithPreviousWithoutReadingReturnsThis() {
+        // previous has no usable reading → this is returned unchanged.
+        val fetch = UsageData(fiveHourUtilization = 12f)
+        assertSame(fetch, fetch.mergedWith(UsageData()))
+    }
+}

keystore.properties.example

@@ -0,0 +1,12 @@
+# Release signing credentials for local builds.
+# Copy to `keystore.properties` (which is gitignored) and fill in the real values.
+# These are NEVER committed. CI injects the same values from Gitea Actions secrets.
+#
+#   cp keystore.properties.example keystore.properties
+#
+# The keystore file itself (app/claude-widget-release.keystore) is also gitignored.
+# Signing identity is unchanged from older builds — same keystore, same alias.
+
+storePassword=CHANGE_ME
+keyPassword=CHANGE_ME
+keyAlias=claudewidget