feat(flowr): export FrState presets for mvvm state

Author: Hu-Wentao

packages/flowr/README.md

@@ -94,6 +94,14 @@ class CounterPage extends StatelessWidget {
 
 `FlowR` follows bloc equality semantics. Do not rely on in-place model mutation plus `put/update`; return a new state instance when the UI should rebuild.
 
+For immutable page state modeled with Freezed, `flowr` also exports two
+recommended presets:
+
+- `@FrState`: enables `toJson()` for debug snapshots without implying restore
+  semantics.
+- `@FrStateJson`: enables both `toJson()` and `fromJson()` for state that must
+  be restored from serialized JSON.
+
 For GetIt DI, register a ViewModel and then read it with `context.read<T>()`.
 `context.read<T>()` reads Provider first, then GetIt.
 

packages/flowr/lib/flowr_mvvm.dart

@@ -25,6 +25,7 @@ export 'package:flowr/src/view_model.dart';
 export 'package:flowr/src/view.dart';
 export 'package:flowr/src/view/value_stream_widget.dart';
 export 'package:flowr/src/provider.dart';
+export 'package:flowr/src/annotations/fr_state.dart';
 
 /// FlowR-Union
 export 'package:flowr/src/fr_union.dart';

packages/flowr/lib/src/annotations/fr_state.dart

@@ -0,0 +1,29 @@
+import 'package:freezed_annotation/freezed_annotation.dart';
+
+/// Recommended Freezed preset for page-local immutable state that should be
+/// easy to inspect in logs and debug tools.
+///
+/// This enables `toJson()` for snapshotting state, but keeps `fromJson()`
+/// disabled so ordinary UI state does not implicitly claim restore semantics.
+// ignore: constant_identifier_names
+const FrState = Freezed(
+  copyWith: true,
+  equal: true,
+  toStringOverride: true,
+  fromJson: false,
+  toJson: true,
+);
+
+/// Recommended Freezed preset for page-local immutable state that must be
+/// restored from serialized JSON, such as persisted or recoverable UI state.
+///
+/// Use this only when the state class genuinely needs `fromJson()` in
+/// addition to debug-friendly `toJson()`.
+// ignore: constant_identifier_names
+const FrStateJson = Freezed(
+  copyWith: true,
+  equal: true,
+  toStringOverride: true,
+  fromJson: true,
+  toJson: true,
+);

packages/flowr/pubspec.yaml

@@ -33,6 +33,7 @@ dependencies:
   provider: ^6.1.5
   stack_trace: ^1.11.1
   async: ^2.11.0 # fixed; adapt flutter 3.16.7;
+  freezed_annotation: ">=2.4.4 <4.0.0"
 
 dev_dependencies:
   flutter_test:

packages/flowr/test/annotations_test.dart

@@ -0,0 +1,23 @@
+import 'package:flowr/flowr_mvvm.dart';
+import 'package:freezed_annotation/freezed_annotation.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  test('FrState exposes the debug-state preset', () {
+    expect(FrState, isA<Freezed>());
+    expect(FrState.copyWith, isTrue);
+    expect(FrState.equal, isTrue);
+    expect(FrState.toStringOverride, isTrue);
+    expect(FrState.fromJson, isFalse);
+    expect(FrState.toJson, isTrue);
+  });
+
+  test('FrStateJson exposes the restorable-state preset', () {
+    expect(FrStateJson, isA<Freezed>());
+    expect(FrStateJson.copyWith, isTrue);
+    expect(FrStateJson.equal, isTrue);
+    expect(FrStateJson.toStringOverride, isTrue);
+    expect(FrStateJson.fromJson, isTrue);
+    expect(FrStateJson.toJson, isTrue);
+  });
+}

packages/fr_acdd/README.md

