chore(docs): rewrite the readme

Author: aleclarson

README.md

@@ -1,23 +1,56 @@
 # preact-sigma
 
-`preact-sigma` is a typed state-model builder for apps that want Preact's fine-grained reactivity, Immer-backed writes, and explicit lifecycle.
+`preact-sigma` lets you define state once and reuse it as a model.
 
-You define a reusable state type once, then create instances wherever they make sense: inside components, in shared modules, or in plain TypeScript code. Each instance exposes readonly public state, tracked derived reads, imperative actions, and optional setup and event APIs.
+It is built for Preact and TypeScript, and combines:
 
-## Getting Started
+- fine-grained reactive reads
+- Immer-style writes
+- explicit setup and cleanup
+- typed events
+- a constructor you can instantiate anywhere
 
-To add `preact-sigma` to your project:
+Use it when your state has started to feel like more than "some values in a component."
+
+Instead of spreading logic across loose signals, reducers, effects, and cleanup code, you define one model with:
+
+- top-level state
+- derived reads
+- write methods
+- side-effect setup
+- optional events
+
+Then you create instances wherever they make sense: inside a component, in a shared module, or in plain TypeScript.
+
+Under the hood, each top-level state property is backed by its own Preact signal, while writes happen through actions with Immer-backed mutation semantics.
+
+## Why you would use it
+
+`preact-sigma` is a good fit when you want state and behavior to live together.
+
+It is especially useful when you need to:
+
+- keep state, derived values, mutations, and lifecycle in one place
+- create multiple instances of the same state model
+- expose readonly public state while keeping writes explicit
+- get fine-grained reactivity without wiring together a pile of loose signals
+- own timers, subscriptions, listeners, or nested setup with clear cleanup
+
+If a couple of plain signals are enough, use plain signals.  
+`preact-sigma` is for the point where state starts acting like a small system.
+
+## Install
 
 ```bash
 npm install preact-sigma
 ```
 
-## Smallest Useful Example
+## 30-second example
 
 ```ts
 import { SigmaType } from "preact-sigma";
 
-const Counter = new SigmaType<{ count: number }>("Counter")
+const Counter = new SigmaType<{ count: number }>()
   .defaultState({
     count: 0,
   })
@@ -40,44 +73,96 @@ console.log(counter.count); // 1
 console.log(counter.doubled); // 2
 ```
 
-## What It Is
+That example shows the basic shape:
+
+- state is public and reactive
+- derived values live in `computed(...)`
+- writes happen in `actions(...)`
+- an instance behaves like a small stateful object
+
+## The mental model
+
+A sigma model is made from a few simple pieces.
+
+### `defaultState(...)`
+
+Defines the top-level state for each instance.
+
+Each top-level property becomes a reactive public property on the instance.
+
+Use plain values for simple defaults, or zero-argument functions when each instance needs a fresh object or array.
+
+### `computed(...)`
+
+Use computeds for derived values that take no arguments.
+
+They behave like tracked getters:
+
+```ts
+.completedCount() // no
+todoList.completedCount // yes
+```
+
+### `queries(...)`
 
-At its core, `preact-sigma` lets you describe a stateful model as a constructor:
+Use queries for reactive reads that need arguments.
 
-- top-level state stays reactive through one signal per state property
-- computed values become tracked getters
-- queries become tracked methods, including queries with arguments
-- actions batch reads and writes through Immer drafts
-- setup handlers own side effects and cleanup
-- typed events let instances notify the outside world without exposing mutable internals
+```ts
+visibleTodos("open");
+```
+
+Queries are for reading, not writing.
 
-The result feels like a small stateful object from application code, while still behaving like signal-driven state from rendering code.
+### `actions(...)`
 
-## What You Can Do With It
+Actions are where state changes happen.
 
-`preact-sigma` is useful when you want state logic to live in one reusable unit instead of being split across loose signals, reducers, and effect cleanup code.
+Outside an action, public state is readonly. Inside an action, you write with normal mutation syntax and sigma handles the draft/update flow for you.
 
