State
Two kinds, by lifetime. Screen state lives while a screen is open — a filter toggle, a password's visibility. App state outlives screens — a cart, a chosen currency, whether onboarding has been seen.
Declaring values
Screen state is declared in a screen's inspector under Local state; app state in the App panel under App state. Each value has a name, a type — bool, string, number, or a list of strings or numbers — and an initial value.
Read them by scope: state.showFilters on the screen that declares it, app.cart from any screen. A list exposes one intrinsic, .length; its items are shown by repeating a list widget over it.
Changing values
Five actions, each naming its scope explicitly. There is no lookup order: a screen value and an app value may share a name and never collide.
{"type": "setState", "scope": "screen", "name": "showFilters", "value": {"literal": true}}
{"type": "toggleState", "scope": "screen", "name": "showFilters"}
{"type": "appendState", "scope": "app", "name": "cart", "value": {"literal": "sku_1"}}
{"type": "removeState", "scope": "app", "name": "cart", "value": {"from": "row", "path": "value"}}
{"type": "clearState", "scope": "app", "name": "cart"}toggle applies to bools only; append, remove and clear to lists only; set to scalars only. The checks refuse the rest before export.
Persistence and sign-out
An app value can persist on device, surviving a relaunch. By default a persisted value is cleared when the user signs out — a cart or a draft must not be inherited by the next person on the same phone. Values that belong to the device rather than the person — a preferred currency, an onboarding flag — opt in with keep after sign-out.
In the export
core/app_state.dart; persisted values write through to shared_preferences, and sign-out resets the non-retained ones in both the provider and storage.