Docs

packages/docs/docs/state-management.md

@@ -5,15 +5,20 @@ title: State Management
 
 # State Management
 
-`effect-fc` works well with state that lives in Effect services, layers, and
-scopes. The usual pattern is:
+`Lens` is the main type used for state management in `effect-fc`.
 
-1. Create state with Effect primitives such as `SubscriptionRef`.
-2. Turn the Effect primitive into a `Lens` with the matching constructor, such
-   as `Lens.fromSubscriptionRef`.
-3. Expose read-only reactive state as a `Subscribable`.
-4. Expose read/write reactive state as a `Lens`.
-5. Bind values into components with `Subscribable.useAll`.
+A Lens is an effectful handle to a piece of state. It can read the current value,
+subscribe to changes, and write updates back to the underlying source. A Lens
+can point at a whole state object or focus on one nested field inside it.
+
+The usual pattern is to create state with Effect primitives such as
+`SubscriptionRef`, turn that primitive into a Lens with a matching constructor
+such as `Lens.fromSubscriptionRef`, and bind Lens values into components with
+`Subscribable.useAll`.
+
+`Subscribable` is the read-only side of this model. Every Lens is also a
+Subscribable, so use `Subscribable.useAll` whenever a component only needs to
+read reactive state.
 
 `effect-fc` re-exports the `Lens` and `Subscribable` modules from
 [`effect-lens`](https://github.com/Thiladev/effect-lens) for convenience. The
@@ -113,8 +118,7 @@ const CounterReadOnlyView = Component.make("CounterReadOnly")(
 
 `Subscribable.useAll` reads the current values during render and uses scoped subscriptions to update React state when changes arrive.
 
-When you need to modify state, write to the Lens with `Lens.set` or
-`Lens.update` from an Effect-FC callback:
+When you need to modify state, write to the Lens with `Lens.set` or `Lens.update`:
 
 ```tsx
 const CounterControlsView = Component.make("CounterControls")(