chore: fine-tune descriptions

Author: edvincandon

README.md

@@ -7,21 +7,20 @@
   <a href="https://redux-toolkit.js.org/"><img src="https://img.shields.io/badge/RTK-%5E2.11.2-764ABC?logo=redux&logoColor=white" alt="Redux Toolkit ^2.11.2"/></a>
 </p>
 
-> Optimistic state management for Redux. No state copies, no checkpoints — optimistic state is derived at the selector level, like `git rebase`.
+> Optimistic state management for Redux. Optimistic state is derived at the selector level by replaying transitions on top of committed state, similar to `git rebase`.
 
 ---
 
 ## Why Optimistron?
 
-Most optimistic-update libraries snapshot your entire state tree for every in-flight operation. Optimistron doesn't. It tracks lightweight **transitions** (stage, amend, commit, fail) alongside your reducer state and replays them at read-time through `selectOptimistic` — right where `reselect` memoization already lives.
+Optimistron tracks lightweight **transitions** (stage, amend, commit, fail) alongside your reducer state and replays them at read-time through `selectOptimistic`. No state snapshots or checkpoints are stored per operation.
 
-Good fit for:
+Optimistron was designed around an **event-driven saga architecture** — components dispatch intent via `stage`, and sagas (or listener middleware) orchestrate the transition lifecycle. It can be used with thunks or direct component dispatches, but the separation between intent and orchestration is where it fits most naturally.
 
-- **Offline-first** — transitions queue up while disconnected, conflicts resolve on reconnect
-- **Async dispatch** — thunks, sagas, listener middleware
-- **Large/normalized state** — no per-operation snapshots
+Designed for:
 
-> Already happy with RTK Query's built-in optimistic updates? You probably don't need this.
+- **Offline-first** — transitions queue up while disconnected, conflicts resolve on reconnect
+- **Large/normalized state** — state is derived, not copied
 
 ---
 
@@ -38,7 +37,7 @@ Think of each `optimistron()` reducer as a **git branch**:
 
 `STAGE`, `AMEND`, `FAIL`, `STASH` never touch reducer state — they only modify the transitions list. The optimistic view updates because `selectOptimistic` re-derives on the next read.
 
-No `isLoading` / `error` / `isOptimistic` flags. A pending transition _is_ loading. A failed one _is_ the error. One source of truth.
+There are no separate `isLoading` / `error` / `isOptimistic` flags — a pending transition represents the loading state, and a failed transition carries the error.
 
 ---
 
