When to use RefAppState
========================

**RefAppState** and **RefSlot** exist for **performance and scale**.

They are powerful,
but they are **not** the default way to manage state in SimpleAppState.

Most applications should use:

- **SimpleAppState**
- **StateSlot**

almost everywhere.

This page explains when reference-based state is appropriate,
and when it is not.

----

The default: value semantics
----------------------------

**SimpleAppState** uses **value semantics**:

- values are deep-copied on read
- values are replaced on write
- state transitions are explicit
- undo, redo, and persistence are safe

This is what makes SimpleAppState easy to reason about.

For the vast majority of app state, this is exactly what you want:

- counters
- selections
- settings
- UI state
- domain objects
- lists and maps

If you are not sure which to use,
use **SimpleAppState**.

----

What RefAppState is for
------------------------

**RefAppState** is for data that is:

- very large
- expensive to copy
- mutated frequently
- conceptually a single object

Typical examples:

- 3D or 2D scene graphs
- geometry models
- large document trees
- binary or image buffers

Copying these on every read or update
would be too slow or too memory-intensive.

**RefAppState** allows these objects
to live as **shared references**
while still participating in:

- slot-based updates
- widget rebuilds
- undo / redo
- persistence

----

Enums and identity-based models
-------------------------------

Another valid use case is **identity-based models**.

For example:

- enum-like objects
- flyweight instances
- canonical singletons
- object graphs where identity matters

In these cases, copying would break meaning.

A reference slot preserves identity
while still letting SimpleAppState track changes.

----

Why beginners should not use RefAppState
----------------------------------------

Reference semantics are harder to reason about.

With **StateSlot**:

- reading never mutates state
- updates are always explicit
- bugs are localized

With **RefSlot**:

- reading can mutate state
- changes can happen deep inside objects
- it is easier to forget to notify

This is powerful,
but also more dangerous.

For this reason:

> **RefAppState** is an advanced tool for special cases.

Most application logic should stay
in **SimpleAppState** and **StateSlot**.

----

Mixing SimpleAppState and RefAppState
--------------------------------------

It is normal to use **both** in one application.

A common pattern:

- **SimpleAppState** for UI and domain state
- **RefAppState** for large models or engines

They are designed to work together.

Widgets can subscribe to slots from both systems,
and batch updates can coordinate them.

----

File organization
-----------------

A recommended project structure is:

- **app_state.dart**
  contains **SimpleAppState** and all **StateSlot** definitions

- **ref_state.dart**
  contains **RefAppState** and all **RefSlot** definitions

This makes the separation explicit:

- most developers work in **app_state.dart**
- only performance-critical code touches **ref_state.dart**

This is a convention, not a requirement,
but it helps keep reference-based state
clearly isolated.

----

Summary
-------

Use **SimpleAppState** and **StateSlot** by default.

Use **RefAppState** and **RefSlot** only when:

- copying is too expensive
- object identity must be preserved
- the data is inherently large or mutable

If you are in doubt:

**do not use RefAppState.**

It is better to start with value semantics
and introduce references only when you truly need them.