Version management, platform validation and fallback colors

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

@@ -188,6 +188,7 @@ class Stac extends StatelessWidget {
     bool logStackTraces = true,
     StacErrorWidgetBuilder? errorWidgetBuilder,
     StacCacheConfig? cacheConfig,
+    int? buildNumber,
   }) async {
     return StacService.initialize(
       options: options,
@@ -199,6 +200,7 @@ class Stac extends StatelessWidget {
       logStackTraces: logStackTraces,
       errorWidgetBuilder: errorWidgetBuilder,
       cacheConfig: cacheConfig,
+      buildNumber: buildNumber,
     );
   }
 

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

@@ -1,3 +1,4 @@
+import 'package:flutter/material.dart';
 import 'package:stac_logger/stac_logger.dart';
 import 'package:stac_framework/stac_framework.dart';
 
@@ -14,6 +15,9 @@ class StacRegistry {
 
   static final _stacActionParsers = <String, StacActionParser>{};
 
+  Color? Function(String?)? parseCustomColor;
+  int? _buildNumber;
+  int? get buildNumber => _buildNumber;
   static final Map<String, dynamic> _variables = {};
 
   bool register(StacParser parser, [bool override = false]) {
@@ -68,6 +72,12 @@ class StacRegistry {
     });
   }
 
+  void registerBuildNumber(int? buildNumber) {
+    if (buildNumber != null) {
+      _buildNumber = buildNumber;
+    }
+  }
+
   StacParser<dynamic>? getParser(String type) {
     return _stacParsers[type];
   }

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

@@ -5,24 +5,18 @@ import 'package:dio/dio.dart';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart' hide ErrorWidgetBuilder;
 import 'package:flutter/services.dart';
-import 'package:stac/src/framework/stac.dart';
-import 'package:stac/src/models/stac_cache_config.dart';
 import 'package:stac/src/framework/stac_error.dart';
-import 'package:stac/src/framework/stac_registry.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';
 import 'package:stac/src/parsers/actions/stac_network_request/stac_network_request_parser.dart';
-import 'package:stac/src/parsers/parsers.dart';
 import 'package:stac/src/parsers/widgets/stac_app_bar/stac_app_bar_parser.dart';
 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_network_service.dart';
 import 'package:stac/src/utils/variable_resolver.dart';
+import 'package:stac/stac.dart';
 import 'package:stac_core/core/stac_options.dart';
 import 'package:stac_core/stac_core.dart';
-import 'package:stac_framework/stac_framework.dart';
 import 'package:stac_logger/stac_logger.dart';
 
 /// Internal service that manages Stac parsers, actions, and rendering.
@@ -181,6 +175,7 @@ class StacService {
     bool logStackTraces = true,
     StacErrorWidgetBuilder? errorWidgetBuilder,
     StacCacheConfig? cacheConfig,
+    int? buildNumber,
   }) async {
     _options = options;
     if (cacheConfig != null) {
@@ -190,18 +185,70 @@ class StacService {
     _actionParsers.addAll(actionParsers);
     StacRegistry.instance.registerAll(_parsers, override);
     StacRegistry.instance.registerAllActions(_actionParsers, override);
+    StacRegistry.instance.registerBuildNumber(buildNumber);
     StacNetworkService.initialize(dio ?? Dio());
     _showErrorWidgets = showErrorWidgets;
     _logStackTraces = logStackTraces;
     _errorWidgetBuilder = errorWidgetBuilder;
   }
 
+  static void setParseCustomColor(Color? Function(String?)? parseCustomColor) =>
+      StacRegistry.instance.parseCustomColor = parseCustomColor;
+
   static Widget? fromJson(Map<String, dynamic>? json, BuildContext context) {
     try {
       if (json == null) {
         return null;
       }
 
+      Map<String, dynamic>? jsonVersion = json['version'];
+      final platform = json['platform'];
+
+      /// Check if has version and buildNumber is not null
+      if (jsonVersion != null && StacRegistry.instance.buildNumber != null) {
+        final stacVersion = StacVersion.fromJson(jsonVersion);
+        final isSatisfied = stacVersion.isSatisfied(
+          StacRegistry.instance.buildNumber!,
+        );
+        // If version is not satisfied, return null
+        if (!isSatisfied) {
+          Log.w(
+            'Stac buildNumber ${stacVersion.buildNumber} is not satisfied; current build is: ${StacRegistry.instance.buildNumber}',
+          );
+          return null;
+        }
+      }
+
+      /// Check if platform is specified and validate
+      if (platform != null) {
+        final currentPlatform = currentPlatformString();
+        final rawList = platform is List
+            ? platform.map((e) => e.toString().toLowerCase()).toList()
+            : <String>[platform.toString().toLowerCase()];
+        final validatedPlatforms = rawList
+            .where((s) => supportedPlatformStrings.contains(s))
+            .toList();
+        final invalid = rawList
+            .where((s) => !supportedPlatformStrings.contains(s))
+            .toList();
+        if (invalid.isNotEmpty) {
+          Log.w(
+            'Unknown platform identifier(s) in "platform": $invalid. Supported: $supportedPlatformStrings',
+          );
+        }
+
+        final isPlatformSupported = validatedPlatforms.contains(
+          currentPlatform,
+        );
+
+        if (!isPlatformSupported && validatedPlatforms.isNotEmpty) {
+          Log.w(
+            'Widget not supported on platform [$currentPlatform]. Only available for: ${validatedPlatforms.join(', ')}',
+          );
+          return null;
+        }
+      }
+
       // Safely extract widget type with validation
       final widgetType = json['type'];
       if (widgetType == null) {

packages/stac/lib/src/parsers/foundation/foundation.dart

@@ -69,6 +69,7 @@ export 'layout/stac_stack_fit_parser.dart';
 export 'layout/stac_vertical_direction_parser.dart';
 export 'layout/stac_wrap_alignment_parser.dart';
 export 'layout/stac_wrap_cross_alignment_parser.dart';
+export 'layout/parsers.dart';
 // Navigation parsers
 export 'navigation/stac_bottom_navigation_bar_landscape_layout_parser.dart';
 export 'navigation/stac_bottom_navigation_bar_type_parser.dart';

packages/stac/lib/src/parsers/foundation/layout/parsers.dart

@@ -0,0 +1,10 @@
+export 'stac_axis_parser.dart';
+export 'stac_box_fit_parser.dart';
+export 'stac_box_shape_parser.dart';
+export 'stac_clip_parser.dart';
+export 'stac_flex_fit_parser.dart';
+export 'stac_material_tap_target_size_parser.dart';
+export 'stac_stack_fit_parser.dart';
+export 'stac_vertical_direction_parser.dart';
+export 'stac_wrap_alignment_parser.dart';
+export 'stac_wrap_cross_alignment_parser.dart';

packages/stac/lib/src/parsers/widgets/widgets.dart

@@ -20,6 +20,7 @@ export 'package:stac/src/parsers/widgets/stac_column/stac_column_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_conditional/stac_conditional_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_container/stac_container_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_custom_scroll_view/stac_custom_scroll_view_parser.dart';
+export 'package:stac/src/parsers/widgets/stac_double/stac_double.dart';
 export 'package:stac/src/parsers/widgets/stac_default_bottom_navigation_controller/stac_default_bottom_navigation_controller_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_default_tab_controller/stac_default_tab_controller_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_divider/stac_divider_parser.dart';
@@ -58,6 +59,7 @@ export 'package:stac/src/parsers/widgets/stac_refresh_indicator/stac_refresh_ind
 export 'package:stac/src/parsers/widgets/stac_safe_area/stac_safe_area_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_scaffold/stac_scaffold_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_selectable_text/stac_selectable_text_parser.dart';
+export 'package:stac/src/parsers/widgets/stac_text/stac_text_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_set_value/stac_set_value_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_single_child_scroll_view/stac_single_child_scroll_view_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_sized_box/stac_sized_box_parser.dart';

packages/stac/lib/src/utils/color_utils.dart

@@ -1,5 +1,6 @@
 import 'package:flutter/material.dart';
 import 'package:stac/src/utils/color_type.dart';
+import 'package:stac/stac.dart';
 
 const String _hashtag = "#";
 const String _empty = "";
@@ -145,6 +146,10 @@ Color? _parseThemeColor(String color, BuildContext context) {
     case StacColorType.surfaceTint:
       return Theme.of(context).colorScheme.surfaceTint;
     case StacColorType.none:
+      final customColor = StacRegistry.instance.parseCustomColor?.call(color);
+      if (customColor != null) {
+        return customColor;
+      }
       return null;
   }
 }

packages/stac/lib/src/utils/stac_platforms.dart

@@ -0,0 +1,28 @@
+import 'package:flutter/foundation.dart';
+
+/// Canonical platform identifiers supported in JSON "platform" field.
+/// Incoming values are normalized (e.g. lowercased) and validated against this list.
+const List<String> supportedPlatformStrings = [
+  'android',
+  'ios',
+  'linux',
+  'macos',
+  'windows',
+  'web',
+];
+
+/// Returns the current platform as a canonical string (one of [supportedPlatformStrings]).
+String currentPlatformString() {
+  if (kIsWeb) {
+    return 'web';
+  }
+
+  return switch (defaultTargetPlatform) {
+    TargetPlatform.android => 'android',
+    TargetPlatform.iOS => 'ios',
+    TargetPlatform.linux => 'linux',
+    TargetPlatform.macOS => 'macos',
+    TargetPlatform.windows => 'windows',
+    _ => 'unknown',
+  };
+}

packages/stac/lib/src/utils/utils.dart

@@ -1 +1,3 @@
 export 'package:stac/src/utils/color_utils.dart';
+export 'package:stac/src/utils/version/stac_version.dart';
+export 'package:stac/src/utils/stac_platforms.dart';