mvc-kit 2.12.0 → 2.12.2

package/src/ViewModel.md

@@ -0,0 +1,1111 @@
+# ViewModel
+
+The core building block for UI state management. A ViewModel holds state, exposes computed getters, tracks async operations, emits typed events, and provides a complete reactive interface for a single component.
+
+---
+
+## Role
+
+The ViewModel is the complete interface between a component and everything else. It encapsulates services, collections, subscriptions, async orchestration, and derived computations. The component never imports infrastructure — it reads state, reads getters, reads async status, and calls methods.
+
+```
+Component → ViewModel → Service / Collection / EventBus / Channel
+```
+
+One ViewModel per connected component. If a component needs two ViewModels, split it into two components.
+
+---
+
+## Generic Parameters
+
+```typescript
+class MyViewModel extends ViewModel<S, E = {}>
+```
+
+| Parameter | Purpose |
+|---|---|
+| `S extends object` | The state shape. Must be a plain object. |
+| `E extends Record<string, any>` | Optional typed event map for imperative events. Defaults to `{}` (no events). |
+
+---
+
+## Creating a ViewModel
+
+### Subclass and Define State
+
+```typescript
+interface State {
+  items: Item[];
+  search: string;
+  typeFilter: 'all' | 'office' | 'warehouse';
+}
+
+class LocationsViewModel extends ViewModel<State> {
+  // ...
+}
+```
+
+### Construction
+
+The constructor accepts the initial state object. State is frozen on construction.
+
+```typescript
+const vm = new LocationsViewModel({
+  items: [],
+  search: '',
+  typeFilter: 'all',
+});
+```
+
+State is always immutable — `Object.freeze` is applied on every state transition.
+
+---
+
+## Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `state` | `S` | Current frozen state object |
+| `disposed` | `boolean` | Whether `dispose()` has been called |
+| `initialized` | `boolean` | Whether `init()` has been called |
+| `disposeSignal` | `AbortSignal` | Lazily created; aborted on `dispose()` |
+| `events` | `EventBus<E>` | Lazily created typed event bus |
+| `async` | `AsyncMap<this>` | Proxy returning `TaskState` per async method |
+
+---
+
+## State Management
+
+### set(partial) — protected
+
+Merges partial state into current state. Produces a new frozen state object and notifies all subscribers (React re-renders).
+
+```typescript
+// Partial object
+this.set({ search: 'alice' });
+
+// Updater function — return a partial
+this.set(prev => ({ count: prev.count + 1 }));
+
+// Draft mode — mutate the draft, return nothing
+this.set(draft => { draft.count = draft.count + 1 });
+```
+
+When using the function form, the state is wrapped in a copy-on-write draft proxy (see [`produceDraft`](./produceDraft.md)). If the function returns an object, that object is used as the partial (existing updater behavior). If the function returns `void`, the draft mutations are collected and applied. Both styles can be used interchangeably — pick whichever reads better for the update at hand.
+
+Draft mode is especially useful for nested state updates:
+
+```typescript
+this.set(draft => { draft.filters.status = 'active' });
+// vs.
+this.set(prev => ({ filters: { ...prev.filters, status: 'active' } }));
+```
+
+Structural sharing is preserved — unchanged subtrees keep their original references. Arrays must be replaced via assignment (in-place `push`/`splice` is not detected).
+
+**Shallow equality check:** If no values actually changed by reference, `set()` is a no-op — no new state object, no notification, no re-render.
+
+```typescript
+// Given state { count: 0, name: 'test' }
+this.set({ count: 0 }); // no-op — value unchanged
+```
+
+**After dispose:** `set()` is a silent no-op. This is intentional — in-flight async callbacks that resolve after dispose can safely call `set()` without crashing.
+
+### State is Always Frozen
+
+Every state object is `Object.freeze`'d. Direct mutation throws:
+
+```typescript
+vm.state.search = 'test'; // TypeError: Cannot assign to read only property
+```
+
+---
+
+## Lifecycle
+
+### init()
+
+Initializes the ViewModel. Sets up auto-memoized getters, subscribable auto-tracking, method wrapping for async tracking, and calls `onInit()`. Idempotent — calling it multiple times has no effect. No-op if already disposed.
+
+```typescript
+vm.init();
+vm.init(); // no-op
+```
+
+Supports async initialization:
+
+```typescript
+class MyVM extends ViewModel<State> {
+  protected async onInit() {
+    const data = await this.service.getAll(this.disposeSignal);
+    this.collection.reset(data);
+  }
+}
+
+await vm.init();
+```
+
+When using `useLocal`, `init()` is called automatically after mount — you never call it manually in components.
+
+### Init Sequence
+
+When `init()` is called, the following happens in order:
+
+1. `_trackSubscribables()` — detects subscribable members and wires up auto-tracking
+2. `_installStateProxy()` — installs context-sensitive state getter for dependency tracking
+3. `_processMembers()` — memoizes getters and wraps methods for async tracking (delegates to shared `wrapAsyncMethods`)
+4. `onInit()` — user-defined initialization hook
+
+### dispose()
+
+Tears down the ViewModel:
+
+1. Sets `disposed` to `true`
+2. Tears down all subscribable and `subscribeTo` subscriptions
+3. Aborts `disposeSignal`
+4. Runs all `addCleanup()` callbacks (including async tracking cleanup)
+5. Disposes the event bus (if created)
+6. Calls `onDispose()`
+7. Clears all state listeners
+
+Idempotent — safe to call multiple times. `onDispose()` only runs once.
+
+### reset(newState?)
+
+Tears down the current lifecycle and re-initializes without unmounting the component. Accepts an optional new state; defaults to the original state passed to the constructor.
+
+```typescript
+// Reset to initial state
+vm.reset();
+
+// Reset with new state
+vm.reset({ userId: newId, data: null });
+```
+
+Reset performs the following in order:
+
+1. Aborts the current `disposeSignal` (nulls the AbortController — a fresh one is lazily created on next access)
+2. Tears down all subscriptions (subscribable + `subscribeTo`)
+3. Resets state to `newState` or `initialState`
+4. Clears all async tracking (states + snapshots), notifies async listeners
+5. Re-runs `_trackSubscribables()` (fresh subscriptions to subscribable members)
+6. Notifies state listeners (React re-renders with new state)
+7. Re-runs `onInit()`
+
+**After dispose:** `reset()` is a no-op.
+
+**Key detail:** The old `disposeSignal` is aborted, so any in-flight fetch using it will throw `AbortError` and be swallowed. The new `disposeSignal` (accessed after reset) is a fresh, unaborted signal.
+
+```typescript
+const oldSignal = vm.disposeSignal;
+vm.reset();
+oldSignal.aborted;        // true
+vm.disposeSignal.aborted; // false (new signal)
+```
+
+---
+
+## Lifecycle Hooks
+
+### onInit?(): void | Promise<void> — protected
+
+Called during `init()` after all internal setup is complete. This is where you kick off initial loads and set up imperative subscriptions.
+
+```typescript
+protected onInit() {
+  // Smart init: skip fetch if another ViewModel already loaded the data
+  if (this.collection.length === 0) this.load();
+}
+```
+
+Collection data is typically accessed via getters that read from collection members directly — auto-tracking handles reactivity without needing `subscribeTo()` + `set()`. See `BEST_PRACTICES.md` for the full pattern.
+
+Can be async — `init()` returns the promise so callers can `await` it.
+
+### onSet?(prev, next): void — protected
+
+Called after every successful `set()` with the previous and next state. Useful for side-effect logic that reacts to specific state transitions.
+
+```typescript
+protected onSet(prev: Readonly<State>, next: Readonly<State>) {
+  if (prev.search !== next.search) {
+    this.analytics.track('search', { query: next.search });
+  }
+}
+```
+
+Not called when `set()` is a no-op (values unchanged).
+
+### onDispose?(): void — protected
+
+Called once during `dispose()`, after the signal is aborted, cleanups have fired, and the event bus is disposed.
+
+```typescript
+protected onDispose() {
+  this.model?.dispose();
+}
+```
+
+---
+
+## Computed Getters (Auto-Memoized)
+
+TypeScript `get` accessors compute derived values from state and subscribable members. After `init()`, all subclass getters are automatically wrapped with a memoization layer that tracks dependencies and caches results.
+
+```typescript
+get filtered(): Item[] {
+  const { items, search, statusFilter } = this.state;
+  let result = items;
+  if (search) {
+    const q = search.toLowerCase();
+    result = result.filter(i => i.name.toLowerCase().includes(q));
+  }
+  if (statusFilter !== 'all') {
+    result = result.filter(i => i.status === statusFilter);
+  }
+  return result;
+}
+
+get total(): number {
+  return this.state.items.length;
+}
+
+get hasResults(): boolean {
+  return this.filtered.length > 0;
+}
+```
+
+### Dependency Tracking
+
+When a memoized getter executes, a proxy records which `this.state` properties are accessed. These become the getter's dependencies. The getter only recomputes when one of those specific properties changes — not on any state change.
+
+```typescript
+// This getter depends on state.search and state.statusFilter
+get filtered() {
+  const { search, statusFilter } = this.state;
+  // ...
+}
+
+// Changing state.loading does NOT invalidate `filtered`
+this.set({ loading: true }); // filtered returns cached value
+```
+
+### Subscribable Dependencies
+
+Getters can also depend on subscribable members (Collections, Channels, other ViewModels). The memoization system auto-detects subscribable instance properties and tracks their revisions.
+
+```typescript
+class MyVM extends ViewModel<State> {
+  collection = new UsersCollection();
+
+  get filtered(): User[] {
+    return this.collection.items.filter(u => u.name.includes(this.state.search));
+  }
+}
+```
+
+When `collection` notifies (e.g., after `reset()`), the getter's cache invalidates and it recomputes on next access.
+
+### Three-Tier Cache
+
+The memoization system uses a three-tier validation strategy:
+
+| Tier | Check | Cost | When |
+|---|---|---|---|
+| **Tier 1** | Global revision unchanged | 1 integer compare | No `set()` or subscribable notification since last access |
+| **Tier 2** | Revision changed but this getter's deps didn't | Check each dep by reference | Unrelated state or subscribable changed |
+| **Tier 3** | At least one dep changed | Full recompute with tracking | Actual dependency changed |
+
+This means:
+- Accessing the same getter multiple times in one render is effectively free (Tier 1).
+- Changing unrelated state properties doesn't recompute the getter (Tier 2).
+- Only actual dependency changes trigger recomputation (Tier 3).
+
+### Conditional Dependencies
+
+Dependencies are re-tracked on every recomputation. If a getter has conditional branches, its dependencies update based on which branch runs:
+
+```typescript
+get display(): string {
+  if (this.state.mode === 'compact') return this.state.title;
+  return `${this.state.title} — ${this.state.subtitle}`;
+}
+```
+
+In `compact` mode, changing `subtitle` does NOT invalidate the getter (it wasn't accessed). After switching to `full` mode, `subtitle` becomes a dependency and changes will trigger recomputation.
+
+### Getter Composition
+
+Getters can call other getters. Dependency tracking bubbles up correctly:
+
+```typescript
+get filtered(): Item[] { /* depends on state.search, state.statusFilter, collection */ }
+get hasResults(): boolean { return this.filtered.length > 0; } // inherits filtered's deps
+```
+
+When `state.search` changes, both `filtered` and `hasResults` recompute.
+
+### Getter Inheritance
+
+Getters from parent classes are memoized. If a subclass overrides a parent getter, only the most-derived version is wrapped.
+
+```typescript
+class BaseVM extends ViewModel<State> {
+  get isEmpty(): boolean { return this.state.items.length === 0; }
+}
+
+class DerivedVM extends BaseVM {
+  get filtered(): Item[] { /* ... */ }
+}
+// Both isEmpty and filtered are memoized
+```
+
+### Error Handling in Getters
+
+If a getter throws, the error propagates and the cache is NOT populated. The next access will recompute (and throw again if the underlying condition hasn't changed).
+
+```typescript
+get data(): Item {
+  if (!this.state.item) throw new Error('No item loaded');
+  return this.state.item;
+}
+```
+
+### After Dispose
+
+Getter access after dispose returns the last cached value without re-executing the getter body. This prevents errors from stale data access during cleanup.
+
+### Rules
+
+- **Never call `set()` inside a getter.** It creates an infinite loop. Dev mode detects this and logs an error (the `set()` call is blocked).
+- **Getters must be pure.** They read state and return a value. No side effects.
+- **Before `init()`**, getters work as plain (unmemoized) accessors.
+
+---
+
+## Subscribable Auto-Detection
+
+After `init()`, the ViewModel scans all own instance properties. Any property that has a `subscribe` method (duck-typed) is treated as a subscribable member and auto-tracked.
+
+```typescript
+class MyVM extends ViewModel<State> {
+  collection = singleton(UsersCollection);  // auto-tracked ✓
+  channel = singleton(ChatChannel);         // auto-tracked ✓
+  plainObject = { value: 42 };              // ignored (no subscribe method)
+}
+```
+
+When a subscribable member notifies:
+
+1. The ViewModel's internal revision counter increments
+2. Memoized getter caches that depend on that member invalidate
+3. A new state reference is forced (even though values are unchanged) so React's `useSyncExternalStore` detects the change
+4. State listeners fire, triggering a re-render
+
+If the member also has `subscribeAsync` (ViewModels and Resources), async state changes (loading/error transitions) also trigger getter invalidation. This means a parent ViewModel can have a getter like `get isChildLoading() { return this.childVM.async.loadData.loading; }` and it will update automatically.
+
+**EventBus does NOT have `subscribe`** — it won't be auto-tracked (by design). Use `subscribeTo` for explicit subscriptions.
+
+### Multiple Subscribable Members
+
+Each subscribable member is tracked independently. A getter that reads `collection1` but not `collection2` won't recompute when `collection2` changes.
+
+---
+
+## Async Tracking
+
+After `init()`, all subclass methods are automatically wrapped. When a method returns a Promise, the framework tracks its loading and error state.
+
+### How It Works
+
+```typescript
+async load() {
+  const data = await this.service.getAll(this.disposeSignal);
+  this.collection.reset(data);
+}
+```
+
+When `load()` is called:
+
+1. `vm.async.load` becomes `{ loading: true, error: null, errorCode: null }`
+2. Async listeners are notified (React re-renders)
+3. On resolve: `vm.async.load` becomes `{ loading: false, error: null, errorCode: null }`
+4. On reject: error is classified via `classifyError()` — `vm.async.load.error` gets the message, `errorCode` gets a discriminant code
+5. On `AbortError`: silently swallowed — not captured as an error, not re-thrown
+
+### TaskState
+
+Each tracked async method has a frozen `TaskState` snapshot:
+
+```typescript
+interface TaskState {
+  readonly loading: boolean;
+  readonly error: string | null;
+  readonly errorCode: AppError['code'] | null;
+  // errorCode: 'unauthorized' | 'forbidden' | 'not_found' | 'validation' |
+  //            'rate_limited' | 'server_error' | 'network' | 'timeout' |
+  //            'abort' | 'unknown' | null
+}
+```
+
+Default (before the method is ever called): `{ loading: false, error: null, errorCode: null }`.
+
+### Reading Async State
+
+```typescript
+const { loading, error, errorCode } = vm.async.load;
+```
+
+The `async` property is a Proxy. Accessing any key returns the `TaskState` for that method, or the default if the method hasn't been called.
+
+### Snapshot Reference Stability
+
+Each `TaskState` is a frozen object. The reference changes on every status update (loading start, loading end, error). This enables React's `useSyncExternalStore` to detect changes via reference comparison.
+
+### Concurrent Calls
+
+Loading state uses a counter. If the same method is called multiple times concurrently, `loading` stays `true` until ALL calls resolve:
+
+```typescript
+const p1 = vm.load(); // loading: true (count: 1)
+const p2 = vm.load(); // loading: true (count: 2)
+await p1;             // loading: true (count: 1)
+await p2;             // loading: false (count: 0)
+```
+
+### Error Clearing
+
+When a method is retried after failure, `error` and `errorCode` are cleared at the start of the new call:
+
+```typescript
+await vm.load().catch(() => {});
+vm.async.load.error; // 'something went wrong'
+
+vm.load(); // immediately: { loading: true, error: null, errorCode: null }
+```
+
+### Return Value Preservation
+
+Wrapped methods preserve their return values:
+
+```typescript
+async fetchData(): Promise<string> {
+  return 'data';
+}
+
+const result = await vm.fetchData(); // 'data'
+```
+
+Errors are re-thrown (except AbortError) so standard Promise rejection behavior is preserved:
+
+```typescript
+await expect(vm.failingMethod()).rejects.toThrow('something went wrong');
+```
+
+### AbortError Handling
+
+AbortErrors are special-cased **at the method wrapper level**:
+- **Not captured** as an error in `TaskState` (error stays `null`)
+- **Not re-thrown** by the wrapper (the outer promise resolves to `undefined`)
+- **Loading counter decremented** normally
+
+This means navigating away from a component (which aborts in-flight fetches via `disposeSignal`) produces no error state and no unhandled rejections.
+
+**For methods without try/catch**, this is all you need — write the happy path and AbortErrors are fully automatic.
+
+**For methods with explicit try/catch**, your catch block **does** receive AbortErrors. The wrapper intercepts at the outer promise level (after your method's promise settles), not inside your function body. Use `isAbortError()` in the catch block to guard side effects that shouldn't run on abort — particularly rollback functions and other operations on shared state like Collections. `set()` and `emit()` are already no-ops after dispose and don't need guarding.
+
+```typescript
+// No try/catch — AbortError is fully automatic:
+async load() {
+  const data = await this.service.getAll(this.disposeSignal);
+  this.collection.reset(data);
+}
+
+// Explicit try/catch with shared-state side effects — guard needed:
+async delete(id: string) {
+  const rollback = this.collection.optimistic(() => {
+    this.collection.remove(id);
+  });
+  try {
+    await this.service.delete(id, this.disposeSignal);
+  } catch (e) {
+    if (!isAbortError(e)) rollback(); // don't roll back on abort
+    throw e;
+  }
+}
+```
+
+### Sync Method Pruning
+
+Methods that return synchronous values on first call are **auto-pruned** from async tracking. The wrapper detects the non-thenable return, removes the method from async maps, and replaces itself with a direct `bind` of the original — zero overhead on subsequent calls.
+
+```typescript
+syncMethod(): number {
+  return 42;
+}
+
+vm.syncMethod(); // first call: detected as sync, pruned
+vm.syncMethod(); // subsequent calls: direct bound call, no wrapping overhead
+```
+
+### What Gets Wrapped
+
+All methods on the subclass prototype chain (up to but not including `ViewModel.prototype`) are wrapped, **except**:
+
+- Getters and setters (managed by memoization)
+- `_`-prefixed methods (private convention)
+- Lifecycle hooks: `onInit`, `onSet`, `onDispose`
+- `constructor`
+
+### subscribeAsync(listener)
+
+Subscribes to async state changes. Returns an unsubscribe function. Used internally by `useInstance` to trigger React re-renders when async status changes.
+
+```typescript
+const unsub = vm.subscribeAsync(() => {
+  // any async method's TaskState changed
+});
+```
+
+Returns a no-op unsubscribe if called after dispose.
+
+---
+
+## Async Tracking Does NOT Invalidate Getters
+
+Async state notifications (`_notifyAsync`) are separate from state notifications. They do NOT bump the revision counter. This means:
+
+- Getter caches are NOT invalidated when async status changes
+- Only `set()` calls and subscribable member notifications invalidate getters
+- This prevents unnecessary recomputation of derived state when only loading/error status changes
+
+---
+
+## Events
+
+ViewModels support typed imperative events via the second generic parameter. Events are for one-shot signals that don't belong in state: toast notifications, navigation redirects, scroll-to-error, shake animations.
+
+### Defining Events
+
+```typescript
+interface Events {
+  saved: { id: string };
+  deleted: { id: string };
+  validationFailed: void;
+}
+
+class ItemViewModel extends ViewModel<State, Events> {
+  async save() {
+    const result = await this.service.save(this.state.draft, this.disposeSignal);
+    this.emit('saved', { id: result.id });
+  }
+}
+```
+
+### emit(event, payload) — protected
+
+Dispatches a typed event. Only the ViewModel can emit — components cannot.
+
+```typescript
+this.emit('saved', { id: result.id });
+```
+
+**After dispose:** `emit()` is a no-op (after the event bus is disposed). However, cleanup callbacks registered via `addCleanup()` run before the event bus is disposed, so they can still emit:
+
+```typescript
+class MyVM extends ViewModel<State, Events> {
+  setup() {
+    this.addCleanup(() => {
+      this.emit('saved', { id: 'final' }); // works — bus not yet disposed
+    });
+  }
+}
+```
+
+### events
+
+Lazily-created `EventBus<E>`. Zero cost if the ViewModel never emits. Auto-disposed with the ViewModel.
+
+```typescript
+vm.events.on('saved', ({ id }) => {
+  toast.success(`Saved ${id}`);
+});
+```
+
+### Lazy Allocation
+
+If the `events` getter is never accessed and `emit()` is never called, no EventBus is allocated. This keeps non-eventing ViewModels zero-cost.
+
+---
+
+## Subscriptions
+
+### subscribe(listener)
+
+Subscribes to state changes. Returns an unsubscribe function. Listeners receive `(nextState, prevState)`.
+
+```typescript
+const unsub = vm.subscribe((next, prev) => {
+  console.log(`count: ${prev.count} → ${next.count}`);
+});
+```
+
+Returns a no-op unsubscribe if called after dispose.
+
+Used internally by `useInstance` / `useSyncExternalStore` for React integration.
+
+### subscribeTo(source, listener) — protected
+
+Subscribes to any `Subscribable` source (Collection, ViewModel, Channel) with automatic cleanup on dispose. Returns an unsubscribe function for manual early cleanup.
+
+Use `subscribeTo()` for **imperative reactions** (side effects on change). For deriving values from collections, use getters instead — auto-tracking handles reactivity automatically.
+
+```typescript
+protected onInit() {
+  // Imperative reaction: play a sound when messages arrive
+  this.subscribeTo(this.messagesCollection, () => {
+    this.playNotificationSound();
+  });
+}
+```
+
+### listenTo(source, event, handler) — protected
+
+Subscribes to a typed event on a Channel or EventBus with automatic cleanup on dispose and reset. The event counterpart to `subscribeTo`.
+
+```typescript
+protected onInit() {
+  this.listenTo(this.channel, 'message', (msg) => {
+    this.set({ messages: [...this.state.messages, msg] });
+  });
+
+  this.listenTo(this.bus, 'auth:logout', () => {
+    this.set({ messages: [] });
+  });
+}
+```
+
+Returns an unsubscribe function for manual early cleanup. Stored in `_subscriptionCleanups` — torn down on both `dispose()` and `reset()`, then re-established when `onInit()` re-runs.
+
+### pipeChannel(channel, type, target) — protected
+
+Bridges a Channel event directly into a Collection via `upsert`. Calls `channel.init()` (idempotent) and registers the listener with auto-cleanup on dispose and reset.
+
+```typescript
+protected onInit() {
+  this.pipeChannel(this.channel, 'data', this.collection);
+
+  if (this.appState.state.online) {
+    this.channel.connect();
+  }
+}
+```
+
+Equivalent to:
+
+```typescript
+this.channel.init();
+this.listenTo(this.channel, 'data', (payload) => {
+  this.collection.upsert(payload);
+});
+```
+
+Use `pipeChannel` when every message should be upserted as-is. If you need to transform, filter, or route messages to different targets, use `listenTo` directly.
+
+Returns an unsubscribe function, consistent with `subscribeTo` and `listenTo`.
+
+### addCleanup(fn) — protected
+
+Registers a cleanup function that runs on dispose. Use this for teardown that isn't covered by `subscribeTo` or `listenTo` (e.g., timers, intervals).
+
+```typescript
+protected onInit() {
+  const id = setInterval(() => this.poll(), 5000);
+  this.addCleanup(() => clearInterval(id));
+}
+```
+
+---
+
+## disposeSignal
+
+A lazily-created `AbortSignal` that aborts when the ViewModel is disposed. Pass it to `fetch()` or any async API that accepts a signal.
+
+```typescript
+async load() {
+  const data = await this.service.getAll(this.disposeSignal);
+  this.collection.reset(data);
+}
+```
+
+- **Lazy** — zero cost if never accessed. No AbortController allocated unless you read `disposeSignal`.
+- **Stable** — returns the same signal on every access.
+- **Aborted before `onDispose()` runs** — cleanup code can check it.
+
+For per-call cancellation, compose signals:
+
+```typescript
+async loadRoom(roomId: string, callSignal: AbortSignal) {
+  const res = await fetch(`/api/rooms/${roomId}`, {
+    signal: AbortSignal.any([this.disposeSignal, callSignal]),
+  });
+  this.set({ messages: await res.json() });
+}
+```
+
+---
+
+## Reserved Keys
+
+The following property names are reserved and cannot be overridden by subclasses:
+
+- `async` — used by the async tracking proxy
+- `subscribeAsync` — used by async state subscription
+
+Attempting to define these as methods, getters, or class fields throws:
+
+```
+[mvc-kit] "async" is a reserved property on ViewModel and cannot be overridden.
+```
+
+The check runs in the constructor (prototype scan) and during `init()` (instance property scan).
+
+---
+
+## Dev Mode
+
+When `__MVC_KIT_DEV__` is enabled, additional safety checks activate:
+
+### set() inside a getter
+
+Detects and blocks `set()` calls during getter evaluation. Logs an error and prevents the state mutation:
+
+```
+[mvc-kit] set() called inside a getter. Getters must be pure — they read state
+and return a value. They must never call set(), which would cause an infinite
+render loop. Move this logic to an action method.
+```
+
+### Method call after dispose
+
+Wrapped methods log a warning and return `undefined`:
+
+```
+[mvc-kit] "load" called after dispose — ignored.
+```
+
+### Method call before init
+
+Wrapped methods log a warning (but still execute):
+
+```
+[mvc-kit] "load" called before init(). Async tracking is active only after init().
+```
+
+### Ghost async operations
+
+When a ViewModel is disposed with pending async calls, a delayed warning fires after `GHOST_TIMEOUT` (default 3000ms):
+
+```
+[mvc-kit] Ghost async operation detected: "load" had 1 pending call(s)
+when the ViewModel was disposed. Consider using disposeSignal to cancel
+in-flight work.
+```
+
+Override `static GHOST_TIMEOUT` on your subclass to change the delay:
+
+```typescript
+class MyVM extends ViewModel<State> {
+  static override GHOST_TIMEOUT = 5000;
+}
+```
+
+### static DEFAULT_STATE
+
+Declare `static DEFAULT_STATE` on singleton ViewModels so `singleton()` and `useSingleton()` can be called without constructor arguments. The value is used as the initial state when no args are passed:
+
+```typescript
+class AuthViewModel extends ViewModel<AuthState> {
+  static DEFAULT_STATE: AuthState = { user: null, isAuthenticated: false };
+}
+
+// No args needed — DEFAULT_STATE is used automatically
+private auth = singleton(AuthViewModel);
+const [state, vm] = useSingleton(AuthViewModel);
+```
+
+---
+
+## React Integration
+
+### useLocal
+
+Creates a component-scoped ViewModel, auto-initialized and auto-disposed.
+
+```tsx
+function LocationsPage() {
+  const [state, vm] = useLocal(LocationsViewModel, {
+    items: [],
+    search: '',
+    typeFilter: 'all',
+  });
+  const { loading, error } = vm.async.load;
+
+  return (
+    <div>
+      <input value={state.search} onChange={e => vm.setSearch(e.target.value)} />
+      {loading && <Spinner />}
+      {error && <ErrorBanner message={error} />}
+      <LocationsTable locations={vm.filtered} />
+    </div>
+  );
+}
+```
+
+**With deps:** Dispose and recreate when dependencies change.
+
+```tsx
+const [state, vm] = useLocal(LocationsViewModel, { userId, data: null }, [userId]);
+```
+
+**Factory overload:**
+
+```tsx
+const [state, vm] = useLocal(() => new ChatViewModel(roomId), [roomId]);
+```
+
+### useEvent
+
+Subscribes to ViewModel events.
+
+```tsx
+useEvent(vm, 'saved', ({ id }) => {
+  toast.success(`Saved ${id}`);
+});
+```
+
+### How Re-renders Work
+
+`useLocal` uses `useSyncExternalStore` internally via two subscriptions:
+
+1. **Combined subscription** — a single `useSyncExternalStore` with a version counter. Both `subscribe` and `subscribeAsync` (if present) increment the counter to trigger re-renders. `subscribable.state` is read directly in the render body.
+
+This means components re-render when:
+- State changes via `set()`
+- A subscribable member notifies (Collection reset, Channel status change)
+- An async method starts, completes, or fails
+
+---
+
+## Inheritance
+
+### Getters
+
+Getters from all levels of the class hierarchy are memoized. Most-derived wins:
+
+```typescript
+class ParentVM extends ViewModel<State> {
+  get label(): string { return 'parent'; }
+}
+
+class ChildVM extends ParentVM {
+  override get label(): string { return this.state.name; } // this version is memoized
+}
+```
+
+### Methods
+
+Methods from all levels are wrapped for async tracking. Most-derived wins:
+
+```typescript
+class ParentVM extends ViewModel<State> {
+  async load(): Promise<string> { return 'parent'; }
+}
+
+class ChildVM extends ParentVM {
+  async load(): Promise<string> { return 'child'; } // this version is tracked
+}
+```
+
+### Multiple Instances
+
+Two instances of the same ViewModel class have completely independent state, caches, and async tracking. They do not share anything.
+
+---
+
+## Section Order Convention
+
+Organize every ViewModel consistently for scannability:
+
+```typescript
+export class LocationsViewModel extends ViewModel<State, Events> {
+  // --- Private fields ---
+  private service = singleton(LocationService);
+  private collection = singleton(LocationsCollection);
+
+  // --- Computed getters ---
+  get filtered(): Item[] { /* ... */ }
+  get total(): number { /* ... */ }
+
+  // --- Lifecycle ---
+  protected onInit() { /* ... */ }
+
+  // --- Actions ---
+  async load() { /* ... */ }
+  async refresh() { /* ... */ }
+
+  // --- Setters ---
+  setSearch(search: string) { this.set({ search }); }
+  setTypeFilter(typeFilter: State['typeFilter']) { this.set({ typeFilter }); }
+}
+```
+
+**Private fields → Computed getters → Lifecycle → Actions → Setters.**
+
+---
+
+## Best Practices
+
+**State holds only source-of-truth values.** User inputs and data from the server. Never derived values (use getters), never loading/error flags (use `vm.async`).
+
+**Write the happy path for async methods.** No try/catch, no loading flags, no abort checks. The framework handles all of it.
+
+```typescript
+async load() {
+  const data = await this.service.getAll(this.disposeSignal);
+  this.collection.reset(data);
+}
+```
+
+**Pass `disposeSignal` to every async call.** Ensures in-flight requests cancel on unmount.
+
+**Use `subscribeTo` for Collection subscriptions.** It auto-cleans up on dispose. **Use `listenTo` for Channel/EventBus event subscriptions.** It auto-cleans up on both dispose and reset.
+
+**Check `collection.length > 0` in `onInit` before fetching.** Another ViewModel may have already loaded the data (smart init pattern).
+
+**Setters do one thing — update a single state value.** Derivation happens in getters, not in setters.
+
+```typescript
+setSearch(search: string) { this.set({ search }); }
+```
+
+**Methods are auto-bound.** All public methods are bound to the instance in the constructor, so they can be passed point-free as callbacks without losing `this` context. Both styles are equivalent:
+
+```tsx
+// Arrow wrapper (always worked)
+<SearchBox onChange={v => vm.setSearch(v)} />
+
+// Point-free (works because methods are auto-bound)
+<SearchBox onChange={vm.setSearch} />
+```
+
+**Re-throw errors in explicit try/catch blocks.** So async tracking still captures them. Use `isAbortError()` to guard side effects on shared state (like Collection rollbacks). `set()` and `emit()` don't need the guard — they're already no-ops after dispose:
+
+```typescript
+// Shared-state side effects — guard needed:
+catch (e) {
+  if (!isAbortError(e)) rollback();
+  throw e;
+}
+
+// Only set()/emit() — no guard needed (no-ops after dispose):
+catch (e) {
+  this.emit('error', { message: 'Failed' });
+  throw e;
+}
+```
+
+**Use `reset()` for form resets or route-param changes.** It tears down and re-initializes without unmounting the component.
+
+---
+
+## Anti-Patterns
+
+### Loading/error in state
+
+```typescript
+// Bad: async tracking handles this
+interface State {
+  loading: boolean;
+  error: string | null;
+}
+
+// Good: read from vm.async.load
+const { loading, error } = vm.async.load;
+```
+
+### Derived values in state
+
+```typescript
+// Bad: will desync
+this.set({ filtered: items.filter(...) });
+
+// Good: getter recomputes automatically
+get filtered() { return this.state.items.filter(...); }
+```
+
+### set() inside a getter
+
+```typescript
+// Bad: infinite loop (blocked in DEV mode)
+get broken() {
+  this.set({ count: 999 });
+  return 'bad';
+}
+```
+
+### Manual try/catch for standard loads
+
+```typescript
+// Bad: unnecessary boilerplate
+async load() {
+  this.set({ loading: true });
+  try {
+    const data = await this.service.getAll(this.disposeSignal);
+    this.set({ items: data, loading: false });
+  } catch (e) { /* ... */ }
+}
+
+// Good: write the happy path
+async load() {
+  const data = await this.service.getAll(this.disposeSignal);
+  this.collection.reset(data);
+}
+```
+
+### Swallowing errors without re-throwing
+
+```typescript
+// Bad: async tracking won't capture the error
+catch (e) {
+  this.emit('error', { message: 'Failed' });
+  // error swallowed — vm.async.save.error stays null
+}
+
+// Good: re-throw so tracking works
+catch (e) {
+  this.emit('error', { message: 'Failed' });
+  throw e;
+}
+```
+
+Note: `emit()` is a no-op after dispose, so no `isAbortError()` guard is needed here. Use `isAbortError()` only when the catch block has side effects on shared state (like rolling back optimistic updates on a singleton Collection).
+
+### Two ViewModels in one component
+
+```tsx
+// Bad: split into two components
+const [s1, vm1] = useLocal(UsersViewModel, { ... });
+const [s2, vm2] = useLocal(OnDutyViewModel, { ... });
+```
+
+### Fetching in useEffect
+
+```tsx
+// Bad: ViewModel handles its own initialization
+useEffect(() => { vm.load(); }, []);
+
+// Good: onInit() handles it automatically via useLocal
+```