@@ -165,15 +164,15 @@ const handler = listState<Todo>({ key: 'id', compare, eq });
 const crud = crudPrepare<Todo>('id');
 ```
 
-You can implement the `StateHandler` interface for any shape — the built-ins are just the common cases.
+Custom shapes can implement the `StateHandler` interface directly.
 
 ---
 
 ## Reducer Configuration
 
 The 4th argument to `optimistron()` supports three modes:
 
-**Auto-wired** — zero boilerplate, handler routes payloads:
+**Auto-wired** — handler routes payloads by CRUD type:
 
 ```typescript
 optimistron('todos', initial, handler, {

usecases/basic/App.tsx

@@ -19,11 +19,11 @@ import { generateId, simulateAPIRequest } from '~usecases/lib/utils/mock-api';
 import { C, F, O } from '~usecases/lib/components/todo/CodeTags';
 
 const description: UsecaseDescription = {
-    subtitle: 'Component-level async — full transition lifecycle managed in the component.',
+    subtitle: 'Component-level async — the transition lifecycle is managed directly in the component.',
     howItWorks: [
         <>Component dispatches <O>stage</O>, awaits the API, then <O>amend</O>s / <C>commit</C>s or <F>fail</F>s directly.</>,
-        <>The full lifecycle (<O>stage</O> → API → <O>amend</O> → <C>commit</C> / <F>fail</F>) lives in the handler function — maximum visibility, minimum indirection.</>,
-        <>Optimistic state is computed at the selector level via <code className="text-gray-400 text-[11px]">selectOptimistic</code> — no state copies, no checkpoints.</>,
+        <>The full lifecycle (<O>stage</O> → API → <O>amend</O> → <C>commit</C> / <F>fail</F>) lives in the handler function.</>,
+        <>Optimistic state is computed at the selector level via <code className="text-gray-400 text-[11px]">selectOptimistic</code>.</>,
         <>Failed transitions can be edited in-place — a new <O>stage</O> overwrites the failed one, restarting the lifecycle.</>,
     ],
 };

usecases/index.tsx

@@ -181,14 +181,14 @@ const Home: FC = () => (
 
             <div className="text-left text-sm text-gray-400 leading-relaxed space-y-3 mb-8">
                 <p>
-                    This demo is a <span className="text-gray-200">project management app</span> built to showcase Optimistron — each section uses a different
-                    state shape with full optimistic CRUD.
+                    A <span className="text-gray-200">project management app</span> demonstrating Optimistron — each section uses a different
+                    state shape with optimistic CRUD.
                 </p>
                 <p>
-                    <code className="text-[10px] text-fuchsia-400 bg-surface-3 px-1 py-0.5 rounded">singularState</code> powers the user profile,{' '}
-                    <code className="text-[10px] text-amber-400 bg-surface-3 px-1 py-0.5 rounded">nestedRecordState</code> drives project-grouped tasks,{' '}
-                    <code className="text-[10px] text-cyan-400 bg-surface-3 px-1 py-0.5 rounded">recordState</code> backs the flat epic list, and{' '}
-                    <code className="text-[10px] text-green-400 bg-surface-3 px-1 py-0.5 rounded">listState</code> powers the activity log.
+                    <code className="text-[10px] text-fuchsia-400 bg-surface-3 px-1 py-0.5 rounded">singularState</code> for the user profile,{' '}
+                    <code className="text-[10px] text-amber-400 bg-surface-3 px-1 py-0.5 rounded">nestedRecordState</code> for project-grouped tasks,{' '}
+                    <code className="text-[10px] text-cyan-400 bg-surface-3 px-1 py-0.5 rounded">recordState</code> for the flat epic list, and{' '}
+                    <code className="text-[10px] text-green-400 bg-surface-3 px-1 py-0.5 rounded">listState</code> for the activity log.
                 </p>
             </div>
 

usecases/sagas/App.tsx

@@ -16,11 +16,11 @@ import type { ActivityEntry, Epic, Profile, ProjectTodo } from '~usecases/lib/st
 import { C, F, O } from '~usecases/lib/components/todo/CodeTags';
 
 const description: UsecaseDescription = {
-    subtitle: 'Redux sagas — the most decoupled approach.',
+    subtitle: 'Redux sagas — lifecycle orchestration decoupled from components.',
     howItWorks: [
-        <>Component only dispatches <O>stage</O> — that's it. No async, no lifecycle awareness.</>,
+        <>Component only dispatches <O>stage</O>. No async logic or lifecycle management in the component.</>,
         <>Saga watcher observes <O>stage</O> via <code className="text-gray-400 text-[11px]">takeEvery</code> and orchestrates the full lifecycle to <C>commit</C> or <F>fail</F>.</>,
-        <>Maximum separation: UI fires intent, saga handles all orchestration — components are pure dispatch.</>,
+        <>UI dispatches intent, saga handles orchestration — components only call dispatch.</>,
         <>Failed transitions can be edited in-place — a new <O>stage</O> overwrites the failed one, the saga picks it up automatically.</>,
     ],
 };

usecases/thunks/App.tsx

@@ -31,11 +31,11 @@ import {
 import { C, F, O } from '~usecases/lib/components/todo/CodeTags';
 
 const description: UsecaseDescription = {
-    subtitle: 'Redux thunks — same lifecycle, cleaner components.',
+    subtitle: 'Redux thunks — lifecycle logic moved from components into thunks.',
     howItWorks: [
-        <>Component dispatches a thunk — no transition management in the component at all.</>,
+        <>Component dispatches a thunk. No transition management in the component.</>,
         <>Each thunk encapsulates the full lifecycle: <O>stage</O> → API → <O>amend</O> → <C>commit</C> / <F>fail</F>.</>,
-        <>Same optimistic behavior as Basic — components only call <code className="text-gray-400 text-[11px]">dispatch(thunk(item))</code>.</>,
+        <>Components only call <code className="text-gray-400 text-[11px]">dispatch(thunk(item))</code>.</>,
         <>Failed transitions can be edited in-place — a new <O>stage</O> overwrites the failed one, restarting the lifecycle.</>,
     ],
 };