2.0.0+44

Add home-screen widget support via AndroidX Glance.

The widget renders the current UTC time and schedules exact-minute
updates through AlarmManager. Glance requires API 23+, so minSdk is
bumped from 21 to 23 and the theme/resource tree is refactored
accordingly.

SCHEDULE_EXACT_ALARM (API 31+) is handled reactively: the widget shows
a prompt when the permission is missing, and tapping it launches the
system alarm settings directly. A new PermissionsRepository exposes
the permission state as a Flow so the Glance composition recomposes
immediately on grant, after which the user returns to the home screen.

Widget lifecycle:
- GlanceAppWidgetReceiver enables/disables a dedicated
  WidgetBroadcastReceiver based on whether widgets exist
- WidgetBroadcastReceiver handles MY_PACKAGE_REPLACED,
  ACTION_APP_STARTED, disclaimer state changes, update alarms, and
  exact-alarm permission changes
- DisclaimerStateBroadcaster notifies widgets when disclaimer
  acceptance state changes
- AlarmManager.setExact(RTC) schedules minute-boundary updates
  without waking the device

Also:
- Widget UI tests (4 scenarios) with helpers factored into
  widget/util/ to cope with launcher differences across API 23-36
- Widget removal support on all API levels via device.drag() (< 29)
  and input motionevent (29+)
- CI matrix expanded to API 23, 30, and 36 emulators (all Nexus 6)
- Remove clearPackageData from test orchestrator (caused app
  uninstall on API 23)
- Fix ZonedDateRepositoryImplFunctionalTests to use Thread.sleep
  instead of virtual-time delay() inside runTest
- Build: warnings as errors, additional lint rules, AGP version
  lint check disabled
- Text-to-bitmap rendering with auto font sizing for the widget
- Dependency bumps (Kotlin, AGP, Compose BOM, Hilt, Gradle, etc.)
- Rename BroadcastReceiver to WidgetBroadcastReceiver to fix Hilt
  ASM instrumentation conflict with android.content.BroadcastReceiver
