Spike: Evaluate options for cross-platform home screen widgets (Android + iOS)

[MessiasLima]

Description

Investigate the available options for adding home screen widgets to Foliary's mobile targets (Android and iOS) while maximizing the amount of code shared from our Kotlin Multiplatform codebase. Survey libraries and approaches that allow building widgets for both platforms from the same codebase, evaluate them against Foliary's constraints, and recommend a direction.

If the investigation confirms a viable solution, this spike's final outcome is to produce a new spike ticket that plans the implementation.

Background

Foliary is a task-management app. Home screen widgets showing today's tasks and overdue tasks are a high-value, low-friction feature. Android widgets (Jetpack Glance) and iOS widgets (WidgetKit) use different proprietary frameworks and UI languages, which normally means writing and maintaining two separate widget implementations. Foliary is KMP-first, so we want an approach that shares as much code as possible — ideally the widget UI itself — across Android and iOS.

Current Knowledge

• Foliary is a KMP app (foliary/ shared module) with Android, iOS (arm64 + simulator), and Desktop targets; data lives in a shared Room database.
• The foliary module already uses Kotlin 2.4.10, the Compose compiler plugin, the kotlinx-serialization plugin, and compose-runtime (foliary/build.gradle.kts).
• Android minSdk is 31; iOS deployment target is 18.6.
• Warp (https://github.com/DevAtrii/Warp, Maven Central io.github.devatrii:warp-widget:0.1.4, MIT): a KMP widget engine that renders one Compose-like DSL to native Glance RemoteViews (Android) and SwiftUI WidgetKit + AppIntents (iOS). 100% shared UI code, depends only on compose.runtime, ships its own state store and adaptive size bucketing. Explicitly Alpha; young project (27 stars, 0 forks, ~113 commits).
• Native Glance + SwiftUI WidgetKit with shared KMP logic (established pattern, e.g. John O'Reilly's BikeShare sample): share data models/repositories/business logic in commonMain, but write the widget UI twice — once in Glance (Kotlin/Compose) for Android, once in SwiftUI for iOS. No shared UI, no third-party dependency, uses stable first-party frameworks.
• No other dedicated "shared-code widget" KMP libraries were surfaced in initial searches; the category appears to be nascent.
• iOS widgets run in a separate extension process and need an App Group to share state with the main app; Android widgets also run in a separate process. Foliary's Room database and Warp's own state store are separate data sources — the data flow between them is an open question for both approaches.

Scope

In scope:

• Survey available libraries and approaches for cross-platform (Android + iOS) home screen widgets, including (but not limited to) Warp and the native Glance + WidgetKit pattern with shared KMP logic.
• For each candidate, assess: code-sharing ratio (UI vs logic), maturity and maintenance risk, integration effort with Foliary's Gradle/KMP setup, iOS App Group / Android widget-provider requirements, and feature coverage for a tasks widget (list of today's/overdue tasks).
• Verify how widget content would flow from Foliary's Room database into the widget on both platforms (update triggers, refresh strategy).
• Recommend a primary approach (and a fallback) with trade-offs.
• Define a minimal proof-of-concept widget to validate the recommended approach (e.g., a small widget listing today's tasks).
• Produce a follow-up spike ticket that plans the implementation, assuming a viable solution is confirmed.

Out of scope:

• Implementing the widget itself.
• Widgets for the Desktop target.
• App Store/Play Store release work for the widget.
• Redesigning the main app UI.

Outcomes

• Documented landscape review of at least two candidates (e.g., Warp and native Glance + WidgetKit with shared logic), comparing code-sharing ratio, maturity, maintenance risk, and platform coverage.
• Recommendation of a primary approach and a fallback, with trade-offs (shared UI vs. shared logic, Alpha-library risk, iOS 17 floor, app size, maintenance).
• Proven integration: a minimal working proof-of-concept widget on both Android and iOS, or a documented blocker explaining why not.
• Design for the data flow between Room task data and the widget (update triggers, refresh strategy, iOS App Group setup).
• Breakdown of the platform work required for a real widget (Android provider/manifest/config; iOS extension/entitlement/AppIntents).
• New spike ticket (or draft) that plans the implementation, created if and only if a viable solution is confirmed.