-With it, you can:
+```ts
+.actions({
+  rename(title: string) {
+    this.title = title;
+  },
+})
+```
 
-- model domain state as reusable constructors instead of one-off store objects
-- read public state directly while keeping writes inside typed action methods
-- derive reactive values with computed getters and parameterized queries
-- publish state changes from synchronous or async actions
-- observe committed state changes and optional Immer patches
-- snapshot committed top-level state and replace committed state for undo-like flows
-- manage timers, listeners, nested state setup, and teardown through explicit cleanup
-- use the same model inside Preact components with `useSigma(...)` and `useListener(...)`
+### `setup(...)`
 
-## Why This Shape Exists
+Setup is where side effects belong.
 
-This package exists to keep stateful logic cohesive without giving up signal-level reactivity.
+Use it for things like:
 
-It is a good fit when plain signals start to sprawl across modules, but heavier store abstractions feel too opaque or too tied to component structure. `preact-sigma` keeps the "model object" ergonomics of a class-like API, while preserving readonly public reads, explicit write boundaries, and explicit ownership of side effects.
+- timers
+- event listeners
+- subscriptions
+- nested model setup
+- storage sync
 
-## Big Picture Example
+Setup is explicit. A new instance does not automatically run setup. When setup does run, it returns one cleanup function that tears down everything that instance owns.
+
+### Events
+
+Use events when the model needs to notify the outside world without exposing mutable internals.
+
+Emit inside actions or setup:
 
 ```ts
-import { computed, SigmaType } from "preact-sigma";
+this.emit("saved", { count: 3 });
+```
+
+Listen from the outside:
+
+```ts
+const stop = instance.on("saved", ({ count }) => {
+  console.log(count);
+});
+```
+
+## A more realistic example
+
+```ts
+import { SigmaType } from "preact-sigma";
 
 type Todo = {
   id: string;
@@ -88,20 +173,18 @@ type Todo = {
 const TodoList = new SigmaType<
   { draft: string; todos: Todo[]; saving: boolean },
   { saved: { count: number } }
->("TodoList")
+>()
   .defaultState({
     draft: "",
     todos: [],
     saving: false,
   })
   .computed({
-    // Computeds are tracked getters with no arguments.
     remainingCount() {
       return this.todos.filter((todo) => !todo.done).length;
     },
   })
   .queries({
-    // Queries stay reactive at the call site and can accept arguments.
     visibleTodos(filter: "all" | "open" | "done") {
       return this.todos.filter((todo) => {
         if (filter === "open") return !todo.done;
@@ -111,7 +194,6 @@ const TodoList = new SigmaType<
     },
   })
   .actions({
-    // Public state is readonly, so writes live in actions.
     setDraft(draft: string) {
       this.draft = draft;
     },
@@ -123,6 +205,7 @@ const TodoList = new SigmaType<
         title: this.draft,
         done: false,
       });
+
       this.draft = "";
     },
     toggleTodo(id: string) {
@@ -131,20 +214,19 @@ const TodoList = new SigmaType<
     },
     async save() {
       this.saving = true;
-      this.commit(); // Publish the loading state before awaiting.
+      this.commit(); // publish "saving" before awaiting
 
       await fetch("/api/todos", {
         method: "POST",
         body: JSON.stringify(this.todos),
       });
 
       this.saving = false;
-      this.commit(); // Publish post-await writes explicitly.
+      this.commit(); // publish before emitting
       this.emit("saved", { count: this.todos.length });
     },
   })
   .setup(function (storageKey: string) {
-    // Setup is explicit and returns cleanup resources.
     const interval = window.setInterval(() => {
       localStorage.setItem(storageKey, JSON.stringify(this.todos));
     }, 1000);
@@ -153,44 +235,93 @@ const TodoList = new SigmaType<
   });
 
 const todoList = new TodoList();
-
-// setup(...) returns one cleanup function for everything this instance owns.
 const cleanup = todoList.setup("todos-demo");
 
-// Queries are reactive where they are read.
-const firstOpenTitle = computed(() => {
-  return todoList.visibleTodos("open")[0]?.title ?? "Nothing open";
-});
-
-// Events are typed and unsubscribe cleanly.
 const stop = todoList.on("saved", ({ count }) => {
   console.log(`Saved ${count} todos`);
 });
 
-todoList.setDraft("Write the README");
+todoList.setDraft("Rewrite the README");
 todoList.addTodo();
-await todoList.save();
 
 console.log(todoList.remainingCount);
-console.log(firstOpenTitle.value);
+console.log(todoList.visibleTodos("open"));
+
+await todoList.save();
 
 stop();
 cleanup();
 ```
 
