react-native-live-widgets 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/LICENSE +21 -0
  3. package/README.md +367 -2
  4. package/android/build.gradle +49 -0
  5. package/android/src/main/AndroidManifest.xml +38 -0
  6. package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +441 -0
  7. package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityPackage.kt +17 -0
  8. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityHeadlessTaskService.kt +24 -0
  9. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityNotifier.kt +410 -0
  10. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +67 -0
  11. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicNodeRegistry.kt +64 -0
  12. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +1223 -0
  13. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetImageCache.kt +120 -0
  14. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +281 -0
  15. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +229 -0
  16. package/android/src/main/res/layout/rn_live_widget_host.xml +113 -0
  17. package/android/src/main/res/xml/rn_live_widget_info.xml +14 -0
  18. package/app.plugin.js +114 -0
  19. package/assets/cross_platform_parity.png +0 -0
  20. package/assets/dashboard_features.png +0 -0
  21. package/assets/donate_qr.png +0 -0
  22. package/assets/dynamic_island_expanded.png +0 -0
  23. package/assets/home_widget_interactive.png +0 -0
  24. package/assets/lock_screen_live_activity.png +0 -0
  25. package/cli/setup.js +491 -0
  26. package/docs/EXPO-GUIDE-EN.md +405 -0
  27. package/docs/EXPO-GUIDE-VI.md +427 -0
  28. package/docs/GUIDE-EN.md +847 -0
  29. package/docs/GUIDE-VI.md +845 -0
  30. package/docs/widgets.md +52 -0
  31. package/ios/Bridge/LiveActivityModule.m +105 -0
  32. package/ios/Bridge/LiveActivityModule.swift +957 -0
  33. package/ios/Intents/DynamicWidgetActionIntent.swift +38 -0
  34. package/ios/Models/DynamicActivityAttributes.swift +22 -0
  35. package/ios/Models/DynamicLayoutModels.swift +243 -0
  36. package/ios/Renderer/ColorHexExtension.swift +49 -0
  37. package/ios/Renderer/DynamicNodeRegistry.swift +54 -0
  38. package/ios/Renderer/DynamicNodeView.swift +1060 -0
  39. package/ios/Storage/DynamicWidgetImageCache.swift +137 -0
  40. package/ios/Storage/DynamicWidgetStateStore.swift +162 -0
  41. package/ios/Widgets/DynamicHomeScreenWidget.swift +435 -0
  42. package/ios/Widgets/DynamicLiveActivityWidget.swift +79 -0
  43. package/lib/builder.d.ts +60 -0
  44. package/lib/builder.d.ts.map +1 -0
  45. package/lib/builder.js +292 -0
  46. package/lib/builder.js.map +1 -0
  47. package/lib/dispatcher.d.ts +16 -0
  48. package/lib/dispatcher.d.ts.map +1 -0
  49. package/lib/dispatcher.js +18 -0
  50. package/lib/dispatcher.js.map +1 -0
  51. package/lib/index.d.ts +199 -0
  52. package/lib/index.d.ts.map +1 -0
  53. package/lib/index.js +621 -0
  54. package/lib/index.js.map +1 -0
  55. package/lib/types.d.ts +489 -0
  56. package/lib/types.d.ts.map +1 -0
  57. package/lib/types.js +9 -0
  58. package/lib/types.js.map +1 -0
  59. package/package.json +85 -4
  60. package/react-native-live-widgets.podspec +38 -0
  61. package/src/builder.ts +409 -0
  62. package/src/dispatcher.ts +25 -0
  63. package/src/index.ts +689 -0
  64. package/src/react-native-env.d.ts +29 -0
  65. package/src/types.ts +595 -0