@@ -24,8 +24,9 @@ class NotificationsScreenDataModel with _$NotificationsScreenDataModel {
 
 Use `@FrAcddFreezed`, `@FrAcddFreezedJSON`, or `@Freezed(...)` for extractable
 DTOs. Keep page-local state on non-DTO models without `@FrAcddDto`. When the
-page is scaffolded by `fr-mvvm-contract`, that usually means the generated
-`@FrState` preset; use plain `@Freezed(...)` only when the state model holds
+page is scaffolded by `fr-mvvm-contract`, that usually means FlowR's exported
+`@FrState` preset; use `@FrStateJson` only when the state model truly needs
+`fromJson()`, and use plain `@Freezed(...)` when the state model holds
 runtime-only or non-JSON-serializable fields.
 
 `@FrAcddFreezed` is the minimal extraction preset, not a claim that every DTO

skills/README.md

@@ -45,11 +45,13 @@ any temporary JSON spec is just generator input and should not be committed as
 a parallel design artifact. Temporary page specs now require `page.figmaUrl`
 and `page.api`, with optional `page.apiContract` when `page.api` is
 `BFF`. Non-DTO page-local models now default to the generated `@FrState`
-Freezed preset so `toJson()` is available during debugging; use
-`models[].preset = "plain"` when a model contains runtime-only or
-non-JSON-serializable fields. Generated pages now require
-`freezed_annotation`, `freezed`, and `build_runner` in the target project. If
-the target project has not installed those yet, use
+Freezed preset exported by `flowr` so `toJson()` is available during
+debugging; use `models[].preset = "state_json"` only when a model must be
+restored from JSON, or `models[].preset = "plain"` when it contains
+runtime-only or non-JSON-serializable fields. Generated pages now require
+`freezed_annotation`, `freezed`, `build_runner`, and a `flowr` version that
+exports `FrState` / `FrStateJson` in the target project. If the target
+project has not installed those yet, use
 `skills/flowr-dart-usage/references/freezed-install.md` first. See
 `skills/fr-mvvm-contract/SKILL.md` for the required spec shape. When a
 contract page uses `bff` mode, the target project also needs `fr_acdd`; use

skills/fr-mvvm-contract/SKILL.md

@@ -24,7 +24,7 @@ This skill is intentionally strict:
 - Only generate `FrBlocViewModel<GeneratedEvent, GeneratedModel>`.
 - Generate page models with Freezed-based presets, not handwritten
   `copyWith`. Non-DTO state models default to the generated `@FrState`
-  annotation so they expose `toJson()` for debugging.
+  annotation exported by `flowr` so they expose `toJson()` for debugging.
 - Do not add `FrViewModel` / method-mode content here.
 - Treat the contract dart file as the authoritative spec for the generated
   parts.
@@ -64,6 +64,9 @@ page.
   - `part '<contract_name>.g.dart';` when a theme or any state model enables
     generated JSON helpers. With the default `@FrState` preset on page-local
     models, that usually means the contract file includes `.g.dart`.
+- Target projects must use a `flowr` version that exports `FrState` and
+  `FrStateJson`. The generator no longer injects local `const FrState = ...`
+  definitions into the contract file.
 - Target project runtime deps need `freezed_annotation`.
 - Target project dev deps need `freezed` and `build_runner`.
 - `bff` pages also need `fr_acdd` in the target package dependencies.
@@ -254,7 +257,8 @@ part '<contract_name>.vm.dart';
 - Also declare `part '<contract_name>.g.dart';` whenever the contract library
   enables generated JSON helpers. The default `@FrState` preset on page-local
   models does this automatically; `preset: plain` is the opt-out when a model
-  contains non-serializable runtime fields.
+  contains non-serializable runtime fields, and `preset: state_json` is the
+  opt-in when a model must restore itself from JSON.
 
 - Keep the contract doc comments above the root widget in this order:
   - Figma
@@ -318,8 +322,10 @@ part '<contract_name>.vm.dart';
 - Always use `FrBlocViewModel<GeneratedEvent, GeneratedModel>`.
 - Events are generated under one sealed base class in the contract library.
 - Non-DTO page models are generated in the contract file with `@FrState` by
-  default. `@FrState` is a contract-local `Freezed` preset that enables JSON
-  hooks so `toJson()` is available for debug snapshots.
+  default. `flowr` exports `@FrState` as a shared `Freezed` preset that
+  enables `toJson()` for debug snapshots without implying restore semantics.
+- Use `@FrStateJson` only when the state class genuinely needs
+  `factory Xxx.fromJson(...)` so it can be restored from serialized JSON.
 - In `bff` mode, only backend-transfer DTOs should use `@FrAcddDto`. Keep
   page-local state in page models or view-model members instead of annotating
   it as DTO state.
@@ -415,15 +421,18 @@ If `theme` is present, it supports:
   - the generated primary model's private constructor
   - the generated primary model's `const factory`
 - `preset` defaults to `state`.
-- `preset: state` emits a contract-local `@FrState` preset equivalent to
-  `@Freezed(copyWith: true, equal: true, toStringOverride: true, fromJson: true, toJson: true)`,
-  adds `factory Xxx.fromJson(...)`, and requires `part '<contract_name>.g.dart';`.
+- `preset: state` emits `@FrState`, equivalent to
+  `@Freezed(copyWith: true, equal: true, toStringOverride: true, fromJson: false, toJson: true)`,
+  and requires `part '<contract_name>.g.dart';`.
+- `preset: state_json` emits `@FrStateJson`, adds
+  `factory Xxx.fromJson(...)`, and requires `part '<contract_name>.g.dart';`.
 - `preset: plain` falls back to
   `@Freezed(copyWith: true, equal: true, toStringOverride: true, fromJson: false, toJson: false)`.
 - `copyWith`, equality, debug `toString`, and the state-model debug `toJson()`
   snapshot are provided by `Freezed`, not handwritten by this script.
 - Generated state models deliberately enable JSON hooks so `toJson()` is
-  available during debugging. If a model contains runtime-only or
+  available during debugging. Only `preset: state_json` enables restore
+  semantics through `fromJson()`. If a model contains runtime-only or
   non-JSON-serializable fields, set `preset: plain` or move those fields out
   of the immutable page model to avoid hidden build failures.
 - `@FrAcddDto` does not imply runtime JSON serialization by itself. In this

skills/fr-mvvm-contract/references/fr-acdd.md

@@ -62,8 +62,9 @@ fvm dart run fr_acdd:extract_bff --format json5 --input lib/page/notifications_p
   Freezed unions for extractable DTOs.
 - `@FrAcddDto` is only for backend-transfer DTOs. Do not annotate page-local
   state classes as DTO kinds. In `fr-mvvm-contract`, page-local models now
-  default to the generated `@FrState` preset so `toJson()` is available for
-  debugging; fall back to plain `@Freezed(...)` only when the model contains
+  default to FlowR's exported `@FrState` preset so `toJson()` is available for
+  debugging. Use `@FrStateJson` only when the state model truly needs
+  `fromJson()`, and fall back to plain `@Freezed(...)` when the model contains
   runtime-only or non-JSON-serializable fields.
 - If a DTO really does cross a runtime JSON boundary, keep `@FrAcddDto` and
   prefer `@FrAcddFreezedJSON`. Use explicit `@Freezed(...)` only when that

skills/fr-mvvm-contract/scripts/new_page.py

@@ -27,6 +27,7 @@
 ARTIFACT_JSON = "JSON"
 ARTIFACT_PROTO = "PROTO"
 MODEL_PRESET_STATE = "state"
+MODEL_PRESET_STATE_JSON = "state_json"
 MODEL_PRESET_PLAIN = "plain"
 SKIP_DIRS = {".dart_tool", ".git", ".idea", ".vscode", "build", "ios/Pods"}
 
@@ -478,8 +479,12 @@ def parse_model_preset(value: Any, path: str) -> str:
     if value is None:
         return MODEL_PRESET_STATE
     preset = require_str(value, path).lower()
-    if preset not in (MODEL_PRESET_STATE, MODEL_PRESET_PLAIN):
-        raise SpecError(f"{path} must be `state` or `plain`")
+    if preset not in (
+        MODEL_PRESET_STATE,
+        MODEL_PRESET_STATE_JSON,
+        MODEL_PRESET_PLAIN,
+    ):
+        raise SpecError(f"{path} must be `state`, `state_json`, or `plain`")
     return preset
 
 
@@ -964,6 +969,8 @@ def render_model_class(model: dict[str, Any]) -> str:
         parts.append(comment)
     if model["preset"] == MODEL_PRESET_STATE:
         parts.append("@FrState")
+    elif model["preset"] == MODEL_PRESET_STATE_JSON:
+        parts.append("@FrStateJson")
     else:
         parts.append("@Freezed(")
         parts.append("  copyWith: true,")
@@ -975,7 +982,7 @@ def render_model_class(model: dict[str, Any]) -> str:
     parts.append(f"class {model['name']} with _${model['name']} {{")
     parts.append(f"  const {model['name']}._();")
     parts.append("")
-    if model["preset"] == MODEL_PRESET_STATE:
+    if model["preset"] == MODEL_PRESET_STATE_JSON:
         parts.append(
             f"  factory {model['name']}.fromJson(Map<String, dynamic> json) => "
             f"_${model['name']}FromJson(json);"
@@ -1138,25 +1145,11 @@ def theme_uses_generated_part(theme: dict[str, Any] | None) -> bool:
 
 
 def model_uses_generated_part(model: dict[str, Any]) -> bool:
-    if model["preset"] == MODEL_PRESET_STATE:
+    if model["preset"] in (MODEL_PRESET_STATE, MODEL_PRESET_STATE_JSON):
         return True
     return any(code_uses_generated_part(member) for member in model["members"])
 
 
-def render_state_preset() -> str:
-    return "\n".join(
-        (
-            "const FrState = Freezed(",
-            "  copyWith: true,",
-            "  equal: true,",
-            "  toStringOverride: true,",
-            "  fromJson: true,",
-            "  toJson: true,",
-            ");",
-        )
-    )
-
-
 def render_contract_file(
     page: dict[str, Any],
     models: list[dict[str, Any]],
@@ -1174,9 +1167,6 @@ def render_contract_file(
     lines.append(f"part '{page['file_name']}.v.dart';")
     lines.append(f"part '{page['file_name']}.vm.dart';")
     lines.append("")
-    if any(model["preset"] == MODEL_PRESET_STATE for model in models):
-        lines.append(render_state_preset())
-        lines.append("")
 
     lines.extend(section_lines("Figma", page["figma"]))
     if page["api_reference"] != API_BFF: