fix: clarify API elements that are not stabilized (#46)

examples/presentation/pubspec.yaml

@@ -9,10 +9,7 @@ dependencies:
   device_frame: ^1.1.0
   flutter:
     sdk: flutter
-  flutter_deck: # ^0.8.0
-    git:
-      url: https://github.com/GregoryConrad/flutter_deck
-      ref: fullscreen-button
+  flutter_deck: ^0.9.1
   flutter_rearch: ^1.2.3
   graphview: ^1.2.0
   rearch: ^1.3.3

packages/flutter_rearch/lib/flutter_rearch.dart

@@ -1,11 +1,16 @@
 import 'package:flutter/widgets.dart';
 import 'package:flutter_rearch/src/widgets.dart';
+import 'package:meta/meta.dart';
 import 'package:rearch/rearch.dart';
 
 export 'src/side_effects.dart';
 export 'src/widgets.dart';
 
 /// The API exposed to [RearchConsumer]s to extend their functionality.
+///
+/// New methods may be added to this interface on any new _minor_ release
+/// (minor in terms of semver).
+@experimental
 abstract interface class WidgetSideEffectApi implements SideEffectApi {
   /// The [BuildContext] of the associated [RearchConsumer].
   BuildContext get context;

packages/flutter_rearch/lib/src/side_effects.dart

@@ -1,6 +1,7 @@
 import 'package:flutter/scheduler.dart';
 import 'package:flutter/widgets.dart';
 import 'package:flutter_rearch/flutter_rearch.dart';
+import 'package:rearch/experimental.dart';
 import 'package:rearch/rearch.dart';
 
 part 'side_effects/animation.dart';

packages/flutter_rearch/pubspec.yaml

@@ -13,6 +13,7 @@ environment:
 dependencies:
   flutter:
     sdk: flutter
+  meta: ^1.10.0
   rearch: ^1.3.3
 
 dev_dependencies:

packages/rearch/lib/experimental.dart

@@ -0,0 +1,33 @@
+/// A collection of ReArch experiments in case you like exploring the unknown.
+///
+/// Nothing here is officially supported;
+/// items may come and go or experience breaking changes on any new release.
+/// Further, items here may be untested so use at your own risk!
+@experimental
+library experimental;
+
+import 'package:meta/meta.dart';
+import 'package:rearch/rearch.dart';
+
+extension _UseConvenience on SideEffectRegistrar {
+  SideEffectRegistrar get use => this;
+}
+
+/// A collection of experimental side effects to
+/// complement the [BuiltinSideEffects].
+extension ExperimentalSideEffects on SideEffectRegistrar {
+  /// Returns a raw value wrapper; i.e., a getter and setter for some value.
+  /// *The setter will not trigger rebuilds*.
+  /// The initial state will be set to the result of running [init],
+  /// if it was provided. Otherwise, you must manually set it
+  /// via the setter before ever calling the getter.
+  // NOTE: experimental because I am not sold on the API and use cases
+  // for non-internal usage.
+  (T Function(), void Function(T)) rawValueWrapper<T>([T Function()? init]) {
+    return use.callonce(() {
+      late T state;
+      if (init != null) state = init();
+      return (() => state, (T newState) => state = newState);
+    });
+  }
+}

packages/rearch/lib/rearch.dart

@@ -71,6 +71,10 @@ typedef SideEffect<T> = T Function(SideEffectApi);
 typedef SideEffectApiCallback = void Function();
 
 /// The api given to [SideEffect]s to create their state.
+///
+/// New methods may be added to this interface on any new _minor_ release
+/// (minor in terms of semver).
+@experimental
 abstract interface class SideEffectApi {
   /// Triggers a rebuild in the supplied capsule.
   void rebuild();

packages/rearch/lib/src/side_effects.dart

@@ -1,6 +1,6 @@
 import 'dart:async';
 
-import 'package:meta/meta.dart';
+import 'package:rearch/experimental.dart';
 import 'package:rearch/rearch.dart';
 
 extension _UseConvenience on SideEffectRegistrar {
@@ -26,20 +26,6 @@ extension BuiltinSideEffects on SideEffectRegistrar {
   /// Side effect that calls the supplied [callback] once, on the first build.
   T callonce<T>(T Function() callback) => use.register((_) => callback());
 
-  /// Returns a raw value wrapper; i.e., a getter and setter for some value.
-  /// *The setter will not trigger rebuilds*.
-  /// The initial state will be set to the result of running [init],
-  /// if it was provided. Otherwise, you must manually set it
-  /// via the setter before ever calling the getter.
-  @experimental
-  (T Function(), void Function(T)) rawValueWrapper<T>([T Function()? init]) {
-    return use.callonce(() {
-      late T state;
-      if (init != null) state = init();
-      return (() => state, (T newState) => state = newState);
-    });
-  }
-
   /// Side effect that provides a way for capsules to contain some state,
   /// where the initial state is computationally expensive.
   /// Further, instead of returning the state directly, this instead returns
@@ -222,10 +208,10 @@ extension BuiltinSideEffects on SideEffectRegistrar {
     return getValue();
   }
 
-  /// A mechanism to persist changes made in state.
+  /// A mechanism to persist changes made in state that manages its own state.
   /// See the docs for usage information.
   ///
-  /// Defines the way to interact with a storage provider of your choice
+  /// Defines a way to interact with a storage provider of your choice
   /// through the [read] and [write] parameters.
   ///
   /// [read] is only called once; it is assumed that if [write] is successful,