legend-doctor 0.5.0 → 0.6.2

package/EXAMPLES.md

@@ -5,7 +5,8 @@ Use these examples after reading a finding. They show the shape of an edit, not
 - Apply `change` findings as written.
 - Inspect `candidate` findings first.
 - Preserve ownership, timing, mount identity, keys, cleanup, and atomic updates.
-- Check the installed Legend State version and types.
+- When a finding carries `edits`, apply those instead of retyping the example. See
+  [REPORT.md](REPORT.md#machine-applicable-edits).
 
 The snippets assume these imports when needed:
 
@@ -13,10 +14,11 @@ The snippets assume these imports when needed:
 import { batch, type Observable } from "@legendapp/state";
 import {
   Computed,
-  useMount,
+  For,
+  Show,
+  Switch,
   useObservable,
   useObserveEffect,
-  useUnmount,
   useValue,
 } from "@legendapp/state/react";
 import { $React } from "@legendapp/state/react-web";
@@ -41,11 +43,12 @@ const refresh = () => {
 
 ### Calculate derived values during render
 
-`delete-derived-state` removes the stale first render and the effect-driven second render.
+`delete-derived-state` removes the render that shows a stale value after an input changes and the effect-driven
+render that corrects it.
 
 ```tsx
 // Before
-const [total, setTotal] = useState(0);
+const [total, setTotal] = useState(price * quantity);
 useEffect(() => setTotal(price * quantity), [price, quantity]);
 
 // After
@@ -54,6 +57,9 @@ const total = price * quantity;
 
 If that was the effect's only work, `delete-effect` removes the empty effect too.
 
+When the initializer differs from the value the effect writes, such as `useState(0)`, the first commit shows the
+initializer. Calculating during render would change that first commit, so the finding is `keep-state`.
+
 ### Remove a React mirror
 
 `use-value` keeps the Legend value as the only owner.
@@ -202,15 +208,79 @@ const name = profile.name;
 const name = useValue(profile$.name);
 ```
 
+The finding needs a production write that changes another field under the subscribed parent without touching the
+read one. Otherwise nothing the narrow subscription skips ever changes, and the action abstains. That covers a parent
+passed in as a prop, a parent that is only replaced whole, and a field only ever written together with the read one.
+
+A single-property destructure such as `const { name } = useValue(profile$)` carries `edits` that produce
+`const name = useValue(profile$.name)`. Renaming reads of a whole-value binding stays prose.
+
+A map read at one key narrows the same way:
+
+```tsx
+// Before: a write to any area wakes this label
+const allAreas = useValue(areas$);
+return <span>{allAreas[areaId]?.name}</span>;
+
+// After: only areas$[areaId] can wake it
+const area = useValue(areas$[areaId]);
+return <span>{area?.name}</span>;
+```
+
+Every read must index the value with the same key, and the key must be fixed for the render: a literal, a prop or
+parameter, or a `const`. When that `const` comes after the subscription, the finding says to declare the narrowed
+subscription after it, which holds only when nothing in between reads the value, returns, or throws. The finding
+needs a production write that changes one entry without replacing the map, and no other subscription, observer
+read, dependency-free effect, ref or `peek()` render read, or subscribing parent that renders the owner on the same
+change.
+
 For a derived primitive, keep the comparison inside the selector:
 
 ```tsx
 const selected = useValue(() => selectedId$.get() === id);
 ```
 
+### Drop a subscription no render reads
+
+Use `peek-unrendered-use-value` when a `useValue` result feeds only a hook initial value or a synchronous event
+handler. The subscription reruns the component on every update for a value its output never shows.
+
+```tsx
+// Before: every play or pause renders the whole playlist
+const isPlaying = useValue(player$.isPlaying);
+const wasPlayingRef = useRef(isPlaying);
+const toggle = useCallback(() => setPlaying(!isPlaying), [isPlaying]);
+
+// After: reads take a snapshot when they run
+const wasPlayingRef = useRef(player$.isPlaying.peek());
+const toggle = useCallback(() => setPlaying(!player$.isPlaying.peek()), []);
+```
+
+The path must be seeded with plain data or a module constant of a literal, so dropping the subscription never
+delays a lazy `synced` or computed source. A persisted store is lazy: its first read starts the load, so it stays
+out of scope. The result may sit behind `!`, a type assertion, or `?? fallback`; each rewritten read keeps the
+fallback, which must be a literal or a module `const`. The action abstains when a render reads a ref, `peek()`,
+or an untracked `get()` that could depend on the forced rerender, and when a read is awaited, deferred, or captured
+by a callback that omits the value from its dependencies. A `path$.get()` directly inside the synchronous selector of
+`useValue`, `use$`, or `useSelector` is tracked by that hook and does not block it.
+
+Two more reads take a snapshot safely. A compare-and-set guard, `if (value !== next) path$.set(next)`, in an inline
+handler or a bare owner-level callback skips only writes Legend drops anyway, since `set` notifies nothing when the
+stored value is identical; `next` must be a literal or a local name, and the comparison must be the guard's last
+condition with no `else`. The initializer of an owner-level `const` that nothing references, and that assigns
+nothing, never reaches output, so its read becomes a `peek()` as well.
+
 ### Split unrelated leaves
 
-`split-use-value-leaves` gives each leaf its own field subscription.
+`split-use-value-leaves` gives each leaf its own field subscription. It requires an object-literal initial value
+that proves the field set, and a production write that changes an unread data field without touching a read one.
+When every field that changes is already read, or the only unread fields are constants and functions, the split
+removes no render and the action abstains.
+
+Both actions count writes by synchronous stretch, not by line. Writes in the same function body before an `await`,
+or inside one `batch` or array callback, land in one render, so an unread field written beside a read one proves
+nothing. A write after an `await`, or in a separate handler or listener, is its own stretch. Writes in the
+module body run while the module loads, before any importer renders, so they never count.
 
 ```tsx
 function Profile() {
@@ -267,7 +337,8 @@ separate subscriptions add overhead and are justified only when their combined r
 
 ### Remove selector work and legacy names
 
-Use `pass-observable-to-use-value` for a direct value and `replace-legacy-use-value` for old APIs.
+Use `pass-observable-to-use-value` for a direct value and `replace-legacy-use-value` for `use$` and `useSelector`,
+which Legend State deprecates in favor of `useValue` and plans to remove.
 
 ```tsx
 useValue(() => profile$.name.get()); // Before
@@ -277,6 +348,14 @@ useSelector(profile$.name); // Before
 useValue(profile$.name); // After
 ```
 
+The rename is `style`, since `useValue` is the same function, except for a `use$` call in a function the React Compiler
+compiles. The Compiler gives hook semantics only to callees named `/^use[A-Z0-9]/`, so it can cache the `use$` result
+and render a stale value; there the rename is `change`. `useSelector`, and an alias whose imported or local name passes
+that test, stay `style`. A function counts as compiled when the project's config enables the Compiler and its default
+`infer` mode compiles it: a component or hook by name that calls a hook or creates JSX, a `memo` or `forwardRef`
+callback, or a `"use memo"` function, with no `"use no memo"` directive and no ESLint suppression of a React hook rule.
+A function passed inline to `observer` is not compiled.
+
 The same-node synchronous selector rewrite without options is `style`: it selects the same value, with no proven
 render or lifecycle saving. Inside `observer`, direct input can use the enclosing observer's tracking instead of a
 separate selector hook. Async selectors and calls with options remain unchanged because their Promise or tracking
@@ -284,31 +363,60 @@ contracts can differ. An eager `useValue(profile$.name.get())` is still `change`
 an ordinary component or avoids redundant selector hooks inside `observer`. Keep `useValue(() => ...)` when the
 selector derives a value from one or more observables, including boolean projections and formatted computed values.
 
-### Compute a derived primitive as an observable
+Both actions carry `edits`. A legacy migration renames every legacy call in the file and removes the legacy import
+specifiers together, so each of those findings carries the same file-wide edit set.
+
+### Select a derived primitive
 
-Use `derive-computed-observable` when every `useMemo` dependency is a `useValue` subscription read nowhere else and
-every result is a primitive.
+This is a manual pattern; no action reports it on its own. When a `useMemo` derives a primitive from observable reads
+that nothing else in the component reads, select the primitive instead.
 
 ```tsx
-// Before: any change to either field renders Header
-const selectedView = useValue(library$.selectedView);
-const selectedPlaylistId = useValue(library$.selectedPlaylistId);
-const title = useMemo(
-  () => (selectedView === "playlist" ? `playlist-${selectedPlaylistId}` : "Library"),
-  [selectedView, selectedPlaylistId],
+// Before: every write under habits$.streaks renders the component
+const streaks = useValue(habits$.streaks);
+const longest = useMemo(
+  () => Math.max(0, ...Object.values(streaks).map((s) => s.longest)),
+  [streaks],
 );
 
-// After: the computed tracks both fields; Header renders only when the title string changes
-const title$ = useObservable(() =>
-  library$.selectedView.get() === "playlist"
-    ? `playlist-${library$.selectedPlaylistId.get()}`
-    : "Library",
+// After: the selector reruns on each render, and a write renders only when the number changes
+const longest = useValue(() =>
+  Math.max(0, ...Object.values(habits$.streaks.get()).map((s) => s.longest)),
 );
-const title = useValue(title$);
 ```
 
-Keep the memo when it mixes props or component-local helpers with observable inputs, or when it returns an object or
-array: a selector would recompute on every render, and a reference result renders on every input change either way.
+Keep the memo when an input is also read elsewhere in the component, since that read renders on every write anyway,
+or when the result is an object or array, since `useValue` compares by reference and a new result always renders.
+`snapshot-mutated-use-value` recommends this rewrite when an in-place write leaves such a memo stale.
+
+### Select fields instead of a new object
+
+`select-stable-selector-result` asks about a selector that builds a new object or array on every run.
+
+```tsx
+// Before: every viewport$.width change renders, even while `wide` stays false
+const layout = useValue(() => ({
+  label: viewport$.label.get(),
+  wide: viewport$.width.get() > 800,
+}));
+
+// After: a width change renders only when `wide` flips
+const label = useValue(viewport$.label);
+const wide = useValue(() => viewport$.width.get() > 800);
+```
+
+`useValue` reruns its selector on each change to an observable the selector read and renders when the result `!==`
+the result of the last render; Legend State offers no shallow or custom equality option. A new literal never equals
+the last one, so the component renders on every tracked change. That costs a render only when a change can leave the
+contents equal: a field built from raw reads (`{ width: viewport$.width.get() }`) changes on every write anyway, and
+the rule stays silent.
+
+Every finding is a `candidate`, since only the app knows whether such changes happen. It is reported for a literal
+result when a tracked path reaches it only through comparisons, negations, conditions, or `typeof`, and that path's
+declared domain, when known, holds objects or three or more values; and for `filter`, `map`, `flatMap`, `Object.keys`,
+`Object.values`, or `Object.entries` of a tracked read, where you can select the primitives the render needs or render
+the items with `<For each={items$}>`. A selector that returns a fresh value on only some paths, passes options, reads
+no proven observable, or shares its path with another subscription in the owner stays silent.
 
 ### Update one host prop
 
@@ -383,9 +491,15 @@ batch(() => {
 
 This preserves an atomic transition: subscribers see one completed update.
 
+React already commits writes from one synchronous stretch in one render, so neither action saves a React render. Both
+appear only when one non-React tracker in the same file reads two or more of the written paths: an `observe`,
+`useObserve`, `useObserveEffect`, or `useComputed` body, or an `onChange` listener on a shared parent. Separate writes
+rerun that tracker once per write, on torn state in between. `syncObservable` persistence queues changes until a
+microtask, so it saves them together either way.
+
 ### Preserve a conditional child's mount behavior
 
-Keep the observable at the owner. Put the condition in a stable leaf.
+Keep the observable at the owner. Let `Show` hold the condition.
 
 ```tsx
 function Page() {
@@ -394,17 +508,26 @@ function Page() {
     <>
       <Canvas />
       <button onClick={() => open$.set(true)}>Open</button>
-      <PanelGate open$={open$} />
+      <Show if={open$}>{() => <Panel />}</Show>
     </>
   );
 }
-
-function PanelGate({ open$ }: { open$: Observable<boolean> }) {
-  return useValue(open$) ? <Panel /> : null;
-}
 ```
 
-`PanelGate` stays mounted. `Panel` keeps its original conditional mount.
+`Show` stays mounted as the only subscriber and calls its child function only while the condition holds, so
+`Panel` keeps its original conditional mount. It re-renders with the owner, so values the child captures stay
+current. `cond ? <A /> : <B />` becomes `<Show if={cond$} else={() => <B />}>{() => <A />}</Show>`, and a chain
+of `tab === "posts" ? ... : tab === "media" ? ... : ...` becomes `<Switch value={tab$}>` with one arm per value
+and a `default` arm. Both return the selected element from one position, so a branch keeps its state across
+toggles exactly when it did before. A finding uses this form only when it renders the same thing:
+
+- A `&&` condition must be boolean. A falsy `0` or `""` would render under `&&` but not under `Show`.
+- A value narrowed by the condition is not read in a branch, because `get()` would lose the narrowing.
+- The slot reads no other observable with `get()` and calls no hook, since `Show` tracks its child function.
+- A ternary sits directly in a host element or fragment, which never inspects its children.
+- `Switch` needs every value the state can hold to be a string literal outside `Object.prototype`.
+
+Otherwise the finding asks for an always-mounted wrapper component that evaluates the slot as written.
 
 ### Subscribe once per keyed row
 
@@ -421,6 +544,39 @@ rows.map((row) => <RowState key={row.id} id={row.id} selectedId$={selectedId$} /
 
 Index keys and state-controlled row mounts need review.
 
+### Render an observable list with For
+
+`render-list-with-for` changes a component whose only read of an observable array is a keyed map.
+
+```tsx
+// Before: a change to one todo renders Todos and every row
+const todos = useValue(todos$);
+return (
+  <ul>
+    {todos.map((todo) => (
+      <TodoRow key={todo.id} todo={todo} />
+    ))}
+  </ul>
+);
+
+// After: a change to one todo renders its row
+return (
+  <ul>
+    <For each={todos$}>
+      {(todo$) => {
+        const todo = todo$.get();
+        return <TodoRow todo={todo} />;
+      }}
+    </For>
+  </ul>
+);
+```
+
+`For` subscribes to the array shallowly and renders each row in its own observer, keyed by the item's `id`.
+Rows do not re-render with the component, so a row that captures a prop, state, or other render value would keep
+its first value; those maps, index keys, keys other than `item.id`, rows that read other observables, and maps
+inside a component that inspects its children stay unchanged.
+
 ## Keep command state out of renders
 
 ### Replace render-free state with a ref
@@ -445,24 +601,39 @@ const send = () => socketRef.current?.send("ping");
 
 ### Use a non-tracking snapshot
 
-`use-peek-for-snapshot` changes a proven command read.
+`use-peek-for-snapshot` marks a read that needs a snapshot, not a dependency. Handlers, effects, and `onChange`
+listeners run outside any tracker, where `get()` already reads without subscribing, so there the finding is style. It is
+a change only for a `useState` initializer inside an `observer` render, where `get()` would subscribe the component.
 
 ```tsx
 const save = () => persist(settings$.theme.get()); // Before
 const save = () => persist(settings$.theme.peek()); // After
 ```
 
-Render reads and reactive callbacks keep tracking reads.
+Render reads and reactive callbacks keep tracking reads. The finding's `edits` rename `get` to `peek`.
+
+A row `key` read with `get()` inside an `observer` render or a `Computed`, `Memo`, `Show`, or `For` child function
+is a `candidate`. The tracked read subscribes the parent to every row's key; `For` derives keys without tracking
+them. The two differ only when code rewrites a key in place, which remounts the row under `get()` and keeps it
+under `peek()`, so confirm no such write exists.
+
+```tsx
+<For each={todos$}>{(todo$) => <TodoRow key={todo$.id.get()} todo$={todo$} />}</For> // Before
+<For each={todos$}>{(todo$) => <TodoRow key={todo$.id.peek()} todo$={todo$} />}</For> // After
+```
 
 ## Track every render read
 
 Legend tracks a `get()` only inside a tracking context: `useValue`, `observer`, a reactive component's selector, or
-`observe`/`when`. These findings catch reads that fall outside one.
+`observe`/`when`. These findings catch reads that fall outside one, or whose change a memo hides. Legend State
+discourages render-time `get()` even inside `observer`; read rendered values through `useValue`.
 
 ### Subscribe to a render read
 
 `use-value-for-render-read` changes a `get()` that runs in a component's or custom hook's render, including
-synchronous `.map`-style callbacks, with nothing tracking it.
+synchronous `.map`-style callbacks, with nothing tracking it. When the package's Babel config lists
+`@legendapp/state/babel`, reads among the element children of `Computed`, `Memo`, and `Show` are tracked, because the
+plugin wraps those children in a function.
 
 ```tsx
 // Before: Counter renders the value once and never again
@@ -478,55 +649,73 @@ function Counter() {
 }
 ```
 
+The direct initializer form carries `edits`, including a `useValue` specifier beside an existing
+`@legendapp/state/react` import. It carries none after an early return, where the new hook would be conditional.
 A read inside a conditional, JSX, or iteration callback gets a hoisting instruction: add `const value =
-useValue(path$)` at the top of the owner and read the binding there. The rule stays silent for `observer` and
-`reactiveObserver` components, for paths a `useValue` in the same owner already covers (directly, through a selector,
-or through a `const` alias), for hook-argument snapshots such as `useState(x$.get())`, for `key` reads, and for
-`get(true)` or dynamically keyed paths.
+useValue(path$)` at the top of the owner and read the binding there. Inside `observer` and `reactiveObserver`
+components the read already tracks and `useValue(path$)` performs the same `get()`, so only the direct initializer
+form is reported, as `style` with the same edit. When the React Compiler compiles the component (declared, then
+wrapped as `observer(Counter)`) and the read's value reaches the rendered output, the Compiler memoizes the `get()` like
+any call and observer's re-render can reuse the stale result, so the read is a `change`, in JSX too. The rule stays silent for paths a `useValue` in the same owner
+already covers (directly, through a selector, or through a `const` alias), for hook-argument snapshots such as
+`useState(x$.get())`, for reads handed to a Legend input that tracks on its own (`Show if`, `For each`, a `Memo`
+child, a `$` prop, or `when`), for `key` reads, and for `get(true)` or dynamically keyed paths.
 
-### Pass the observable to a reactive input
+### Select a copy when a memo keys on a mutated value
 
-`pass-observable-to-reactive-input` changes a `get()` or `peek()` handed to an input that tracks on its own.
+`snapshot-mutated-use-value` changes a `useValue` whose raw result keys a `useMemo` while another write mutates that
+value in place.
 
 ```tsx
-<Show if={ready$.get()}>{() => <Panel />}</Show>; // Before
-<Show if={ready$}>{() => <Panel />}</Show>; // After
+// Elsewhere: library$.folders.push(folder), library$.folders[i].name.set(name), or counts$.assign({ b: 2 })
 
-<For each={items$.get()}>{(item$) => <Row item$={item$} />}</For>; // Before
-<For each={items$}>{(item$) => <Row item$={item$} />}</For>; // After
-
-<Memo>{name$.get()}</Memo>; // Before
-<Memo>{name$}</Memo>; // After
+const folders = useValue(library$.folders); // Before
+const folders = useValue(() => [...library$.folders.get()]); // After
+const visible = useMemo(() => folders.filter((folder) => !folder.deleted), [folders]); // Unchanged
+```
 
-<$React.input $value={name$.get()} />; // Before
-<$React.input $value={name$} />; // After
+Legend applies child writes, array mutators, `assign`, and `delete` to the object it already holds, so `useValue`
+rerenders the component with the same reference and the memo returns its previous result. A copy selected inside
+`useValue` gets a new reference on every tracked change. If the derivation is cheap, computing it without `useMemo`
+is equally correct. When that memo is the value's only reader and computes a primitive without side effects, the
+finding instead recommends [selecting the primitive](#select-a-derived-primitive) and deleting both the memo and the
+`useValue` binding.
 
-when(ready$.get(), start); // Before
-when(ready$, start); // After
-```
+The finding names each in-place write and fires only when the memo reads what the write changes: a membership write
+against any element read, a field write against a read of that field. It is a `change` when every other dependency
+keeps its identity across renders (module constants, refs, state setters, owned observables) and a `candidate` when
+another dependency could change in the same update and recompute the memo. Writes that replace the value with
+`set(next)`, writes to unread fields, `get(true)` reads, and bindings that are reassigned stay silent.
 
-Covered inputs: `Show if`/`ifReady`, `Switch value`, `For each`, `Memo` and `Computed` children, `$`-prefixed props
-on `$React`, native `$View`-style hosts and `reactive()` components, and the first argument of `observe`, `when`,
-`whenReady`, `useObserve`, `useObserveEffect`, `useWhen`, and `useWhenReady`. The snapshot is evaluated once in the
-parent's render, so the input only updates when the parent happens to re-render; `For` also calls `get()` on what it
-receives, so a raw array breaks it. `useValue(x$.get())` stays with `pass-observable-to-use-value`.
+In a function the React Compiler compiles, the Compiler memoizes by reference without a `useMemo`: a method chain on
+the raw value, or a call that receives it, whose result reaches the rendered output, such as
+`{folders.map((folder) => <Row folder={folder} />)}`, keeps its cached result after an in-place write. The same finding
+covers those calls; reads through a property such as `folders.length`, results that stay inside the render, and
+values handed to hooks stay silent, because the Compiler does not cache them on the raw reference.
 
-### Split a selector that only builds a literal
+### Re-render a Memo child that reads parent values
 
-`split-use-value-result` offers a `style` rewrite for a const destructured selector whose members are direct reads or inert expressions.
+`use-computed-for-parent-reads` changes a `<Memo>` whose child reads a value from its owner's render.
 
 ```tsx
-const { a, b } = useValue(() => ({ a: state$.a.get(), b: state$.b.get() })); // Before
-const a = useValue(state$.a); // After
-const b = useValue(state$.b);
+const offset = useValue(feed$.offset);
+const index = offset + position;
+
+<Memo>{() => <Fork at={index} forks={forks$.get()} />}</Memo>; // Before
+<Computed>{() => <Fork at={index} forks={forks$.get()} />}</Computed>; // After
 ```
 
-The aggregate object is fresh; its destructured values retain their own identities. This rewrite removes the result
-allocation and adds per-path subscriptions. It does not prove fewer owner renders, lower CPU cost, or less native
-work. Every observable read must remain represented, including reads in otherwise unused fields: they may invalidate
-ref-backed render snapshots. Omitted effects, duplicate properties, mutable declarations, results used whole, block
-bodies, async selectors, prototype-setting properties, reordered reads, spreads, defaults, rest elements, computed
-members, and calls stay as they are.
+`Memo` wraps `Computed` in `React.memo` with an equality check that ignores new children unless `scoped` is set, so
+the owner's renders never reach the child. The child tracks the observables it reads, but every value it captures
+from the owner stays at the Memo's first render. `Computed` re-renders with its parent and keeps the same tracking.
+
+It is a `change` when a captured value changes whenever the owner re-renders for it: a `useValue`, `use$`, or
+`useSelector` result, React state whose setter is used, a `useSyncExternalStore` result, or a value, callback, or
+local render helper computed from one. It is a `candidate` when the child reads only props, context or custom-hook
+results, or values computed from them, which may stay constant for the Memo's lifetime. Observables, including props
+the component's type declares `Observable`, refs, state setters, owned observables, module values, and callbacks
+memoized without changing dependencies keep their identity and stay silent, as do `scoped` Memos and values read
+only inside event handlers.
 
 ## Keep effect timing correct
 
@@ -548,6 +737,37 @@ const changeQuery = (next: string) => {
 
 Every query change must come through the proven event path.
 
+### Reset state when an input changes
+
+`reset-during-render` removes the stale commit an effect renders before it resets state for new props, params, or
+loaded data.
+
+```tsx
+// Before
+const [selected, setSelected] = useState(0);
+useEffect(() => setSelected(0), [query]);
+
+// After
+const [selected, setSelected] = useState(0);
+const [prevQuery, setPrevQuery] = useState(query);
+if (!Object.is(query, prevQuery)) {
+  setPrevQuery(query);
+  setSelected(0);
+}
+```
+
+The effect body must only set the owner's state from pure values, under at most one `if`, with no cleanup, and must
+not read the state it resets. The effect's mount write must be a no-op so the first commit stays the same: each value
+is the state's own initializer, or the `if` pins one input to literals, as in `kind === "a" || kind === "b"`, under
+each of which the initializer evaluates to the written value. An effect that replaces a placeholder after mount keeps
+its timing. The comparison settles only when each dependency keeps its identity while React reruns the owner. A state
+value, a module binding, a `length` or other primitive constant, a memo that returns only such values, or a component
+prop proves that, since React reruns a component after a render-phase update with the same props; a destructuring
+default must be a primitive or a module binding. A custom hook's parameter qualifies when its declared type is a
+string, number, bigint, boolean, literal, `null`, or `undefined`, which a pure caller recomputes to a value the
+`Object.is` guard finds equal, even `NaN`. Any other value the owner computes, such as a hook result, leaves a review
+that asks about it. A function, object, or array the owner rebuilds every render keeps the effect.
+
 ### React to an observable without rendering
 
 Use `use-observe-effect` when a `useValue` result exists only to run an external side effect.
@@ -561,21 +781,75 @@ useEffect(() => syncTheme(theme), [theme]);
 useObserveEffect(() => syncTheme(settings$.theme.get()));
 ```
 
-Keep the React effect when the same value also renders. Moving it could change post-commit timing.
+Keep the React effect when the same value also renders. Moving it could change post-commit timing. Keep it as well
+when every parent that renders the component subscribes to the same observable: the parent's render already reruns
+the component on each change, so dropping `useValue` saves nothing. When a parent might rerender it, through an
+ancestor subscription or a memoized child whose props may be stable, the finding is a review.
 
-### Express proven lifecycle intent
+The observer tracks every `get()` it runs synchronously, including reads before the first `await` of an async
+function it calls. A read of an observable that is not a dependency would become a new trigger, so the finding
+names it and tells you to `peek()` it instead:
 
-Use `use-mount` and `use-unmount` only when lifecycle timing is proven equivalent.
+```tsx
+// Before
+const isPlaying = useValue(player$.isPlaying);
+useEffect(() => {
+  if (!isPlaying && window$.isOpen.get()) closeWindow();
+}, [isPlaying]);
+
+// After
+useObserveEffect(() => {
+  if (!player$.isPlaying.get() && window$.isOpen.peek()) closeWindow();
+});
+```
+
+Reads after an unconditional `await` and reads inside timers or promise callbacks stay untracked, so they are left
+alone. The finding becomes a review when a read runs in a callback of unknown timing, or calls `get()` on a receiver
+that is not proven to be an observable.
+
+A function the effect calls runs inside the observer's pass too, and its reads cannot be peeked from the effect. A
+project function, local or imported, is followed up to its first unconditional `await`; if it reads an observable
+there, the finding becomes a review that names the call. So does any call whose code is not followed: an import from a
+module out of view, a method of an application object, a callback prop, a value a hook returns, or a function held in
+a variable. Globals, packages, React setters and refs, built-in methods of constants, and observable writes stay
+convertible.
 
 ```tsx
-useEffect(() => start(), []); // Before
-useMount(() => start()); // After
+// Stays a React effect: loadThread reads mail$.errorId before its first await, so an observer
+// would refetch every time a failed load records its error.
+useEffect(() => {
+  if (selectedId) void loadThread(selectedId);
+}, [selectedId]);
+```
+
+### Keep empty-dependency lifecycle effects
+
+Legend's `useMount(fn)` runs `useEffect(fn, [])` in production, and `useUnmount(fn)` is `useMount(() => fn)`. Rewriting
+an empty-dependency effect with either removes no render or lifecycle cost, so the effect is `keep-effect`. Legend
+State prefers `useMount` and `useUnmount` when writing new code; converting existing effects is optional.
+
+```tsx
+useEffect(() => {
+  preload();
+}, []);
 
-useEffect(() => () => stop(), []); // Before
-useUnmount(() => stop()); // After
+useEffect(() => () => clearTimeout(timer.current), []);
 ```
 
-Keep the React effect when Strict Mode replay, setup work, or cleanup ownership could change.
+The only difference is in development under Strict Mode: `useUnmount` skips the teardown of the simulated unmount. A
+cleanup-free `useMount` setup still runs twice there, as the React effect does.
+
+### Keep layout work before paint
+
+A `useLayoutEffect` finding reports `hook: "useEffect"`. The effect runs after DOM mutation and before paint, so it
+can only be deleted with its derived state, move its write into the event, wait on the state it writes, or stay
+`keep-effect`. `use-observe-effect`, Legend persistence, and lifecycle aliases would run its work after the first paint.
+
+```tsx
+useLayoutEffect(() => {
+  setHeight(ref.current?.offsetHeight ?? 0);
+}, [label]);
+```
 
 ### Persist an observable instead of writing storage
 
@@ -601,9 +875,7 @@ const filters$ = useObservable(
 `synced` and `syncObservable` come from `@legendapp/state/sync`; the plugin matching the storage the effect wrote comes
 from `@legendapp/state/persist-plugins/local-storage`. The finding stays a candidate because the storage key, the
 serialized shape, and any mount effect that hydrates the same key need a manual check. While the persisted state stays
-React, or a prop drives the write, the effect is `keep-effect`. When the installed `@legendapp/state` has no `sync`
-entry point, every such effect stays `keep-effect` and `capabilities.disabledRules` lists
-`browser-storage-persistence` with reason `sync-export-missing`.
+React, or a prop drives the write, the effect is `keep-effect`.
 
 ### Keep an effect while changing its storage
 
@@ -650,7 +922,7 @@ menu$.open.set((value) => !value); // Before
 menu$.open.toggle(); // After
 ```
 
-`toggle-observable` is a style finding. Check that the installed API supports `toggle()`.
+`toggle-observable` is a style finding.
 
 ## Own observables once
 
@@ -666,18 +938,6 @@ stability, or context. `useObservable` also deactivates the node it returns when
 node is the shared source. Nest one observable inside another only as an intentional link whose reads and writes
 forward to the source.
 
-### Snapshot an initial value instead of writing a computed
-
-```tsx
-const draft$ = useObservable(() => store$.user.name.get() || fallback); // Before
-const draft$ = useObservable(store$.user.name.peek() || fallback); // After
-draft$.set(event.target.value); // Unchanged
-```
-
-A function initializer with a tracked `get()` creates a computed observable, and a computed replaces any written
-value on its next recomputation. The finding fires only when the owner also writes the observable; an initializer
-that is never written stays a legitimate derivation, and a `linked` or `synced` body already declares its own setter.
-
 ## Final check
 
 Before finishing: