feat: bundle mode with atomic deploys, seed assets, and version-gated caching

packages/stac/lib/src/framework/stac.dart

@@ -5,6 +5,7 @@ import 'package:dio/dio.dart';
 import 'package:flutter/material.dart';
 import 'package:stac/src/framework/stac_error.dart';
 import 'package:stac/src/framework/stac_service.dart';
+import 'package:stac/src/models/stac_bundle_config.dart';
 import 'package:stac/src/models/stac_cache_config.dart';
 import 'package:stac/src/services/stac_cloud.dart';
 import 'package:stac_core/actions/network_request/stac_network_request.dart';
@@ -165,6 +166,11 @@ class Stac extends StatelessWidget {
   /// - [cacheConfig]: Global cache configuration for all Stac widgets and
   ///   StacCloud calls. Defaults to networkFirst strategy if not provided.
   ///
+  /// - [bundleConfig]: Configuration for bundle mode, where all screens and
+  ///   themes are downloaded as a single version-gated bundle. Disabled by
+  ///   default (opt-in); when not provided, legacy per-screen fetching is
+  ///   used.
+  ///
   /// ## Example
   ///
   /// ```dart
@@ -188,6 +194,7 @@ class Stac extends StatelessWidget {
     bool logStackTraces = true,
     StacErrorWidgetBuilder? errorWidgetBuilder,
     StacCacheConfig? cacheConfig,
+    StacBundleConfig? bundleConfig,
   }) async {
     return StacService.initialize(
       options: options,
@@ -199,6 +206,7 @@ class Stac extends StatelessWidget {
       logStackTraces: logStackTraces,
       errorWidgetBuilder: errorWidgetBuilder,
       cacheConfig: cacheConfig,
+      bundleConfig: bundleConfig,
     );
   }
 

packages/stac/lib/src/framework/stac_service.dart

@@ -8,6 +8,7 @@ import 'package:flutter/services.dart';
 import 'package:stac/src/framework/stac.dart';
 import 'package:stac/src/framework/stac_error.dart';
 import 'package:stac/src/framework/stac_registry.dart';
+import 'package:stac/src/models/stac_bundle_config.dart';
 import 'package:stac/src/models/stac_cache_config.dart';
 import 'package:stac/src/parsers/actions/stac_form_validate/stac_form_validate_parser.dart';
 import 'package:stac/src/parsers/actions/stac_get_form_value/stac_get_form_value_parser.dart';
@@ -18,6 +19,8 @@ import 'package:stac/src/parsers/widgets/stac_inkwell/stac_inkwell_parser.dart';
 import 'package:stac/src/parsers/widgets/stac_row/stac_row_parser.dart';
 import 'package:stac/src/parsers/widgets/stac_text/stac_text_parser.dart';
 import 'package:stac/src/parsers/widgets/stac_tool_tip/stac_tool_tip_parser.dart';
+import 'package:stac/src/services/stac_bundle_service.dart';
+import 'package:stac/src/services/stac_bundle_updater.dart';
 import 'package:stac/src/services/stac_network_service.dart';
 import 'package:stac/src/utils/variable_resolver.dart';
 import 'package:stac_core/stac_core.dart';
@@ -173,6 +176,10 @@ class StacService {
   );
   static StacCacheConfig get defaultCacheConfig => _defaultCacheConfig;
 
+  // Bundle configuration for bundle mode (opt-in, disabled by default).
+  static StacBundleConfig _bundleConfig = const StacBundleConfig();
+  static StacBundleConfig get bundleConfig => _bundleConfig;
+
   static Future<void> initialize({
     StacOptions? options,
     List<StacParser> parsers = const [],
@@ -183,11 +190,21 @@ class StacService {
     bool logStackTraces = true,
     StacErrorWidgetBuilder? errorWidgetBuilder,
     StacCacheConfig? cacheConfig,
+    StacBundleConfig? bundleConfig,
   }) async {
     _options = options;
     if (cacheConfig != null) {
       _defaultCacheConfig = cacheConfig;
     }
+    if (bundleConfig != null) {
+      _bundleConfig = bundleConfig;
+    }
+    if (_bundleConfig.enabled) {
+      StacBundleUpdater.start();
+      if (_bundleConfig.prefetchOnInit && options != null) {
+        unawaited(StacBundleService.sync());
+      }
+    }
     _parsers.addAll(parsers);
     _actionParsers.addAll(actionParsers);
     StacRegistry.instance.registerAll(_parsers, override);

packages/stac/lib/src/models/models.dart

@@ -1,2 +1,4 @@
+export 'package:stac/src/models/stac_bundle.dart';
+export 'package:stac/src/models/stac_bundle_config.dart';
 export 'package:stac/src/models/stac_cache_config.dart';
 export 'package:stac/src/models/stac_cache.dart';

packages/stac/lib/src/models/stac_bundle.dart

@@ -0,0 +1,99 @@
+import 'dart:convert';
+
+import 'package:json_annotation/json_annotation.dart';
+
+part 'stac_bundle.g.dart';
+
+/// Model representing a bundle of screens and themes from Stac Cloud.
+///
+/// A bundle contains every screen and theme for a project at a single
+/// server-owned monotonic [version]. Screens render from the cached bundle;
+/// the body is re-downloaded only when a conditional version check returns
+/// a new version.
+@JsonSerializable()
+class StacBundle {
+  /// Creates a [StacBundle] instance.
+  const StacBundle({
+    required this.projectId,
+    required this.version,
+    this.etag,
+    this.checksum,
+    required this.fetchedAt,
+    required this.screens,
+    required this.themes,
+  });
+
+  /// The Stac Cloud project this bundle belongs to.
+  final String projectId;
+
+  /// The server-owned monotonic bundle version.
+  final int version;
+
+  /// The HTTP ETag for conditional (`If-None-Match`) requests.
+  final String? etag;
+
+  /// The sha256 checksum of the bundle content.
+  final String? checksum;
+
+  /// The timestamp when this bundle was fetched or hydrated.
+  final DateTime fetchedAt;
+
+  /// Screen name to Stac JSON string.
+  final Map<String, String> screens;
+
+  /// Theme name to Stac JSON string.
+  final Map<String, String> themes;
+
+  /// Returns the Stac JSON string for the screen [name], or `null` if the
+  /// screen is not part of this bundle.
+  String? screen(String name) => screens[name];
+
+  /// Returns the Stac JSON string for the theme [name], or `null` if the
+  /// theme is not part of this bundle.
+  String? theme(String name) => themes[name];
+
+  /// Creates a [StacBundle] from a JSON map.
+  factory StacBundle.fromJson(Map<String, dynamic> json) =>
+      _$StacBundleFromJson(json);
+
+  /// Converts this [StacBundle] to a JSON map.
+  Map<String, dynamic> toJson() => _$StacBundleToJson(this);
+
+  /// Creates a [StacBundle] from a JSON string.
+  factory StacBundle.fromJsonString(String jsonString) {
+    return StacBundle.fromJson(jsonDecode(jsonString) as Map<String, dynamic>);
+  }
+
+  /// Converts this [StacBundle] to a JSON string.
+  String toJsonString() {
+    return jsonEncode(toJson());
+  }
+
+  /// Creates a copy of this [StacBundle] with the given fields replaced.
+  StacBundle copyWith({
+    String? projectId,
+    int? version,
+    String? etag,
+    String? checksum,
+    DateTime? fetchedAt,
+    Map<String, String>? screens,
+    Map<String, String>? themes,
+  }) {
+    return StacBundle(
+      projectId: projectId ?? this.projectId,
+      version: version ?? this.version,
+      etag: etag ?? this.etag,
+      checksum: checksum ?? this.checksum,
+      fetchedAt: fetchedAt ?? this.fetchedAt,
+      screens: screens ?? this.screens,
+      themes: themes ?? this.themes,
+    );
+  }
+
+  @override
+  String toString() {
+    return 'StacBundle(projectId: $projectId, version: $version, '
+        'screens: ${screens.length}, themes: ${themes.length}, '
+        'fetchedAt: $fetchedAt)';
+  }
+}

packages/stac/lib/src/models/stac_bundle_config.dart

@@ -0,0 +1,126 @@
+/// Configuration for Stac bundle mode.
+///
+/// Bundle mode replaces per-screen fetches with a single version-gated
+/// bundle download containing every screen and theme for a project.
+/// It is opt-in: [enabled] defaults to `false`, so an app without a
+/// `bundleConfig` behaves exactly as before.
+///
+/// Bundle caching behavior is fixed (no strategies): screens always render
+/// from the cached bundle, and the body is re-downloaded only when a
+/// conditional version check returns a new version. The check runs at app
+/// launch ([prefetchOnInit]), on app-resume ([checkOnResume]), on an optional
+/// poll interval ([pollingInterval]), or via an explicit
+/// `StacBundleService.sync()` call.
+///
+/// ## Basic Usage
+///
+/// ```dart
+/// await Stac.initialize(
+///   options: StacOptions(...),
+///   bundleConfig: StacBundleConfig(
+///     enabled: true,
+///     seedAsset: 'assets/stac_bundle.json',
+///   ),
+/// );
+/// ```
+class StacBundleConfig {
+  /// Creates a [StacBundleConfig] instance.
+  const StacBundleConfig({
+    this.enabled = false,
+    this.prefetchOnInit = true,
+    this.baseUrl = 'https://api.stac.dev',
+    this.seedAsset,
+    this.checkOnResume = true,
+    this.pollingInterval,
+  });
+
+  /// Whether bundle mode is enabled.
+  ///
+  /// Defaults to `false` (opt-in). When disabled, the legacy per-artifact
+  /// fetch and cache behavior is untouched.
+  final bool enabled;
+
+  /// Whether to kick off a conditional bundle sync during initialization.
+  ///
+  /// Defaults to `true`. The sync is not awaited, so it never delays startup.
+  final bool prefetchOnInit;
+
+  /// The base URL used for bundle requests.
+  ///
+  /// Defaults to `https://api.stac.dev`.
+  final String baseUrl;
+
+  /// Optional asset path of a seed bundle shipped with the app
+  /// (e.g. `assets/stac_bundle.json`, written by `stac deploy`).
+  ///
+  /// When set, first launch hydrates from the seed instantly — no loading
+  /// wait, and it works offline. Defaults to `null` (no seed).
+  final String? seedAsset;
+
+  /// Whether to run a conditional bundle sync when the app returns to the
+  /// foreground.
+  ///
+  /// Defaults to `true`.
+  final bool checkOnResume;
+
+  /// Optional interval for periodic conditional bundle syncs while the app
+  /// is foregrounded.
+  ///
+  /// Defaults to `null` (polling off).
+  final Duration? pollingInterval;
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Methods
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /// Creates a copy of this config with the given fields replaced.
+  StacBundleConfig copyWith({
+    bool? enabled,
+    bool? prefetchOnInit,
+    String? baseUrl,
+    String? seedAsset,
+    bool? checkOnResume,
+    Duration? pollingInterval,
+  }) {
+    return StacBundleConfig(
+      enabled: enabled ?? this.enabled,
+      prefetchOnInit: prefetchOnInit ?? this.prefetchOnInit,
+      baseUrl: baseUrl ?? this.baseUrl,
+      seedAsset: seedAsset ?? this.seedAsset,
+      checkOnResume: checkOnResume ?? this.checkOnResume,
+      pollingInterval: pollingInterval ?? this.pollingInterval,
+    );
+  }
+
+  @override
+  String toString() {
+    return 'StacBundleConfig(enabled: $enabled, prefetchOnInit: $prefetchOnInit, '
+        'baseUrl: $baseUrl, seedAsset: $seedAsset, checkOnResume: $checkOnResume, '
+        'pollingInterval: $pollingInterval)';
+  }
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) return true;
+
+    return other is StacBundleConfig &&
+        other.enabled == enabled &&
+        other.prefetchOnInit == prefetchOnInit &&
+        other.baseUrl == baseUrl &&
+        other.seedAsset == seedAsset &&
+        other.checkOnResume == checkOnResume &&
+        other.pollingInterval == pollingInterval;
+  }
+
+  @override
+  int get hashCode {
+    return Object.hash(
+      enabled,
+      prefetchOnInit,
+      baseUrl,
+      seedAsset,
+      checkOnResume,
+      pollingInterval,
+    );
+  }
+}

packages/stac/lib/src/services/services.dart

@@ -1,2 +1,4 @@
+export 'package:stac/src/services/stac_bundle_service.dart';
+export 'package:stac/src/services/stac_bundle_store.dart';
 export 'package:stac/src/services/stac_cache_service.dart';
 export 'package:stac/src/services/stac_network_service.dart';