refactor: Centralize cache configuration to Stac.initialize and set networkFirst` as default cache strategy.

docs/concepts/caching.mdx

@@ -3,7 +3,7 @@ title: "Caching & Offline Support"
 description: "Learn how Stac intelligently caches screens for offline access, faster loading, and smarter network usage"
 ---
 
-Stac includes a powerful caching system that stores screens locally, enabling offline access, instant loading, and more efficient network usage. The caching layer works automatically with the `Stac` widget and can be customized for different use cases.
+Stac includes a powerful caching system that stores screens locally, enabling offline access, instant loading, and more efficient network usage. The caching layer works automatically with the `Stac` widget and is configured globally during initialization.
 
 ## How Caching Works
 
@@ -14,42 +14,72 @@ When you use the `Stac` widget to fetch screens from Stac Cloud:
 3. **Version Tracking**: Each cached screen stores its version number, enabling smart updates
 4. **Background Updates**: Fresh data can be fetched in the background without blocking the UI
 
+## Global Configuration
+
+Configure caching once during app initialization. This applies to all `Stac` widgets and `StacAppTheme`:
+
+```dart
+await Stac.initialize(
+  options: defaultStacOptions,
+  cacheConfig: StacCacheConfig(
+    strategy: StacCacheStrategy.networkFirst, // default
+    maxAge: Duration(days: 30),
+  ),
+);
+```
+
 ## Cache Strategies
 
 Stac provides five caching strategies to fit different use cases:
 
-### 1. Optimistic (Default)
+### 1. Network First (Default)
 
-Returns cached data immediately while fetching updates in the background. Best for fast perceived performance.
+Always tries the network first, falls back to cache if network fails. **This is the default strategy.**
 
 ```dart
