docs: clarify act callback syntax

Author: aleclarson

README.md

@@ -159,14 +159,14 @@ In Preact, the same constructor can be used with `useSigma(() => new TodoList(),
 
 Cleanup resources can be returned as functions, `AbortController`, objects with `dispose()`, or objects with `Symbol.dispose`.
 
-Inside setup, `this` exposes the public instance plus `emit(...)` and `act(fn)`. Use `this.act(() => { ... })` when a setup-owned callback needs one synchronous anonymous action with normal draft, `commit()`, and `emit(...)` semantics, but should not become a public action method.
+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.
 
 ## Best Practices
 
 - Let `new SigmaType<TState, TEvents>()` and the builder inputs drive inference. Avoid forcing extra type arguments onto builder methods.
 - Keep top-level state properties meaningful. Each top-level property gets its own signal, so shape state around the reads you want to track.
 - Use `computed(...)` for argument-free derived state, and use queries for reactive reads that need parameters.
-- Put writes in actions. A draft boundary is any point where sigma cannot keep reusing the current draft. `emit()`, `await`, and any action call other than a same-instance sync nested action call are draft boundaries, so call `this.commit()` before those boundaries when pending writes should become public. Setup-owned callbacks can use `this.act(() => { ... })` to run one synchronous anonymous action without adding a public action method.
+- Put writes in actions. A draft boundary is any point where sigma cannot keep reusing the current draft. `emit()`, `await`, and any action call other than a same-instance sync nested action call are draft boundaries, so call `this.commit()` before those boundaries when pending writes should become public. Setup can use `this.act(function () { ... })` to run one synchronous anonymous action for initialization work or setup-owned callbacks without adding a public action method.
 - Use `snapshot(instance)` and `replaceState(instance, snapshot)` for committed-state replay. They work on top-level state keys and stay outside action semantics.
 - Use `SigmaRef<T>` when a value should stay by reference in sigma's `Draft` and `Immutable` types. A normal assignment to a `SigmaRef<T>`-typed value only changes typing and does not change Immer's runtime drafting or freezing behavior.
 - Use `immerable` on custom classes only when they should participate in Immer drafting. `setAutoFreeze(false)` disables sigma's runtime deep-freezing when you need published state to stay unfrozen.

llms.txt

@@ -8,7 +8,7 @@
 - `computed`: A tracked getter declared with `.computed({ ... })`.
 - `query`: A tracked method declared with `.queries({ ... })` or created with `query(fn)`.
 - `action`: A method declared with `.actions({ ... })` that reads and writes through one Immer draft for one synchronous call.
-- `setup act callback`: A synchronous function passed to `this.act(...)` inside setup to run one anonymous action.
+- `anonymous action`: A synchronous function passed to `this.act(...)` inside setup to run one anonymous action.
 - `draft boundary`: Any point where sigma cannot keep reusing the current draft.
 - `setup handler`: A function declared with `.setup(fn)` that returns an array of cleanup resources.
 - `cleanup resource`: A cleanup function, an `AbortController`, an object with `dispose()`, or an object with `[Symbol.dispose]()`.
@@ -292,7 +292,9 @@ Behavior:
 - the public `.setup(...)` method always returns one cleanup function
 - `this` inside a setup handler exposes the public instance plus `emit(...)` and `act(fn)`
 - `this.act(fn)` inside setup runs `fn` with normal action semantics without adding a public action method
-- `this.act(fn)` callbacks must stay synchronous
+- use `this.act(fn)` for setup-time initialization work or setup-owned callbacks that need action semantics
+- pass a normal `function () {}` to `this.act(...)` so callback `this` receives the action context
+- `this.act(fn)` functions must stay synchronous
 - each setup handler returns an array of cleanup resources
 - setup typing only exposes computeds, queries, and actions that were already present when that `.setup(...)` call happened