@@ -0,0 +1,847 @@
1
+ # REACT-NATIVE-LIVE-WIDGETS — COMPLETE SETUP & DEVELOPER GUIDE 🚀
2
+
3
+ > 🌐 **Language:** [Tiếng Việt (GUIDE-VI.md)](./GUIDE-VI.md) | **English** • [⚡ Dedicated Expo Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md)
4
+
5
+ Comprehensive guide covering installation, native setup (iOS & Android), and building 100% JavaScript/TypeScript declarative layouts for **Live Activities (Dynamic Island / Lock Screen / Android Live Updates)** and **Interactive Multi-Page Home Screen Widgets**.
6
+
7
+ > [!TIP]
8
+ > **Using Expo (SDK 50, 51, 52, 58+)?** Check out the [Dedicated Expo Integration Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md) for full details on Expo Config Plugins and EAS Build!
9
+
10
+ ---
11
+
12
+ ## TABLE OF CONTENTS
13
+ 1. [Overview & Architecture](#1-overview--architecture)
14
+ 2. [Official Live Demo Repositories (Expo & Bare RN)](#2-official-live-demo-repositories-expo--bare-rn)
15
+ 3. [Installation & Project Setup](#3-installation--project-setup)
16
+ - [For Expo Projects](#for-expo-projects)
17
+ - [Package Installation (Bare React Native)](#package-installation)
18
+ - [iOS Setup (Xcode & Widget Extension)](#ios-setup-xcode--widget-extension)
19
+ - [Android Setup (Gradle, Manifest, MainApplication & Permissions)](#android-setup-gradle-manifest-mainapplication--permissions)
20
+ - [Native Directory Architecture (`ios/` & `android/`)](#native-directory-architecture-ios--android)
21
+ 4. [Core API Reference](#4-core-api-reference)
22
+ - [LiveActivity API (Lock Screen, Dynamic Island & 3 Push Token Types)](#1-liveactivity-api)
23
+ - [Widget API (Home Screen Widgets, Multi-Page & Background Sync)](#2-widget-api-home-screen-widgets)
24
+ - [SharedStorage API (App Groups & SharedPreferences)](#3-sharedstorage-api)
25
+ 5. [Declarative UI Engine (`UI.*`)](#5-declarative-ui-engine-ui)
26
+ - [UI.VStack & UI.HStack](#uivstack--uihstack)
27
+ - [UI.Text](#uitext)
28
+ - [UI.Timer (Zero-Battery Hardware Timer)](#uitimer-zero-battery-hardware-timer)
29
+ - [UI.Progress (Bar, Segmented & Circular Progress)](#uiprogress-bar-segmented--circular-progress)
30
+ - [UI.Equalizer (Realtime Animated Music Waveform)](#uiequalizer-realtime-animated-music-waveform)
31
+ - [UI.Image (Remote URL, Base64, File, Asset & SF Symbols)](#uiimage-remote-url-base64-file-asset--sf-symbols)
32
+ - [UI.Button (Interactive Page Switching, Task Toggle, API Refresh & Deep Links)](#uibutton-interactive-widget-buttons)
33
+ 6. [Dynamic Island Configuration (iPhone 14 Pro, 15, 16, 17)](#6-dynamic-island-configuration-iphone-14-pro-15-16-17)
34
+ 7. [Building Multi-Page & Interactive Home Screen Widgets in JavaScript](#7-building-multi-page--interactive-home-screen-widgets-in-javascript)
35
+ - [Lock Screen Widgets on iOS (accessoryRectangular, circular, inline)](#lock-screen-widgets-on-ios)
36
+ - [In-App Pin Widget on Android](#in-app-pin-widget-on-android)
37
+ 8. [Background API Auto-Sync When App Is Killed (`Widget.setRemoteConfig`)](#8-background-api-auto-sync-when-app-is-killed-widgetsetremoteconfig)
38
+ 9. [Managing All 3 Push Token Types (APNs & FCM)](#9-managing-all-3-push-token-types-apns--fcm)
39
+ 10. [State Machine & Timed Phases (`phases`)](#10-state-machine--timed-phases-phases)
40
+ 11. [Server Push Payload Structure (APNs & FCM)](#11-server-push-payload-structure-apns--fcm)
41
+ 12. [Troubleshooting](#12-troubleshooting)
42
+
43
+ ---
44
+
45
+ ## 1. Overview & Architecture
46
+
47
+ **`react-native-live-widgets`** is an all-in-one library that lets you author **100% of your Home Screen Widget and Live Activity UI directly in React Native (`App.tsx`)**, rendering natively on both iOS and Android without writing custom SwiftUI or RemoteViews XML for each screen:
48
+
49
+ - **Live Activity (iOS 16.1+ ActivityKit & Dynamic Island):** Real-time ongoing activities (attendance shifts, ride-hailing, food delivery, Pomodoro timers).
50
+ - **Live Update (Android API 24 -> Android 16 API 36 `Notification.ProgressStyle`):** Promoted ongoing notifications on Android featuring custom avatars (`LargeIcon`), multi-step segmented progress bars, chronometer countdowns, and interactive action buttons.
51
+ - **Home Screen Widgets (iOS WidgetKit & Android AppWidget High-DPI Canvas Renderer):** Home screen widgets (`small`, `medium`, `large`) supporting in-place tab/page switching (`pages`), interactive checklists (`toggle`), remote URL/Base64 images, and background API synchronization even when the app is force-killed.
52
+ - **Shared Storage:** Instant bridge between React Native and Native Widgets backed by iOS App Groups and Android `SharedPreferences`.
53
+
54
+ ---
55
+
56
+ ## 2. Official Live Demo Repositories (Expo & Bare RN)
57
+
58
+ To inspect real-world implementation patterns and test immediately on a simulator or device, check out the two official demo projects:
59
+
60
+ | Architecture | GitHub Repository | Highlights |
61
+ | :--- | :--- | :--- |
62
+ | **🚀 Expo (SDK 58 / CNG)** | 👉 **[https://github.com/React-Native-Vu/LiveWidgetsExampleExpo](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo)** | Continuous Native Generation with Expo Config Plugin (`app.plugin.js`), zero manual Xcode/Gradle editing required. |
63
+ | **⚛️ Bare React Native CLI** | 👉 **[https://github.com/React-Native-Vu/LiveWidgetsExample](https://github.com/React-Native-Vu/LiveWidgetsExample)** | Full Xcode Widget Extension and Android Studio project structure for standard React Native CLI setups. |
64
+
65
+ ### ⚡ Quick Start with Expo Demo (LiveWidgetsExampleExpo):
66
+ ```bash
67
+ git clone https://github.com/React-Native-Vu/LiveWidgetsExampleExpo.git
68
+ cd LiveWidgetsExampleExpo
69
+ npm install
70
+ npx expo prebuild
71
+ npm run setup:widgets
72
+ npx expo run:ios # or npx expo run:android
73
+ ```
74
+
75
+ ---
76
+
77
+ ## 3. Installation & Project Setup
78
+
79
+ ### For Expo Projects
80
+ If you are using **Expo**, the library provides an **Expo Config Plugin (`app.plugin.js`)** and **CLI Wizard** out of the box.
81
+ 👉 **See the dedicated step-by-step guide: [Expo Integration Guide (EXPO-GUIDE-EN.md)](./EXPO-GUIDE-EN.md)**
82
+
83
+ ```bash
84
+ # 1. Install package
85
+ npx expo install react-native-live-widgets
86
+
87
+ # 2. Add plugin to app.json & generate native projects
88
+ npx expo prebuild
89
+
90
+ # 3. Automatically link and configure Widget Extension
91
+ npx react-native-live-widgets init --group group.com.yourcompany.app
92
+ ```
93
+
94
+ ---
95
+
96
+ ### Package Installation (Bare React Native CLI)
97
+ From the root directory of your React Native project:
98
+ ```bash
99
+ npm install react-native-live-widgets
100
+ # or
101
+ yarn add react-native-live-widgets
102
+
103
+ # Automatically configure Info.plist, Entitlements, AndroidManifest & Widget templates
104
+ npx react-native-live-widgets init --group group.com.yourcompany.app
105
+ ```
106
+
107
+ ---
108
+
109
+ ### iOS Setup (Xcode & Widget Extension)
110
+
111
+ #### Step 1: Enable Live Activities & App Groups
112
+ Running `npx react-native-live-widgets init` automatically configures `Info.plist` and `.entitlements`:
113
+ ```xml
114
+ <key>NSSupportsLiveActivities</key>
115
+ <true/>
116
+ <key>NSSupportsLiveActivitiesFrequentUpdates</key>
117
+ <true/>
118
+ ```
119
+ And in both `<YourApp>.entitlements` and `LiveWidgetsExtension.entitlements`:
120
+ ```xml
121
+ <key>aps-environment</key>
122
+ <string>development</string>
123
+ <key>com.apple.security.application-groups</key>
124
+ <array>
125
+ <string>group.<your_bundle_id></string>
126
+ </array>
127
+ ```
128
+
129
+ #### Step 2: Create the Widget Extension Target in Xcode (if not created yet)
130
+ 1. Open your `.xcworkspace` in Xcode.
131
+ 2. Go to **File -> New -> Target... -> Widget Extension**.
132
+ 3. Set **Product Name:** `LiveWidgets` (or `LiveWidgetsExtension`), and uncheck *Include Configuration App Intent*.
133
+ 4. Replace `LiveWidgetsBundle.swift` with:
134
+ ```swift
135
+ import WidgetKit
136
+ import SwiftUI
137
+ import react_native_live_widgets
138
+
139
+ @main
140
+ struct LiveWidgetsBundle: WidgetBundle {
141
+ var body: some Widget {
142
+ if #available(iOS 16.1, *) {
143
+ DynamicLiveActivityWidget()
144
+ }
145
+ DynamicHomeScreenWidget()
146
+ }
147
+ }
148
+ ```
149
+
150
+ #### Step 3: Configure `Podfile` & Install Pods
151
+ In `ios/Podfile`, link `react-native-live-widgets` to your Widget Extension target:
152
+ ```ruby
153
+ target 'LiveWidgetsExtension' do
154
+ use_modular_headers!
155
+ pod 'react-native-live-widgets', :path => '../node_modules/react-native-live-widgets'
156
+ end
157
+ ```
158
+ Then run:
159
+ ```bash
160
+ cd ios && pod install
161
+ ```
162
+
163
+ ---
164
+
165
+ ### Android Setup (Gradle, Manifest, MainApplication & Permissions)
166
+
167
+ On Android, most of the native setup is **handled automatically** out of the box via Gradle's **Android Manifest Merger**. Below is a complete breakdown of what is pre-configured and what you should verify in your project:
168
+
169
+ #### 1. What the Library Auto-Registers for You (Zero Manual Manifest Setup)
170
+ The library's bundled `AndroidManifest.xml` automatically merges the following into your app at build time:
171
+ - **System Permissions:**
172
+ - `android.permission.INTERNET` (downloads remote URL images & executes background Widget API calls).
173
+ - `android.permission.POST_NOTIFICATIONS` (displays Live Update Notifications on Android 13+).
174
+ - `android.permission.POST_PROMOTED_NOTIFICATIONS` (enables status-bar Live Update chips on Android 16 / API 36).
175
+ - `android.permission.VIBRATE`.
176
+ - **Home Screen Widget Provider (`DynamicHomeScreenWidgetProvider`):** Linked with `@xml/rn_live_widgets_info` supporting free horizontal & vertical resizing (`resizeMode="horizontal|vertical"`).
177
+ - **Broadcast Receiver (`LiveActivityReceiver`):** Handles interactive button taps on both Notifications and Home Screen Widgets.
178
+
179
+ #### 2. Step 1: Verify SDK Versions in `android/build.gradle`
180
+ Ensure your root `android/build.gradle` uses `minSdkVersion >= 24` and `compileSdkVersion >= 35` (or `36` for Android 16 Live Updates):
181
+ ```groovy
182
+ buildscript {
183
+ ext {
184
+ buildToolsVersion = "35.0.0"
185
+ minSdkVersion = 24
186
+ compileSdkVersion = 35 // Or 36 for Android 16
187
+ targetSdkVersion = 35
188
+ ndkVersion = "27.1.12297006"
189
+ kotlinVersion = "2.1.20"
190
+ }
191
+ }
192
+ ```
193
+
194
+ #### 3. Step 2: Verify `MainApplication.kt`
195
+ React Native 0.7x / 0.8x **Autolinking** (`PackageList(this).packages`) automatically registers `LiveActivityPackage`.
196
+ > ⚠️ **Important Note for React Native 0.80+:** Ensure `loadReactNative(this)` is called inside `MainApplication.onCreate()` so SoLoader/JSI initializes properly on launch:
197
+ ```kotlin
198
+ package com.yourcompany.app
199
+
200
+ import android.app.Application
201
+ import com.facebook.react.PackageList
202
+ import com.facebook.react.ReactApplication
203
+ import com.facebook.react.ReactHost
204
+ import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
205
+ import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
206
+
207
+ class MainApplication : Application(), ReactApplication {
208
+ override val reactHost: ReactHost by lazy {
209
+ getDefaultReactHost(
210
+ context = applicationContext,
211
+ packageList = PackageList(this).packages, // LiveActivityPackage() is auto-linked here
212
+ )
213
+ }
214
+
215
+ override fun onCreate() {
216
+ super.onCreate()
217
+ loadReactNative(this) // Required on React Native 0.80+
218
+ }
219
+ }
220
+ ```
221
+
222
+ #### 4. Step 3: Request Runtime Notification Permission on Android 13+ (API 33+)
223
+ On Android 13 (API 33) and above, request `POST_NOTIFICATIONS` at runtime before starting a Live Update notification:
224
+ ```typescript
225
+ import { Platform, PermissionsAndroid } from 'react-native';
226
+ import { LiveActivity } from 'react-native-live-widgets';
227
+
228
+ async function ensureAndroidNotificationPermission() {
229
+ if (Platform.OS === 'android' && Platform.Version >= 33) {
230
+ await PermissionsAndroid.request(
231
+ PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS
232
+ );
233
+ }
234
+ // Or call the library's cross-platform helper directly:
235
+ await LiveActivity.registerForPushNotifications();
236
+ }
237
+ ```
238
+
239
+ #### 5. Step 4: Adding & Resizing Home Screen Widgets on Android (`small` / `medium` / `large`)
240
+ 1. After calling `Widget.update('main', { small, medium, large })` in your app, go to the Android Home Screen.
241
+ 2. **Long-press an empty area** on the Home Screen -> Tap **Widgets** -> Find your app -> Drag **Live Widgets** onto the Home Screen.
242
+ 3. **Responsive Family Switching (`small` / `medium` / `large`):** Long-press the placed widget and release to show the resize handles:
243
+ - Resize to **2×2 cells** (`width < 210dp`): Automatically renders the **`small`** layout (1:1 square aspect ratio).
244
+ - Resize to **4×2 cells** (default): Automatically renders the **`medium`** layout.
245
+ - Resize vertically to **4×4 cells** (`height >= 200dp`): Automatically renders the **`large`** layout.
246
+
247
+ ---
248
+
249
+ ### Native Directory Architecture (`ios/` & `android/`)
250
+
251
+ The native codebase is modularized by feature so you can easily navigate or extend it:
252
+
253
+ ```text
254
+ react-native-live-widgets/
255
+ ├── ios/
256
+ │ ├── Bridge/ # LiveActivityModule.swift/.m (React Native <-> iOS Bridge)
257
+ │ ├── Models/ # DynamicLayoutModels.swift, DynamicActivityAttributes.swift
258
+ │ ├── Storage/ # DynamicWidgetStateStore.swift, DynamicWidgetImageCache.swift
259
+ │ ├── Intents/ # DynamicWidgetActionIntent.swift (iOS 17+ interactive AppIntent)
260
+ │ ├── Renderer/ # DynamicNodeView.swift, ColorHexExtension.swift (SwiftUI JSON Renderer)
261
+ │ └── Widgets/ # DynamicHomeScreenWidget.swift, DynamicLiveActivityWidget.swift
262
+ └── android/src/main/java/com/reactnativeliveactivity/
263
+ ├── bridge/ # LiveActivityModule.kt, LiveActivityPackage.kt
264
+ ├── storage/ # DynamicWidgetStateStore.kt, DynamicWidgetImageCache.kt
265
+ ├── renderer/ # DynamicWidgetCanvasRenderer.kt (2D Canvas Renderer + HitBox Calculator)
266
+ ├── widgets/ # DynamicHomeScreenWidgetProvider.kt (Small/Medium/Large AppWidget Provider)
267
+ └── liveactivity/ # LiveActivityNotifier.kt, LiveActivityReceiver.kt (Android 8 -> 16 Live Updates)
268
+ ```
269
+
270
+ ---
271
+
272
+ ## 3. Core API Reference
273
+
274
+ ```typescript
275
+ import { LiveActivity, Widget, SharedStorage, UI } from 'react-native-live-widgets';
276
+ ```
277
+
278
+ ### 1. `LiveActivity` API
279
+ - `LiveActivity.start(options)`: Starts a Live Activity (iOS) or Live Update Notification (Android). Returns `{ activityId, activityPushToken }`.
280
+ - `LiveActivity.update(options)`: Updates the UI layout and alert state of a running `activityId`.
281
+ - `LiveActivity.end(activityId)`: Ends a specific activity session.
282
+ - `LiveActivity.endAll()`: Ends all active sessions.
283
+ - `LiveActivity.registerForPushNotifications()`: Requests notification permissions and registers for an APNs Device Token.
284
+ - `LiveActivity.getAllPushTokens(activityId?)`: Returns all 3 push tokens (`devicePushToken`, `pushToStartToken`, `activityUpdateToken`).
285
+ - `LiveActivity.getDevicePushToken()`: Gets the APNs Device Token (iOS) or stored FCM Token (Android).
286
+ - `LiveActivity.getPushToStartToken()`: Gets the APNs Push-to-Start Token (iOS 17.2+).
287
+ - `LiveActivity.getActivityPushToken(activityId?)`: Gets the APNs Activity Update Token for a running activity.
288
+ - `LiveActivity.setDevicePushToken(token)`: Stores the Android FCM token into the unified token manager.
289
+ - `LiveActivity.onDevicePushTokenChange(cb)` / `onPushToStartTokenChange(cb)` / `onActivityUpdateTokenChange(cb)`: Real-time listeners for token generation and rotation.
290
+
291
+ ### 2. `Widget` API (Home Screen & Lock Screen Widgets)
292
+ - `Widget.setLayout(widgetKey, layoutConfig, appGroup?)`: Updates the dynamic widget layout (`small`, `medium`, `large` for Home Screen; `accessoryRectangular`, `accessoryCircular`, `accessoryInline` for iOS 16+ Lock Screen; `pages`, `initialPage` for multi-page tabs). Prefetches and downscales all remote URL images automatically.
293
+ - `Widget.requestPin()`: *(Android 8.0+)* Prompts the system dialog allowing the user to pin the widget directly to their home screen with a single tap from within the app!
294
+ - `Widget.isPinSupported()`: Checks if the current Android launcher supports in-app widget pinning.
295
+ - `Widget.setRemoteConfig(config, widgetKey?, appGroup?)`: Configures a remote HTTP endpoint so the Widget automatically fetches fresh JSON data in the background even when the app is killed.
296
+ - `Widget.reloadAll()`: Forces iOS/Android to redraw all Home Screen and Lock Screen Widgets immediately.
297
+ - `Widget.reload(kind)`: Reloads a specific widget by kind.
298
+ - `Widget.getInteractiveState(widgetKey?, appGroup?)`: Reads the current interactive state (`activePage`, `toggledItems`, `lastSyncTime`, `remoteVariables`).
299
+ - `Widget.onWidgetAction(cb)`: Subscribes to button tap actions triggered from the Widget or Notification.
300
+
301
+ ### 3. `SharedStorage` API
302
+ - `SharedStorage.set(key, value, appGroup?)`: Saves a string or JSON object to App Group `UserDefaults` (iOS) or `SharedPreferences` (Android).
303
+ - `SharedStorage.get<T>(key, appGroup?)`: Reads shared data.
304
+ - `SharedStorage.remove(key, appGroup?)`: Removes a key.
305
+ - `SharedStorage.clear(appGroup?)`: Clears all shared widget data (useful on user logout).
306
+
307
+ ### 4. `AudioPlayer` API (Music Playback & Equalizer Testing)
308
+ - `AudioPlayer.play(url)`: Plays audio directly from URL (`.mp3`, `.m4a`, `.aac`, `.wav`) through system speakers (iOS `AVPlayer` / Android `MediaPlayer`).
309
+ - `AudioPlayer.pause()`: Pauses the currently playing track.
310
+ - `AudioPlayer.resume()`: Resumes playback.
311
+ - `AudioPlayer.stop()`: Stops playback and releases audio resources.
312
+ - `AudioPlayer.getStatus()`: Returns current playback status (`{ isPlaying, currentTime, duration }`).
313
+
314
+ ---
315
+
316
+ ## 4. Declarative UI Engine (`UI.*`)
317
+
318
+ ### `UI.StyleSheet` & Reusable Styling (`StyleProp`)
319
+ Just like React Native's `StyleSheet.create`, you can define reusable styles to keep your widget layouts modular and clean, supporting conditional style arrays:
320
+
321
+ ```typescript
322
+ import { UI } from 'react-native-live-widgets';
323
+
324
+ const styles = UI.StyleSheet.create({
325
+ card: {
326
+ padding: 14,
327
+ backgroundColor: '#0F172A',
328
+ borderRadius: 14,
329
+ spacing: 8,
330
+ },
331
+ headerText: {
332
+ fontSize: 10,
333
+ fontWeight: 'bold',
334
+ color: '#38BDF8',
335
+ },
336
+ titleText: {
337
+ fontSize: 15,
338
+ fontWeight: 'bold',
339
+ color: '#F8FAFC',
340
+ },
341
+ errorText: {
342
+ color: '#EF4444',
343
+ },
344
+ });
345
+
346
+ // Single style or conditional array:
347
+ UI.VStack(
348
+ styles.card,
349
+ UI.Text('REPORT TITLE', styles.headerText),
350
+ UI.Text('Current Shift Status', [styles.titleText, isError && styles.errorText])
351
+ );
352
+ ```
353
+
354
+ ### `UI.VStack` & `UI.HStack`
355
+ Vertical (`VStack`) and horizontal (`HStack`) flex-like containers:
356
+ ```typescript
357
+ UI.VStack(
358
+ {
359
+ padding: 14,
360
+ backgroundColor: '#1A1D24',
361
+ borderRadius: 16,
362
+ spacing: 8,
363
+ alignItems: 'leading', // 'leading' | 'center' | 'trailing'
364
+ },
365
+ // child nodes...
366
+ )
367
+ ```
368
+
369
+ ### `UI.Text`
370
+ Renders styled text with automatic `{{variable}}` interpolation from background API responses and automatic strikethrough when linked to an interactive checklist item:
371
+ ```typescript
372
+ UI.Text('Checked in at {{checkinTime}}', {
373
+ color: '#FFFFFF',
374
+ fontSize: 15,
375
+ fontWeight: 'bold',
376
+ maxLines: 1,
377
+ strikethroughWhenToggled: 'task_1', // Automatically strikes through and dims when 'task_1' is toggled!
378
+ })
379
+ ```
380
+
381
+ ### `UI.Timer` (Zero-Battery Hardware Timer)
382
+ Real-time `countdown` or `countup` timer rendered directly by the OS on Lock Screen, Dynamic Island, and Home Screen Widgets:
383
+ ```typescript
384
+ UI.Timer(targetTimestampInSeconds, {
385
+ mode: 'countdown',
386
+ color: '#FFA500',
387
+ fontSize: 16,
388
+ fontWeight: 'bold',
389
+ showsHours: false, // Compact MM:SS format ideal for Dynamic Island Compact
390
+ })
391
+ ```
392
+
393
+ ### `UI.Progress` (Bar, Segmented & Circular Progress)
394
+ Supports 3 visual styles: `'bar'` (continuous bar), `'segmented'` (multi-step delivery/shift stages), and `'circular'` (ring progress gauge):
395
+ ```typescript
396
+ // 1. 4-Step Segmented Progress Bar
397
+ UI.Progress({
398
+ style: 'segmented',
399
+ segments: 4,
400
+ currentSegment: 3, // Or pass value: 0.75
401
+ tintColor: '#10B981',
402
+ trackColor: '#374151',
403
+ segmentSpacing: 6,
404
+ height: 8,
405
+ })
406
+
407
+ // 2. Circular Progress Ring
408
+ UI.Progress({
409
+ style: 'circular',
410
+ value: 0.68,
411
+ tintColor: '#10B981',
412
+ trackColor: '#064E3B',
413
+ height: 64,
414
+ showPercentage: true,
415
+ })
416
+ ```
417
+
418
+ ### `UI.Equalizer` (Realtime Animated Music Waveform)
419
+ A dedicated audio equalizer and waveform visualizer. On Dynamic Island and Lock Screen Live Activities (iOS), the equalizer automatically oscillates rhythmically in real-time (using SwiftUI `TimelineView(.animation)`) with zero battery drain; on Android and Home Screen, it renders crisp audio frequency bars:
420
+ ```typescript
421
+ // 1. Used in Dynamic Island (compactTrailing or minimal)
422
+ UI.Equalizer({
423
+ isPlaying: true, // true: oscillating animated wave | false: paused
424
+ barCount: 4, // Number of wave bars (2 to 8)
425
+ tintColor: '#10B981', // Wave bar color (Spotify / Apple Music green)
426
+ height: 14, // Height in points
427
+ barWidth: 3, // Width of each bar
428
+ spacing: 2, // Spacing between bars
429
+ })
430
+
431
+ // 2. Used in Home Screen or Lock Screen Widget
432
+ UI.Equalizer({
433
+ isPlaying: true,
434
+ barCount: 5,
435
+ tintColor: '#FFFFFF',
436
+ height: 18,
437
+ })
438
+ ```
439
+
440
+ ### `UI.Image` (Remote URL, Base64, File, Asset & SF Symbols)
441
+ Supports **5 image sources** across both iOS and Android. When you pass a remote `url` (`https://...`), the library automatically downloads, downscales (`maxDimension = 360px` to stay safely below WidgetKit's 30MB memory ceiling), caches it on disk/memory, and refreshes the widget:
442
+ ```typescript
443
+ // 1. Remote URL Image (Circular Avatar with Border)
444
+ UI.Image({
445
+ url: 'https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=300&q=80',
446
+ width: 44,
447
+ height: 44,
448
+ cornerRadius: 999, // 999 = Full circle mask
449
+ contentMode: 'fill', // 'fill' | 'fit'
450
+ borderColor: '#60A5FA', // Border color
451
+ borderWidth: 2, // Border width
452
+ })
453
+
454
+ // 2. Base64 Encoded Image (QR Code, Barcode, Badge...)
455
+ UI.Image({
456
+ base64: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...',
457
+ width: 36,
458
+ height: 36,
459
+ cornerRadius: 8,
460
+ })
461
+
462
+ // 3. System Icon (SF Symbols on iOS / Vector Mapping on Android)
463
+ UI.Image({
464
+ systemName: 'bicycle',
465
+ tintColor: '#FB923C',
466
+ width: 18,
467
+ height: 18,
468
+ })
469
+ ```
470
+
471
+ ### `UI.Button` (Interactive Widget Buttons)
472
+ Lets users interact directly on the Widget surface (via iOS 17+ `AppIntents` and Android `PendingIntent` hit zones) **without opening the app**:
473
+ ```typescript
474
+ // 1. Switch to another page/tab inside the Widget
475
+ UI.Button({
476
+ title: 'Tasks →',
477
+ actionId: 'page:tasks', // Or 'page:next' / 'page:prev'
478
+ backgroundColor: '#2563EB',
479
+ color: '#FFFFFF',
480
+ fontSize: 11,
481
+ paddingHorizontal: 10,
482
+ paddingVertical: 5,
483
+ borderRadius: 8,
484
+ })
485
+
486
+ // 2. Toggle a task item directly on the Widget
487
+ UI.Button({
488
+ title: 'Review attendance module PR',
489
+ actionId: 'toggle:task_1', // Automatically toggles [ ] <-> [✓]
490
+ backgroundColor: '#F8FAFC',
491
+ activeBackgroundColor: '#DCFCE7',
492
+ color: '#1E293B',
493
+ activeColor: '#15803D',
494
+ })
495
+
496
+ // 3. Trigger an immediate background API refresh
497
+ UI.Button({
498
+ title: '↻ Sync',
499
+ actionId: 'refresh',
500
+ backgroundColor: '#1E293B',
501
+ color: '#60A5FA',
502
+ })
503
+ ```
504
+
505
+ ### `UI.ZStack`, `UI.Grid` & `UI.Divider` (Advanced Layout Containers)
506
+ ```typescript
507
+ // 1. ZStack: Overlay layers on top of each other
508
+ UI.ZStack(
509
+ { zAlignment: 'bottomTrailing' },
510
+ UI.Image('https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=200', { width: 44, height: 44, borderRadius: 22 }),
511
+ UI.Badge('●', { backgroundColor: '#10B981', textColor: '#FFFFFF', fontSize: 8 })
512
+ )
513
+
514
+ // 2. Grid: Multi-column grid layout (e.g., 2x2 KPI dashboard cards)
515
+ UI.Grid(
516
+ { columns: 2, columnSpacing: 8, rowSpacing: 8 },
517
+ UI.VStack({ padding: 8, backgroundColor: '#1E293B', borderRadius: 8 }, UI.Text('Revenue', { fontSize: 10, color: '#94A3B8' }), UI.Text('$128K', { fontSize: 14, fontWeight: 'bold', color: '#FFFFFF' })),
518
+ UI.VStack({ padding: 8, backgroundColor: '#1E293B', borderRadius: 8 }, UI.Text('Orders', { fontSize: 10, color: '#94A3B8' }), UI.Text('1,420', { fontSize: 14, fontWeight: 'bold', color: '#34D399' }))
519
+ )
520
+
521
+ // 3. Divider: Horizontal or vertical separator line
522
+ UI.Divider({ color: '#334155', thickness: 1, marginVertical: 4 })
523
+ ```
524
+
525
+ ### `UI.Gauge` & `UI.Chart` (Speedometer KPI Gauge & Bar / Line Sparkline Charts)
526
+ ```typescript
527
+ // 1. 240° Arc Speedometer / KPI Gauge
528
+ UI.Gauge(0.86, {
529
+ size: 66,
530
+ tintColor: '#38BDF8',
531
+ trackColor: '#1E293B',
532
+ textColor: '#F8FAFC',
533
+ labelColor: '#94A3B8',
534
+ valueText: '86%',
535
+ label: 'Q4 KPI',
536
+ })
537
+
538
+ // 2. Bar Chart ('bar') or Sparkline Area Chart ('line')
539
+ UI.Chart([42, 58, 51, 74, 68, 92, 108], {
540
+ style: 'bar', // 'bar' | 'line'
541
+ labels: ['M', 'T', 'W', 'T', 'F', 'S', 'S'],
542
+ tintColor: '#38BDF8',
543
+ secondaryColor: '#1E3A8A',
544
+ labelColor: '#94A3B8',
545
+ height: 48,
546
+ })
547
+ ```
548
+
549
+ ### `UI.Toggle`, `UI.Badge` & `UI.Link`
550
+ ```typescript
551
+ // 1. Toggle: Interactive Checkbox or Switch directly on the Widget surface
552
+ UI.Toggle('Approve weekly revenue report', {
553
+ actionId: 'toggle:kpi_approve',
554
+ style: 'checkbox', // 'checkbox' | 'switch'
555
+ tintColor: '#38BDF8',
556
+ textColor: '#F8FAFC',
557
+ })
558
+
559
+ // 2. Badge: Pill / Capsule status tag
560
+ UI.Badge('+18% Above Target', {
561
+ backgroundColor: '#064E3B',
562
+ textColor: '#34D399',
563
+ fontSize: 10,
564
+ })
565
+
566
+ // 3. Link: Wrap any container to open a Deep Link or trigger an interactive action
567
+ UI.Link(
568
+ { deepLink: 'livewidgets://analytics/q4', padding: 10, backgroundColor: '#1E293B', borderRadius: 10 },
569
+ UI.Text('View full analytics →', { fontSize: 12, fontWeight: 'bold', color: '#38BDF8' })
570
+ )
571
+ ```
572
+
573
+ ### `UI.Custom` & `DynamicNodeRegistry` (Register Custom Native SwiftUI / Kotlin Components)
574
+ You can register your own custom **SwiftUI View** or **Kotlin Canvas Drawer** without modifying the library's core code:
575
+
576
+ 1. **Register on iOS (Swift — inside `LiveWidgetsBundle.swift`):**
577
+ ```swift
578
+ import SwiftUI
579
+ import react_native_live_widgets
580
+
581
+ DynamicNodeRegistry.shared.registerView("WeatherCard") { node in
582
+ let city = node.props?["city"]?.stringValue ?? "Hanoi"
583
+ let temp = node.props?["temp"]?.stringValue ?? "28°C"
584
+ HStack {
585
+ Image(systemName: "sun.max.fill").foregroundColor(.yellow)
586
+ Text("\(city): \(temp)").font(.headline)
587
+ }
588
+ }
589
+ ```
590
+
591
+ 2. **Register on Android (Kotlin — inside `MainApplication.onCreate()`):**
592
+ ```kotlin
593
+ import com.reactnativeliveactivity.DynamicNodeRegistry
594
+
595
+ DynamicNodeRegistry.register(
596
+ componentName = "WeatherCard",
597
+ heightDp = { 44f },
598
+ drawer = { context, canvas, rect, props, density ->
599
+ // Draw custom graphics onto the Widget Canvas
600
+ }
601
+ )
602
+ ```
603
+
604
+ 3. **Invoke from React Native (`App.tsx`):**
605
+ ```typescript
606
+ UI.Custom('WeatherCard', { city: 'Ho Chi Minh City', temp: '31°C' })
607
+ ```
608
+
609
+ ---
610
+
611
+ ## 5. Dynamic Island Configuration (iPhone 14 Pro, 15, 16, 17)
612
+
613
+ ```typescript
614
+ dynamicIsland: {
615
+ compactLeading: UI.HStack(
616
+ { spacing: 4 },
617
+ UI.Image({
618
+ url: 'https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=200&q=80',
619
+ width: 18,
620
+ height: 18,
621
+ cornerRadius: 999,
622
+ }),
623
+ UI.Text('08:02', { color: '#60A5FA', fontSize: 12, fontWeight: 'bold' })
624
+ ),
625
+ compactTrailing: UI.Timer(shiftEndTimestamp, {
626
+ mode: 'countdown',
627
+ color: '#60A5FA',
628
+ fontSize: 12,
629
+ fontWeight: 'bold',
630
+ showsHours: false,
631
+ }),
632
+ minimal: UI.Image({ systemName: 'clock.fill', tintColor: '#60A5FA', width: 14, height: 14 }),
633
+ expanded: {
634
+ leading: UI.Text('ON SHIFT', { color: '#60A5FA', fontSize: 12, fontWeight: 'bold' }),
635
+ trailing: UI.Timer(shiftEndTimestamp, { mode: 'countdown', color: '#FFFFFF', fontSize: 14, fontWeight: 'bold' }),
636
+ bottom: UI.VStack(
637
+ { spacing: 6 },
638
+ UI.Progress({ style: 'segmented', segments: 4, value: 0.75, tintColor: '#3B82F6', height: 6 }),
639
+ UI.Text('Checked in: District 1 Office', { color: '#94A3B8', fontSize: 11 })
640
+ ),
641
+ },
642
+ }
643
+ ```
644
+
645
+ ---
646
+
647
+ ## 6. Building Multi-Page & Interactive Home Screen Widgets in JavaScript
648
+
649
+ Pass a `pages` map to `Widget.setLayout` to create multiple interactive screens/tabs inside a single Widget:
650
+
651
+ ```typescript
652
+ await Widget.setLayout('main', {
653
+ initialPage: 'overview',
654
+ // Fallback default layout
655
+ medium: overviewMediumNode,
656
+ // Named pages switched via actionId: 'page:<page_name>'
657
+ pages: {
658
+ overview: {
659
+ small: overviewSmallNode,
660
+ medium: overviewMediumNode,
661
+ large: overviewLargeNode,
662
+ },
663
+ tasks: {
664
+ small: tasksSmallNode,
665
+ medium: tasksMediumNode,
666
+ large: tasksLargeNode,
667
+ },
668
+ stats: {
669
+ small: statsSmallNode,
670
+ medium: statsMediumNode,
671
+ large: statsLargeNode,
672
+ },
673
+ },
674
+ });
675
+ ```
676
+
677
+ ### Lock Screen Widgets on iOS
678
+ On iOS 16+, WidgetKit supports 3 lock screen accessory families:
679
+ - `accessoryRectangular`: Horizontal rectangle positioned below the clock.
680
+ - `accessoryCircular`: Compact circular gauge or indicator.
681
+ - `accessoryInline`: Compact single-line text row above the clock.
682
+
683
+ > [!NOTE]
684
+ > The library automatically strips opaque background colors and adapts paddings so that lock screen widgets render natively with system vibrancy against the user's wallpaper.
685
+
686
+ ```typescript
687
+ await Widget.setLayout('main', {
688
+ // Home Screen sizes
689
+ small: smallNode,
690
+ medium: mediumNode,
691
+ large: largeNode,
692
+
693
+ // Lock Screen sizes (iOS 16+)
694
+ accessoryRectangular: UI.HStack(
695
+ { spacing: 6 },
696
+ UI.VStack(
697
+ { spacing: 2 },
698
+ UI.Text('Starboy', { fontSize: 13, fontWeight: 'bold', color: '#FFFFFF' }),
699
+ UI.Text('The Weeknd', { fontSize: 11, color: '#CCCCCC' })
700
+ ),
701
+ UI.Spacer(),
702
+ UI.Equalizer({ isPlaying: true, barCount: 4, tintColor: '#FFFFFF', height: 16 })
703
+ ),
704
+ accessoryCircular: UI.VStack(
705
+ { spacing: 2 },
706
+ UI.Equalizer({ isPlaying: true, barCount: 4, tintColor: '#FFFFFF', height: 18 }),
707
+ UI.Text('MUSIC', { fontSize: 8, fontWeight: 'bold', color: '#FFFFFF' })
708
+ ),
709
+ accessoryInline: UI.Text('♪ Starboy • The Weeknd', { fontSize: 12, fontWeight: 'medium' }),
710
+ });
711
+ ```
712
+
713
+ ### In-App Pin Widget on Android
714
+ On Android 8.0+ (API 26+), you can trigger the system dialog from inside your React Native app to pin a widget to the home screen without asking users to manually search the launcher:
715
+
716
+ ```typescript
717
+ import { Widget } from 'react-native-live-widgets';
718
+
719
+ // Check if launcher supports in-app pinning
720
+ const isSupported = await Widget.isPinSupported();
721
+
722
+ if (isSupported) {
723
+ // Request system dialog to pin widget
724
+ const success = await Widget.requestPin();
725
+ if (success) {
726
+ console.log('Pin request accepted by system');
727
+ }
728
+ }
729
+ ```
730
+
731
+ ---
732
+
733
+ ## 7. Background API Auto-Sync When App Is Killed (`Widget.setRemoteConfig`)
734
+
735
+ When the user swipes away (force-kills) the main app, the React Native JS thread stops. To keep your Widget updated with live server data autonomously:
736
+
737
+ ```typescript
738
+ await Widget.setRemoteConfig({
739
+ url: 'https://api.yourcompany.com/v1/widget-summary',
740
+ method: 'GET',
741
+ headers: {
742
+ Authorization: `Bearer ${accessToken}`,
743
+ },
744
+ intervalMinutes: 15, // OS-scheduled background sync every 15 minutes
745
+ });
746
+ ```
747
+
748
+ - **How it works:**
749
+ - **iOS**: `DynamicWidgetProvider` performs an asynchronous HTTP request during its WidgetKit timeline reload (or immediately when the user taps a button with `actionId: 'refresh'`), flattens the JSON response, and injects values into `{{fieldName}}` placeholders across your UI tree.
750
+ - **Android**: `AlarmManager` schedules `LiveActivityReceiver` (`ACTION_WIDGET_SYNC`), fetches fresh JSON in the background (`goAsync()`), updates `SharedPreferences`, and redraws `DynamicHomeScreenWidgetProvider`.
751
+ - The built-in `{{_lastSyncTime}}` placeholder automatically resolves to the latest sync timestamp (`HH:mm:ss`).
752
+
753
+ ---
754
+
755
+ ## 8. Managing All 3 Push Token Types (APNs & FCM)
756
+
757
+ To control Live Activities and notifications from your backend server, the library exposes 3 token types:
758
+ 1. **`devicePushToken`**: Standard APNs Device Token (iOS) / FCM Token (Android).
759
+ 2. **`pushToStartToken` (iOS 17.2+)**: Allows your backend to remotely start a brand-new Live Activity even when the app is closed.
760
+ 3. **`activityUpdateToken`**: Unique token per active Live Activity used by your server to push real-time content updates or end that specific activity.
761
+
762
+ ```typescript
763
+ // 1. Request permission & register with APNs
764
+ await LiveActivity.registerForPushNotifications();
765
+
766
+ // 2. Fetch all 3 tokens at once
767
+ const tokens = await LiveActivity.getAllPushTokens();
768
+ console.log(tokens.devicePushToken, tokens.pushToStartToken, tokens.activityUpdateToken);
769
+
770
+ // 3. Subscribe to real-time token rotation events
771
+ const sub1 = LiveActivity.onDevicePushTokenChange(({ token }) => {
772
+ api.syncDeviceToken(token);
773
+ });
774
+ const sub2 = LiveActivity.onPushToStartTokenChange((token) => {
775
+ api.syncPushToStartToken(token);
776
+ });
777
+ const sub3 = LiveActivity.onActivityUpdateTokenChange(({ activityId, token }) => {
778
+ api.syncActivityUpdateToken(activityId, token);
779
+ });
780
+ ```
781
+
782
+ ---
783
+
784
+ ## 9. State Machine & Timed Phases (`phases`)
785
+
786
+ Declare scheduled transitions ahead of time so the native layer updates alerts and UI at exact timestamps without requiring a server push:
787
+
788
+ ```typescript
789
+ phases: [
790
+ {
791
+ id: 'warning_phase',
792
+ triggerTimestamp: targetTimestamp - 300, // 5 minutes before deadline
793
+ alertTitle: 'Shift starting soon!',
794
+ alertBody: 'Only 5 minutes left to check in.',
795
+ },
796
+ {
797
+ id: 'late_phase',
798
+ triggerTimestamp: targetTimestamp, // Deadline reached
799
+ alertTitle: 'Late for shift!',
800
+ alertBody: 'Your shift start time has passed.',
801
+ },
802
+ ]
803
+ ```
804
+
805
+ ---
806
+
807
+ ## 10. Server Push Payload Structure (APNs & FCM)
808
+
809
+ ### APNs HTTP/2 Headers (iOS Live Activity):
810
+ - `apns-push-type`: `liveactivity`
811
+ - `apns-topic`: `<your_bundle_id>.push-type.liveactivity`
812
+ - `apns-priority`: `10`
813
+
814
+ ### APNs JSON Body:
815
+ ```json
816
+ {
817
+ "aps": {
818
+ "timestamp": 1711890000,
819
+ "event": "update",
820
+ "content-state": {
821
+ "layoutJson": "{\"lockScreen\":{...},\"dynamicIsland\":{...}}"
822
+ },
823
+ "alert": {
824
+ "title": "Order Delivered!",
825
+ "body": "Enjoy your meal."
826
+ }
827
+ }
828
+ }
829
+ ```
830
+
831
+ ---
832
+
833
+ ## 11. Troubleshooting
834
+
835
+ 1. **Home Screen Widget displays the default placeholder text:**
836
+ - Verify that both the main app target and the Widget Extension target share the same App Group identifier (`group.<bundle_id>`).
837
+ - Ensure `await Widget.setLayout('main', ...)` has been called from React Native.
838
+ 2. **Dynamic Island Compact pill stretches too wide when using `UI.Timer`:**
839
+ - Pass `showsHours: false` to `UI.Timer` in `compactTrailing`. The native renderer automatically constrains the timer frame width so the Dynamic Island stays compact.
840
+ 3. **Remote images (`https://...`) do not appear immediately:**
841
+ - Ensure the URL uses `https://`. The library prefetches, downscales to `360px`, caches the image in the App Group / cache directory, and automatically triggers a widget reload once the download finishes.
842
+
843
+ ---
844
+
845
+ ## 📄 License
846
+ MIT © vu-tran
847
+