-In Preact, the same constructor can be used with `useSigma(() => new TodoList(), ["todos-demo"])` so the component owns one instance and `setup(...)` cleanup runs automatically. Use `useListener(...)` when you want component-scoped event subscriptions with automatic teardown.
+## The one rule to remember about actions
+
+For normal synchronous actions, mutate state and return. You usually do **not** need `this.commit()`.
+
+Use `this.commit()` when you have unpublished changes and the action is about to cross a boundary like:
+
+- `await`
+- `emit(...)`
+- another action boundary that should not keep using the current draft
+
+In practice, that means:
+
+- sync action with no boundary: mutate and return
+- async action before `await`: `commit()` if you want those changes published first
+- action before `emit(...)`: `commit()` if there are pending changes
+
+That rule is the main thing to learn beyond the basic API.
+
+## In Preact
+
+`preact-sigma` works outside components, but it also has a nice component story.
+
+Use `useSigma(...)` when the component should own one instance:
+
+```ts
+import { useSigma } from "preact-sigma";
+
+const todoList = useSigma(() => new TodoList(), ["todos-demo"]);
+```
+
+If the model defines setup handlers, `useSigma(...)` runs setup for that component-owned instance and cleans it up automatically when setup params change or the component unmounts.
+
+Use `useListener(...)` for component-scoped event subscriptions:
+
+```ts
+import { useListener } from "preact-sigma";
+
+useListener(todoList, "saved", ({ count }) => {
+  console.log(`Saved ${count} todos`);
+});
+```
+
+## What you get out of the box
+
+Beyond the core model API, `preact-sigma` also includes:
+
+- `observe(...)` for reacting to committed state changes
+- optional Immer patch delivery in observers
+- `snapshot(...)` and `replaceState(...)` for restore/undo-like flows
+- `get(key)` when you need direct signal access for a state key or computed
+
+## Why this shape exists
+
+`preact-sigma` exists for the space between two extremes:
 
-Cleanup resources can be returned as functions, `AbortController`, objects with `dispose()`, or objects with `Symbol.dispose`.
+- **too small for a big store abstraction**
+- **too stateful for a handful of loose signals**
 
-Inside setup, `this` exposes the public instance plus `emit(...)` and `act(fn)`. Use `this.act(function () { ... })` when setup needs one synchronous anonymous action with normal draft, `commit()`, and `emit(...)` semantics, whether that work happens immediately in the setup body or later from a setup-owned callback, but should not become a public action method.
+It keeps the ergonomics of working with a model object, while preserving:
 
-## Constructor and Defaults
+- readonly public reads
+- explicit write boundaries
+- fine-grained reactivity
+- explicit ownership of side effects
 
-- `defaultState` values may be plain values or zero-argument initializer functions. Use initializer functions when each instance needs a fresh object, array, or class instance.
-- Constructor input shallowly overrides `defaultState`, so `new TodoList({ draft: "ready" })` replaces only the top-level keys you pass.
+That makes it useful for app state that has real behavior, not just values.
 
-## More Docs
+## More docs
 
-- [llms.txt](./llms.txt) provides the exhaustive machine-oriented API guide and terminology.
+- [`llms.txt`](./llms.txt) contains the exhaustive API and behavior reference.
 - Companion skills are available via `npx skills add alloc/preact-sigma`.
-- The `preact-sigma` skill packages the procedural guidance and agent-oriented workflow for this library.
+- The `preact-sigma` skill packages procedural guidance and agent-oriented workflow for the library.