-Stac(
-  routeName: '/home',
-  cacheConfig: StacCacheConfig(
-    strategy: StacCacheStrategy.optimistic,
-  ),
+cacheConfig: StacCacheConfig(
+  strategy: StacCacheStrategy.networkFirst,
+)
+```
+
+**Behavior:**
+- ✅ Always fetches fresh data first
+- ✅ Falls back to cache on network error
+- ✅ Ensures latest content when online
+- 🌐 Requires network for best experience
+
+**Best for:** Server-driven UI where users should see the latest content, real-time data, frequently changing screens.
+
+### 2. Optimistic
+
+Returns cached data immediately while fetching updates in the background.
+
+```dart
+cacheConfig: StacCacheConfig(
+  strategy: StacCacheStrategy.optimistic,
 )
 ```
 
 **Behavior:**
-- ✅ Returns cached data instantly (even if expired)
+- ✅ Returns cached data instantly
 - ✅ Fetches fresh data in background
 - ✅ Updates cache for next load
 - ⚡ Fastest perceived loading
 
 **Best for:** UI layouts, content screens, any screen where instant loading matters more than showing the absolute latest data.
 
-### 2. Cache First
+<Warning>
+  With optimistic caching, users see outdated content until the next app launch after you deploy updates. Consider using `networkFirst` if immediate updates are important.
+</Warning>
+
+### 3. Cache First
 
 Uses cached data if available and valid, only fetches from network when cache is invalid or missing.
 
 ```dart
-Stac(
-  routeName: '/home',
-  cacheConfig: StacCacheConfig(
-    strategy: StacCacheStrategy.cacheFirst,
-    maxAge: Duration(hours: 24),
-  ),
+cacheConfig: StacCacheConfig(
+  strategy: StacCacheStrategy.cacheFirst,
+  maxAge: Duration(hours: 24),
 )
 ```
 
@@ -61,37 +91,13 @@ Stac(
 
 **Best for:** Offline-first apps, content that doesn't change frequently, reducing network usage.
 
-### 3. Network First
-
-Always tries the network first, falls back to cache if network fails.
-
-```dart
-Stac(
-  routeName: '/home',
-  cacheConfig: StacCacheConfig(
-    strategy: StacCacheStrategy.networkFirst,
-  ),
-)
-```
-
-**Behavior:**
-- ✅ Always fetches fresh data first
-- ✅ Falls back to cache on network error
-- ✅ Ensures latest content when online
-- 🌐 Requires network for best experience
-
-**Best for:** Real-time data, frequently changing content, screens where freshness is critical.
-
 ### 4. Cache Only
 
 Only uses cached data, never makes network requests. Throws an error if no cache exists.
 
 ```dart
-Stac(
-  routeName: '/home',
-  cacheConfig: StacCacheConfig(
-    strategy: StacCacheStrategy.cacheOnly,
-  ),
+cacheConfig: StacCacheConfig(
+  strategy: StacCacheStrategy.cacheOnly,
 )
 ```
 
@@ -108,11 +114,8 @@ Stac(
 Always fetches from network, never uses or updates cache.
 
 ```dart
-Stac(
-  routeName: '/home',
-  cacheConfig: StacCacheConfig(
-    strategy: StacCacheStrategy.networkOnly,
-  ),
+cacheConfig: StacCacheConfig(
+  strategy: StacCacheStrategy.networkOnly,
 )
 ```
 
@@ -124,47 +127,37 @@ Stac(
 
 **Best for:** Sensitive data that shouldn't be cached, real-time dashboards, authentication screens.
 
-## Cache Configuration
+## Configuration Options
 
 ### StacCacheConfig Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `strategy` | `StacCacheStrategy` | `optimistic` | The caching strategy to use |
-| `maxAge` | `Duration?` | `null` | Maximum age before cache is considered expired. `null` means no time-based expiration |
-| `refreshInBackground` | `bool` | `true` | Whether to fetch fresh data in background when cache is valid |
-| `staleWhileRevalidate` | `bool` | `false` | Whether to use expired cache while fetching fresh data |
+| `strategy` | `StacCacheStrategy` | `networkFirst` | The caching strategy to use |
+| `maxAge` | `Duration?` | `null` | Maximum age before cache is considered stale. `null` means no time-based expiration |
+| `refreshInBackground` | `bool` | `true` | Whether to fetch fresh data in background when showing cached content |
 
 ### Setting Cache Duration
 
 Control how long cached data remains valid:
 
 ```dart
 // Cache valid for 1 hour
-Stac(
-  routeName: '/home',
-  cacheConfig: StacCacheConfig(
-    strategy: StacCacheStrategy.cacheFirst,
-    maxAge: Duration(hours: 1),
-  ),
+cacheConfig: StacCacheConfig(
+  strategy: StacCacheStrategy.cacheFirst,
+  maxAge: Duration(hours: 1),
 )
 
 // Cache valid for 7 days
-Stac(
-  routeName: '/settings',
-  cacheConfig: StacCacheConfig(
-    strategy: StacCacheStrategy.cacheFirst,
-    maxAge: Duration(days: 7),
-  ),
+cacheConfig: StacCacheConfig(
+  strategy: StacCacheStrategy.cacheFirst,
+  maxAge: Duration(days: 7),
 )
 
 // Cache never expires (only version-based updates)
-Stac(
-  routeName: '/static-page',
-  cacheConfig: StacCacheConfig(
-    strategy: StacCacheStrategy.cacheFirst,
-    maxAge: null, // No time-based expiration
-  ),
+cacheConfig: StacCacheConfig(
+  strategy: StacCacheStrategy.cacheFirst,
+  maxAge: null, // No time-based expiration
 )
 ```
 
@@ -173,13 +166,10 @@ Stac(
 Keep cache fresh without blocking the UI:
 
 ```dart
-Stac(
-  routeName: '/home',
-  cacheConfig: StacCacheConfig(
-    strategy: StacCacheStrategy.cacheFirst,
-    maxAge: Duration(hours: 1),
-    refreshInBackground: true, // Fetch updates silently
-  ),
+cacheConfig: StacCacheConfig(
+  strategy: StacCacheStrategy.cacheFirst,
+  maxAge: Duration(hours: 1),
+  refreshInBackground: true, // Fetch updates silently
 )
 ```
 
@@ -189,33 +179,13 @@ When `refreshInBackground` is `true`:
 - Cache is updated for next load
 - User sees instant loading with eventual consistency
 
-### Stale While Revalidate
-
-Show expired cache while fetching fresh data:
-
-```dart
-Stac(
-  routeName: '/home',
-  cacheConfig: StacCacheConfig(
-    strategy: StacCacheStrategy.cacheFirst,
-    maxAge: Duration(hours: 1),
-    staleWhileRevalidate: true, // Use expired cache while fetching
-  ),
-)
-```
-
-This is useful when:
-- You prefer showing something over a loading spinner
-- Content staleness is acceptable for a brief period
-- Network is slow or unreliable
-
 ## Strategy Comparison
 
 | Strategy | Initial Load | Subsequent Load | Offline Support | Best For |
 |----------|--------------|-----------------|-----------------|----------|
-| `optimistic` | Network → Cache | Cache (bg update) | ✅ Yes | Fast UX |
+| `networkFirst` | Network | Network (cache fallback) | ⚠️ Fallback only | Fresh data (default) |
+| `optimistic` | Cache or Network | Cache (bg update) | ✅ Yes | Fast UX |
 | `cacheFirst` | Cache or Network | Cache | ✅ Yes | Offline apps |
-| `networkFirst` | Network | Network (cache fallback) | ⚠️ Fallback only | Fresh data |
 | `cacheOnly` | Cache only | Cache only | ✅ Yes | Offline mode |
 | `networkOnly` | Network only | Network only | ❌ No | Sensitive data |
 
@@ -230,3 +200,20 @@ Stac tracks version numbers for each cached screen. When you deploy updates to S
 
 This ensures users get updates without manual intervention while maintaining fast loading times.
 
+## Clearing Cache
+
+Clear cached screens programmatically:
+
+```dart
+// Clear a specific screen
+await StacCloud.clearScreenCache('/home');
+
+// Clear all cached screens
+await StacCloud.clearAllCache();
+
+// Clear a specific theme
+await StacCloud.clearThemeCache('dark');
+
+// Clear all cached themes
+await StacCloud.clearAllThemeCache();
+```

packages/stac/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.3.0-dev.1
+
+- **BREAKING**: Refactored caching to use global configuration via `Stac.initialize()`. See [Caching Docs](https://docs.stac.dev/concepts/caching) for migration guide.
+
 ## 1.2.0
 
 - Added screen caching and offline support

packages/stac/README.md

@@ -40,6 +40,7 @@ This approach separates your app's presentation layer from its business logic, e
 - 🎛 Actions & navigation: Control routes and API calls from the backend.
 - 📝 Forms & validation: Built-in form state and validation rules.
 - 🎨 Theming: Brand and layout via JSON with Stac Theme.
+- 💾 Caching: Intelligent screen caching with configurable strategies.
 - 🔌 Extensible: Add custom widgets, actions, and native integrations.
 
 ## Documentation