- Restore KSP plugin (annotationProcessor doesn't process Kotlin)
- Remove deprecated edge-to-edge APIs in favor of enableEdgeToEdge()

Author: elevenfive

.github/workflows/android.yml

@@ -29,8 +29,13 @@ jobs:
         run: |
           ./gradlew dependencyUpdates --refresh-dependencies --no-parallel
 
-  build:
+  build-and-test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Test on both min SDK (23) and target SDK (36) as well as an intermediate version (30)
+        # These must be kept in sync with minSdk and targetSdk in app/build.gradle.kts
+        api-level: [23, 30, 36]
 
     steps:
       - name: checkout
@@ -60,13 +65,13 @@ jobs:
           path: |
             ~/.android/avd/*
             ~/.android/adb*
-          key: avd-36
+          key: avd-${{ matrix.api-level }}
 
       - name: create AVD and generate snapshot for caching
         if: steps.avd-cache.outputs.cache-hit != 'true'
         uses: reactivecircus/android-emulator-runner@v2
         with:
-          api-level: 36
+          api-level: ${{ matrix.api-level }}
           target: google_apis
           arch: x86_64
           profile: Nexus 6
@@ -78,7 +83,7 @@ jobs:
       - name: run tests
         uses: reactivecircus/android-emulator-runner@v2
         with:
-          api-level: 36
+          api-level: ${{ matrix.api-level }}
           target: google_apis
           arch: x86_64
           profile: Nexus 6

.gitignore

@@ -12,3 +12,4 @@ local.properties
 app/release/**
 release/release.jks
 release/keystore-info.txt
+

CLAUDE.md

@@ -25,6 +25,22 @@ UTC Clock is a single-module Android application that displays UTC time with sup
 ./gradlew clean build
 ```
 
+## Development Workflow
+
+**IMPORTANT: Before considering any task complete:**
+
+1. **Always compile the code** to verify there are no compilation errors:
+   - For production code changes: `./gradlew assembleDebug`
+   - For UI test code changes: `./gradlew compileDebugAndroidTestKotlin`
+   - For unit test code changes: `./gradlew compileDebugUnitTestKotlin`
+
+2. **Always ask the user to run tests** before marking a task as complete:
+   - For unit test changes: Ask user to run `./gradlew test`
+   - For UI test changes: Ask user to run the relevant instrumented tests on a device/emulator
+   - Never assume tests pass without user confirmation
+
+3. **Never mark a task as complete** until both compilation succeeds AND the user confirms tests pass.
+
 ## Testing
 
 ```bash
@@ -37,6 +53,15 @@ UTC Clock is a single-module Android application that displays UTC time with sup
 # Run instrumented tests on connected device/emulator
 ./gradlew connectedAndroidTest
 
+# Run specific instrumented test class
+./gradlew app:connectedAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=<package.name.MyTestClass>
+
+# Run specific instrumented test method
+./gradlew app:connectedAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=<package.name.MyTestClass>#<testMethodName>
+
+# Example: Run only widget UI tests
+./gradlew app:connectedAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=com.dermochelys.utcclock.widget.WidgetUiTests
+
 # Run both unit and instrumented tests
 ./gradlew clean build connectedCheck
 ```
@@ -48,6 +73,42 @@ UTC Clock is a single-module Android application that displays UTC time with sup
 - **Test DI Modules**: Test modules in `app/src/androidTest/java/com/dermochelys/utcclock/di/` use `@TestInstallIn` to replace production modules.
 - **Test JVM Args**: Tests require `-XX:+EnableDynamicAgentLoading` for MockK compatibility (configured in app/build.gradle.kts).
 
+### Widget UI Testing
+
+Widget UI tests have API version-specific nuances due to launcher UI changes across Android versions as well as platform feature support differences.
+
+**API Version Differences:**
+
+- **Widget Addition**:
+  - **API 23-30**: Long press on the widget preview, then release to place on home screen (no expansion needed)
+  - **API 31**: Tap app name to expand (chevrons appear), long press on the widget preview, then release to place on home screen, then press HOME to complete placement
+  - **API 32+**: Tap app name to expand (chevrons appear), long press on the widget preview and drag upwards to place on the home screen, then press HOME to complete placement
+  - **Chevrons**: Chevrons appear in the widget picker on **API 31+** for expanding/collapsing widget options. The test helper taps the app name text to expand rather than looking for the chevron, as the chevron's resource ID/type changes across Android versions.
+  - **Widget Identification**: Widgets are identified by looking for `LauncherAppWidgetHostView` with contentDescription "UTC Clock". Falls back to checking for rootView FrameLayout if contentDescription is not found.
+  - **Widget State Verification**: Widget state is verified by checking TextView text inside the widget (the widget always includes invisible Text components with fontSize 0.sp for accessibility). Looks for "Tap to begin" or time format (HH:mm) with "UTC" indicator.
+
+- **Widget Removal**:
+  - **API 23-28**: Widget removal is not supported because the gesture is complex and shell commands for this complex gesture don't work properly until API 29+ (method returns early without attempting removal)
+  - **API 29+**: Widget removal is supported
+  - **API 29 & 30**: Removal drag is slower, performed in several very small steps
+  - **API 31+**: Smoother and faster drag motion
+
+**Test Infrastructure:**
+
+Widget test utilities are organized in `app/src/androidTest/java/com/dermochelys/utcclock/widget/util/`:
+- **Constants.kt**: Shared constants (text strings, resource IDs, class names)
+- **AppTasks.kt**: Common helper functions (finding elements, scrolling, etc.)
+- **Gestures.kt**: Gesture utilities (home screen, widget panel, long-press-drag)
+- **Finding.kt**: Widget finding and verification functions
+- **Adding.kt**: Widget addition logic (Api 31+)
+- **AddingLegacy.kt**: Widget addition logic (Before API 31)
+- **Removing.kt**: Widget removal logic
+
+**TODO's:**
+
+- Investigate widget loading failures seen on emulator during UI test runs - Sometimes the widget can say  "Failed to load widget" when first placing it on the home screen. Need to determine root cause and add retry logic or better error handling.
+- Further refine widget UI test helpers for increased brevity, understandability, reliability
+
 ## Code Quality & Linting
 
 ```bash
@@ -106,12 +167,20 @@ Implementations in `repository/internal/` package.
 - Injected with CoroutineScope (ViewModelScoped) for lifecycle-aware coroutine management
 - ViewModels manually call `coroutineScope.cancel()` in `onCleared()`
 
-**UI Pattern**: Fragments host Compose content while still using ViewBinding for the fragment layout. This hybrid approach will transition to pure Compose when Jetpack Navigation 3 is stable.
+**UI Pattern**: Fragments host Compose content while still using ViewBinding for the fragment layout. This hybrid approach is planned to transition to pure Compose using Jetpack Navigation 3, which is now stable.
 
 **State Management**:
 - ViewModels use Compose `mutableStateOf` for UI state
 - State can be saved/restored via `Bundle` in `onSaveInstanceState`/`onLoadInstanceState` methods when needed
 
+**TODO - Navigation 3 Migration:**
+- Migrate from Fragment-based navigation to pure Compose using Jetpack Navigation 3 (now stable)
+- Remove ViewBinding and Fragment dependencies
+- Convert all Fragment-based screens to pure Composable destinations
+- Update navigation graph from XML to Kotlin DSL
+- Consider impact on Hilt scoping (ViewModelComponent vs Navigation scoping)
+- Ensure TV navigation patterns remain optimized for d-pad/remote control
+
 ### Platform Detection
 
 The app detects Android TV using utilities in `view/common/TvUtils.kt` and provides TV-optimized UI variants (e.g., `TvDisclaimer.kt` vs `NonTvDisclaimer.kt`).
@@ -122,14 +191,47 @@ The app detects Android TV using utilities in `view/common/TvUtils.kt` and provi
 - System UI hiding via `window.hideSystemUi()` (view/common/WindowExt.kt)
 - Window insets are consumed to achieve full-screen display
 
+### Widget Implementation
+
+The app provides a Glance-based home screen widget (`UtcClockGlanceAppWidget`) that displays the current UTC time.
+
+**CRITICAL ALARM SCHEDULING REQUIREMENT:**
+- **NEVER use `*Idle` alarm methods** (`setExactAndAllowWhileIdle`, `setAndAllowWhileIdle`)
+- These methods interfere with Android Doze mode optimization and battery management
+- Always use `setExact()` or `set()` without the `*Idle` variants
+- Use `AlarmManager.RTC` (not `RTC_WAKEUP`) to avoid waking the device unnecessarily
+
+**Widget Lifecycle:**
+- Widget uses Hilt for dependency injection via `@AndroidEntryPoint`
+- `onEnabled()` is called only when the first widget instance is added
+- `onDisabled()` is called when the last widget instance is removed
+- `MY_PACKAGE_REPLACED` broadcast is handled to reschedule alarms after app reinstall/update
+  - Separate `BroadcastReceiver` class handles `MY_PACKAGE_REPLACED`
+  - Receiver is dynamically enabled/disabled based on widget state (enabled when widgets exist, disabled when no widgets)
+  - Only reschedules alarms if disclaimer is already accepted
+- Alarms are automatically cleared by Android on app uninstall and force stop
+
+**Implementation Details:**
+- Widget receiver: `GlanceAppWidgetReceiver` (extends `GlanceAppWidgetReceiver`)
+- Package replaced receiver: `BroadcastReceiver` (handles `MY_PACKAGE_REPLACED`, dynamically enabled/disabled)
+- Widget implementation: `UtcClockGlanceAppWidget` (object, extends `GlanceAppWidget`)
+- Update mechanism: Broadcasts to internal `ACTION_UPDATE_WIDGET` trigger updates
+- Alarm scheduling: Updates scheduled for exact minute boundaries using `AlarmManager.setExact()`
+
+**TODO - Force Stop Recovery:**
+- When user taps widget after force stop, Activity launches but alarms remain cancelled
+- Need to detect missing alarms in LandingViewModel and reschedule them (when disclaimer is accepted)
+- Use `PendingIntent.FLAG_NO_CREATE` to check if alarm exists, reschedule if not
+- Only reschedule if: (1) disclaimer accepted AND (2) widgets exist AND (3) alarms not scheduled
+
 ## Development Requirements
 
 - **JDK**: 21 (JVM toolchain version 21)
 - **Target SDK**: 36 (Android 15+)
-- **Min SDK**: 21 (Android 5.0)
+- **Min SDK**: 23 (Android 6.0)
 - **NDK**: 29.0.14206865
 - **Build Tools**: 36.0.0
-- **Current Version**: 1.10.0+40
+- **Current Version**: 2.0.0+41
 
 ## Dependency Management
 
@@ -144,11 +246,11 @@ Dependencies are managed via Gradle version catalogs in `gradle/libs.versions.to
 - **Hilt**: 2.57.2
 - **KSP**: 2.2.21-2.0.4
 - **Navigation**: 2.9.6
-- **Lifecycle**: 2.9.4 (held at this version as 2.10.0+ require minApi 23+)
-- **DataStore Preferences**: 1.1.7 (held at this version as 1.2.0+ require minApi 23+)
-- **Activity Compose**: 1.11.0 (held at this version as 1.12.0+ require minApi 23+)
+- **Lifecycle**: 2.9.4 (held at this version as 2.10.0+ require minApi 24+)
+- **DataStore Preferences**: 1.1.7 (held at this version as 1.2.0+ require minApi 24+)
+- **Activity Compose**: 1.11.0 (held at this version as 1.12.0+ require minApi 24+)
 
-Note: Several AndroidX dependencies are intentionally held back to maintain compatibility with API 21+.
+Note: Several AndroidX dependencies are intentionally held back to maintain compatibility with API 23.
 
 ## Build Configuration
 
@@ -178,6 +280,10 @@ GitHub Actions workflow (`.github/workflows/android.yml`) runs on push/PR to mai
 - Enables KVM for emulator
 - Caches AVD and Gradle
 - Checks for dependency updates with `./gradlew dependencyUpdates --refresh-dependencies --no-parallel`
-- Runs tests on API 36 emulator with Google APIs
-- Runs `./gradlew build connectedCheck`
+- Runs tests on **two emulators using matrix strategy**:
+  - **API 23** (minSdk) - tests minimum supported Android version
+  - **API 36** (targetSdk) - tests target Android version
+  - Both emulators use Google APIs, x86_64 architecture, Nexus 6 profile
+  - **IMPORTANT**: When updating minSdk or targetSdk in `app/build.gradle.kts`, the matrix API levels in `.github/workflows/android.yml` must be updated manually to match
+- Runs `./gradlew build connectedCheck` on both emulators
 - Checks Android ELF alignment