mvc-kit 2.13.0 → 2.13.1

package/BEST_PRACTICES.md

@@ -0,0 +1,1390 @@
+# mvc-kit Best Practices
+
+This guide prescribes how to build clean, testable, maintainable single-page applications with mvc-kit. It is opinionated by design. The patterns here eliminate boilerplate, push logic out of components, and produce applications where every class has one clear job.
+
+---
+
+## Guiding Principles
+
+**1. The ViewModel is the complete interface.**
+A component interacts with one ViewModel. That ViewModel exposes everything the component needs — state, computed properties, actions, events — and encapsulates everything the component doesn't need to know about: services, collections, subscriptions, async orchestration. The component never imports infrastructure.
+
+**2. Components are declarative.**
+Components read state, read getters, read async status, and call methods. They don't coordinate, derive, subscribe, or fetch. If you're writing logic in a component, it belongs in a ViewModel.
+
+**3. One ViewModel per component.**
+A connected component owns one ViewModel via `useLocal`. It may also use `useEvent` on that same ViewModel. If a component needs a second ViewModel, it should be split into two components.
+
+**4. Lifecycle drives initialization, not the component.**
+`onInit()` replaces `useEffect` for data loading and subscription setup. The ViewModel knows what it needs and when to get it. The component doesn't tell it.
+
+**5. State holds truth, getters derive the rest.**
+State contains only source-of-truth values — what the user typed, what the server returned. Derived values (filtered lists, counts, flags) are getters on the ViewModel. They can't desync because they compute from state on every access.
+
+**6. Async status is automatic.**
+Loading flags and error messages for async operations are tracked by the framework, not by you. Don't put `loading` or `error` in state — read them from `vm.async.methodName`.
+
+---
+
+## Class Roles
+
+| Question | Answer |
+|---|---|
+| Does it hold UI state, computed properties, and actions for a component? | **ViewModel** |
+| Does it represent a single entity with validation and dirty tracking? | **Model** |
+| Does it hold a list of entities with CRUD operations? | **Collection** |
+| Does it hold a list of entities and persist to browser/device storage? | **PersistentCollection** subclass |
+| Does it hold a list of entities AND load them from an API? | **Resource** |
+| Does it fetch data from an external source? | **Service** |
+| Does it broadcast events across unrelated parts of the app? | **EventBus** |
+| Does it manage a persistent external connection (WebSocket, SSE)? | **Channel** |
+| Does it coordinate multiple ViewModels in a single workflow? | **Controller** (rare) |
+| Does it wrap a third-party SDK or manage custom reactive state for a ViewModel? | **Trackable** subclass |
+
+If code doesn't fit any of these, it's a plain utility function. Not everything needs to be a class.
+
+---
+
+## The ViewModel
+
+The ViewModel is the core building block. Get this right and everything else follows.
+
+### State Design: Source of Truth Only
+
+State holds only the raw values: user inputs and data loaded from the server. Nothing derived. Nothing related to async status.
+
+```typescript
+// ✗ Bad: derived values, collection mirrors, and async status in state
+interface State {
+  search: string;
+  items: Item[];         // collection data — use a getter reading from collection
+  filtered: Item[];      // derived — use a getter
+  total: number;         // derived — use a getter
+  loading: boolean;      // async status — use vm.async
+  error: string | null;  // async status — use vm.async
+}
+
+// ✓ Good: only source-of-truth values (user inputs and filters)
+interface State {
+  search: string;
+  typeFilter: 'all' | 'office' | 'warehouse';
+}
+```
+
+Derived values live on the ViewModel as getters. Async status lives in `vm.async`. State stays lean.
+
+### Computed Getters
+
+TypeScript `get` accessors compute derived values from state. They can't desync because they read from `this.state` on every access and recompute during each render.
+
+```typescript
+export class LocationsViewModel extends ViewModel<State> {
+  collection = singleton(LocationsCollection);
+
+  get items(): LocationState[] {
+    return this.collection.items as LocationState[];
+  }
+
+  get filtered(): LocationState[] {
+    const { search, typeFilter } = this.state;
+    let result = this.items;
+
+    if (search) {
+      const q = search.toLowerCase();
+      result = result.filter(loc =>
+        loc.name.toLowerCase().includes(q) ||
+        loc.city.toLowerCase().includes(q)
+      );
+    }
+    if (typeFilter !== 'all') {
+      result = result.filter(loc => loc.type === typeFilter);
+    }
+    return result;
+  }
+
+  get total(): number {
+    return this.items.length;
+  }
+
+  get hasResults(): boolean {
+    return this.filtered.length > 0;
+  }
+
+  get isEmpty(): boolean {
+    return this.total > 0 && !this.hasResults;
+  }
+}
+```
+
+In the component, read `state.x` for raw values and `vm.x` for computed values:
+
+```tsx
+function LocationsPage() {
+  const [state, vm] = useLocal(LocationsViewModel, { /* ... */ });
+
+  return (
+    <div>
+      <input value={state.search} onChange={e => vm.setSearch(e.target.value)} />
+      <LocationsTable locations={vm.filtered} />
+      <p>Showing {vm.filtered.length} of {vm.total}</p>
+      {vm.isEmpty && <p>No results match your filters.</p>}
+    </div>
+  );
+}
+```
+
+**Important:** Never call `set()` inside a getter. It creates an infinite loop. Dev mode (`__MVC_KIT_DEV__`) detects this and logs a clear error.
+
+### One-Liner Setters
+
+With getters handling derivation, setters do one thing — update a single state value:
+
+```typescript
+setSearch(search: string) { this.set({ search }); }
+setTypeFilter(typeFilter: State['typeFilter']) { this.set({ typeFilter }); }
+setStatusFilter(statusFilter: State['statusFilter']) { this.set({ statusFilter }); }
+```
+
+The setter changes state, React re-renders, and getters compute the new result. There is no opportunity for desync.
+
+All classes auto-bind methods in the constructor, so they can be passed point-free as callbacks:
+
+```tsx
+// Both work — pick whichever you prefer
+<SearchBox onChange={vm.setSearch} />
+<SearchBox onChange={v => vm.setSearch(v)} />
+
+// Works on all classes, not just ViewModel
+<SortHeader onClick={sorting.toggle} />
+<button onClick={pagination.nextPage}>Next</button>
+<button onClick={model.commit}>Save</button>
+```
+
+### Encapsulating Collections
+
+Collections are the shared data cache. Getters on the ViewModel read directly from collection members — the auto-tracking system detects the subscribable dependency and handles reactivity automatically. Components never import or subscribe to a Collection.
+
+```typescript
+export class LocationsViewModel extends ViewModel<State> {
+  collection = singleton(LocationsCollection);
+  private service = singleton(LocationService);
+
+  // Getter reads from collection — auto-tracked, no subscribeTo needed
+  get items(): LocationState[] {
+    return this.collection.items as LocationState[];
+  }
+
+  get filtered(): LocationState[] {
+    const { search, typeFilter } = this.state;
+    let result = this.items;
+    if (search) {
+      result = result.filter(loc => loc.name.toLowerCase().includes(search.toLowerCase()));
+    }
+    if (typeFilter !== 'all') {
+      result = result.filter(loc => loc.type === typeFilter);
+    }
+    return result;
+  }
+
+  get total(): number {
+    return this.items.length;
+  }
+
+  protected onInit() {
+    // Smart init: skip fetch if another ViewModel already loaded the data
+    if (this.collection.length === 0) this.load();
+  }
+}
+```
+
+When a getter reads from a collection member, the memoization system auto-tracks it as a dependency. When the collection changes, the getter invalidates and recomputes. No `subscribeTo()` or `set()` wiring needed.
+
+ViewModels with no local state at all (e.g. a dashboard that only derives from collections) can omit the state type parameter entirely:
+
+```typescript
+export class DashboardViewModel extends ViewModel {
+  private usersCollection = singleton(UsersCollection);
+
+  get totalUsers(): number {
+    return this.usersCollection.length;
+  }
+
+  protected onInit() {
+    if (this.usersCollection.length === 0) this.load();
+  }
+}
+```
+
+#### When subscribeTo() is still needed
+
+`subscribeTo()` is not deprecated. It remains the right tool for **imperative reactions** — side effects that should fire when a collection changes:
+
+```typescript
+protected onInit() {
+  // Play a sound when new messages arrive
+  this.subscribeTo(this.messagesCollection, () => {
+    this.playNotificationSound();
+  });
+}
+```
+
+Use getters for deriving values from collections. Use `subscribeTo()` for imperative side effects.
+
+### Async Methods
+
+After `init()`, mvc-kit automatically tracks loading and error state for every async method. You write the happy path. The framework handles the rest.
+
+```typescript
+async load() {
+  const data = await this.service.getAll(this.disposeSignal);
+  this.collection.reset(data);
+}
+```
+
+That's the entire method. No `try/catch`. No `this.set({ loading: true })`. No `this.set({ error: ... })`. No AbortError check. No dispose guard.
+
+Here's what happens automatically:
+
+- When `load()` is called, `vm.async.load` becomes `{ loading: true, error: null, errorCode: null }`.
+- When it resolves, `vm.async.load` becomes `{ loading: false, error: null, errorCode: null }`.
+- If it throws, the error is classified via `classifyError()` — `vm.async.load.error` gets the message string and `vm.async.load.errorCode` gets a discriminant code (e.g. `'unauthorized'`, `'network'`, `'server_error'`, `'unknown'`). The error is re-thrown (preserving standard Promise behavior).
+- If `disposeSignal` aborts and `fetch` throws an `AbortError`, it's silently swallowed — not captured as an error, not re-thrown.
+- If `set()` is called after dispose (in-flight callback resolves late), it's a no-op — no crash, no guard needed.
+
+The component reads async status directly from `vm.async`:
+
+```tsx
+function LocationsPage() {
+  const [state, vm] = useLocal(LocationsViewModel, { /* ... */ });
+  const { loading, error } = vm.async.load;
+
+  return (
+    <div>
+      {loading && <p>Loading…</p>}
+      {error && <p className="error">{error}</p>}
+      <LocationsTable locations={vm.filtered} />
+    </div>
+  );
+}
+```
+
+For error-type branching, use `errorCode`:
+
+```tsx
+const { loading, error, errorCode } = vm.async.load;
+if (errorCode === 'unauthorized') return <Redirect to="/login" />;
+if (errorCode === 'network') return <NetworkError onRetry={() => vm.load()} />;
+```
+
+**When you still need try/catch:** Only when you want to do something specific beyond what async tracking provides — emitting an imperative event on error, rolling back optimistic updates, or running custom logic on success before the method returns:
+
+```typescript
+async save() {
+  try {
+    const result = await this.service.save(this.state.draft, this.disposeSignal);
+    this.collection.update(result.id, result);
+    this.emit('saved', { id: result.id });
+  } catch (e) {
+    this.emit('error', { message: classifyError(e).message });
+    throw e; // re-throw so async tracking still captures it
+  }
+}
+```
+
+Note the `throw e` at the end of the catch block. If you swallow the error, async tracking won't see it. Re-throw to let the framework track it.
+
+**`isAbortError` is only needed when the catch block affects shared state.** The async tracking wrapper swallows AbortErrors at the outer promise level, but your internal catch block does receive them. `set()` and `emit()` are already no-ops after dispose, so they don't need guarding. Use `isAbortError()` to guard operations on objects that outlive the ViewModel — like rolling back optimistic updates on a singleton Collection:
+
+```typescript
+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;
+  }
+}
+```
+
+### Cancellation with disposeSignal
+
+Pass `this.disposeSignal` to every async call. When the component unmounts, `dispose()` fires, the signal aborts, `fetch()` throws `AbortError`, and async tracking swallows it.
+
+```typescript
+async load() {
+  const data = await this.service.getAll(this.disposeSignal);
+  this.collection.reset(data);
+}
+```
+
+For per-call cancellation (e.g. user switches rooms rapidly), compose signals with `AbortSignal.any()`:
+
+```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() });
+}
+```
+
+### Imperative Events
+
+Some actions produce one-shot signals that don't belong in state: toast notifications, navigation redirects, scroll-to-error, shake animations. ViewModels have built-in typed events for this via the second generic parameter.
+
+```typescript
+interface SaveEvents {
+  saved: { id: string };
+  deleted: { id: string };
+  validationFailed: void;
+}
+
+export class ItemViewModel extends ViewModel<State, SaveEvents> {
+  private service = singleton(ItemService);
+  private collection = singleton(ItemsCollection);
+
+  async save() {
+    const result = await this.service.save(this.state.draft, this.disposeSignal);
+    this.collection.update(result.id, result);
+    this.emit('saved', { id: result.id });  // protected, type-safe
+  }
+
+  async delete(id: string) {
+    await this.service.delete(id, this.disposeSignal);
+    this.collection.remove(id);
+    this.emit('deleted', { id });
+  }
+
+  submit() {
+    if (!this.isValid) {
+      this.emit('validationFailed');
+      return;
+    }
+    this.save();
+  }
+}
+```
+
+The component subscribes with `useEvent` directly on the ViewModel:
+
+```tsx
+function ItemPage() {
+  const [state, vm] = useLocal(ItemViewModel, { /* ... */ });
+
+  useEvent(vm, 'saved', ({ id }) => {
+    toast.success(`Item ${id} saved`);
+  });
+
+  useEvent(vm, 'validationFailed', () => {
+    scrollToFirstError();
+  });
+
+  return <div>{/* ... */}</div>;
+}
+```
+
+`emit()` is **protected** — only the ViewModel can emit. The event bus is lazy (zero cost if never used) and auto-disposes with the ViewModel.
+
+### Exposing Actions
+
+Public methods are the component's API. Name them as user-intent verbs:
+
+```typescript
+// ✓ Good: user-intent verbs
+vm.load()
+vm.refresh()
+vm.setSearch(query)
+vm.toggleStatus(id)
+vm.remove(id)
+vm.submit()
+
+// ✗ Bad: implementation-detail names
+vm.fetchDataFromApi()
+vm.updateCollectionAndRefilter()
+vm.setStateLoading()
+```
+
+### ViewModel Section Order
+
+Organize every ViewModel consistently:
+
+```typescript
+export class LocationsViewModel extends ViewModel<State, Events> {
+  // --- Private fields ---
+  private service = singleton(LocationService);
+  private collection = singleton(LocationsCollection);
+
+  // --- Computed getters ---
+  get filtered(): LocationState[] { /* ... */ }
+  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.** This order makes every ViewModel scannable.
+
+### Resetting a ViewModel
+
+`reset(newState?)` tears down the current lifecycle and re-initializes without unmounting the component. It aborts in-flight async, resets subscriptions and state, clears async tracking, and re-runs `onInit()`. See `src/ViewModel.md` for full API details.
+
+```typescript
+vm.reset();                                  // reset to initial state
+vm.reset({ userId: newId, data: null });     // reset with new state
+```
+
+---
+
+## Components
+
+### One ViewModel, Minimal Hooks
+
+A connected component owns one ViewModel via `useLocal`. It may add `useEvent` for imperative events — but all on the same ViewModel. Async status is read directly from `vm.async`. That's the full toolkit.
+
+```tsx
+export function LocationsPage() {
+  const [state, vm] = useLocal(LocationsViewModel, {
+    search: '',
+    typeFilter: 'all',
+  });
+  const { loading, error } = vm.async.load;
+
+  return (
+    <div>
+      <LocationFilters
+        search={state.search}
+        typeFilter={state.typeFilter}
+        onSearchChange={v => vm.setSearch(v)}
+        onTypeFilterChange={v => vm.setTypeFilter(v)}
+      />
+
+      {loading && <p>Loading…</p>}
+      {error && <p className="error">{error}</p>}
+
+      <LocationsTable locations={vm.filtered} />
+      <p>Showing {vm.filtered.length} of {vm.total}</p>
+    </div>
+  );
+}
+```
+
+No `useEffect`. No `useState`. No `useMemo`. No `useCallback`. The ViewModel is the hook.
+
+```tsx
+// ✗ Bad: multiple useLocal — split into two components
+const [usersState, usersVM] = useLocal(UsersViewModel, { ... });
+const [onDutyState, onDutyVM] = useLocal(OnDutyViewModel, { ... });
+
+// ✓ Good: each component owns one ViewModel
+<UsersTable />
+<OnDutySidebar />
+```
+
+```tsx
+// ✗ Bad: logic in the component
+const filtered = state.items.filter(i => i.status === 'active');
+
+// ✓ Good: getter on the ViewModel
+<ItemTable items={vm.filtered} />
+```
+
+### Connected vs Presentational
+
+**Connected components** call `useLocal` and own a ViewModel — pages, sidebars, cards, self-contained widgets. **Presentational components** receive props and render UI with zero knowledge of mvc-kit. Keep the ratio high: many presentational, few connected.
+
+### No useEffect for Data Loading
+
+The ViewModel's `onInit()` handles initialization. `useLocal` calls `init()` automatically after mount.
+
+```tsx
+// ✗ Bad: component orchestrates loading
+function UsersPage() {
+  const [state, vm] = useLocal(UsersViewModel, { ... });
+  useEffect(() => { vm.load(); }, []);
+  return <div>...</div>;
+}
+
+// ✓ Good: ViewModel handles its own initialization via onInit()
+function UsersPage() {
+  const [state, vm] = useLocal(UsersViewModel, { ... });
+  return <div>...</div>;
+}
+```
+
+### Multiple Async Operations
+
+When a component needs loading/error state for more than one async method, destructure each from `vm.async`:
+
+```tsx
+const loadState = vm.async.load;
+const saveState = vm.async.save;
+
+// Use loadState.loading, loadState.error, saveState.loading, etc.
+```
+
+### useLocal with Dependencies
+
+`useLocal` accepts an optional `deps` array as its final argument. When any dep changes, the current instance is disposed and a new one is created and initialized. Use this when a ViewModel is tied to a route param or prop that can change without unmounting.
+
+```tsx
+function UserPage({ userId }: { userId: string }) {
+  const [state, vm] = useLocal(UserViewModel, { userId, data: null }, [userId]);
+  const { loading, error } = vm.async.onInit;
+
+  return (
+    <div>
+      {loading && <Spinner />}
+      {error && <ErrorBanner message={error} />}
+      {state.data && <UserProfile user={state.data} />}
+    </div>
+  );
+}
+```
+
+When `userId` changes, `UserViewModel` is disposed (aborting in-flight requests via `disposeSignal`) and a fresh instance is created with the new `userId` in its initial state. The factory overload also supports deps: `useLocal(() => new ChatViewModel(roomId), [roomId])`.
+
+---
+
+## Shared State Across Components
+
+When sibling or parent-child components need to share state, use one of these patterns in order of preference.
+
+### Pattern A: Parent ViewModel with Presentational Children
+
+The parent creates the ViewModel and passes state down as props. Children are presentational. This is the default.
+
+```tsx
+function OrderPage() {
+  const [state, vm] = useLocal(OrderViewModel, { /* ... */ });
+  const { loading, error } = vm.async.load;
+
+  return (
+    <div>
+      <OrderHeader status={state.status} />
+      <OrderItems
+        items={vm.visibleItems}
+        onRemove={id => vm.removeItem(id)}
+      />
+      <OrderSummary
+        subtotal={vm.subtotal}
+        total={vm.total}
+        onSubmit={() => vm.submit()}
+        canSubmit={vm.canSubmit}
+      />
+    </div>
+  );
+}
+```
+
+### Pattern B: Singleton ViewModel
+
+When components are far apart in the tree, use a singleton ViewModel via `useSingleton`. Multiple components subscribe to the same instance. Define `static DEFAULT_STATE` so every call site is arg-free:
+
+```typescript
+class CartViewModel extends ViewModel<CartState> {
+  static DEFAULT_STATE: CartState = { items: [] };
+  // ...methods
+}
+```
+
+```tsx
+function CartIcon() {
+  const [state, vm] = useSingleton(CartViewModel);
+  return <span className="badge">{vm.itemCount}</span>;
+}
+
+function CartDrawer() {
+  const [state, vm] = useSingleton(CartViewModel);
+  return (
+    <aside>
+      {state.items.map(item => (
+        <CartItem key={item.id} item={item} onRemove={() => vm.removeItem(item.id)} />
+      ))}
+      <p>Total: ${vm.total}</p>
+    </aside>
+  );
+}
+```
+
+Use this for app-wide concerns — cart, auth, theme — where state must survive route changes.
+
+#### Convenience Hooks (Optional)
+
+For singleton ViewModels that appear in many components (auth, theme, cart), you can co-export a convenience hook from the ViewModel file to reduce imports at each call site:
+
+```typescript
+// viewmodels/AuthViewModel.ts
+import { ViewModel, singleton } from 'mvc-kit';
+import { useSingleton } from 'mvc-kit/react';
+
+export class AuthViewModel extends ViewModel<AuthState> {
+  static DEFAULT_STATE: AuthState = { user: null, accessToken: null };
+  // ...getters, actions
+}
+
+export const useAuth = () => useSingleton(AuthViewModel);
+```
+
+```tsx
+// components/Header.tsx — single import
+import { useAuth } from '../viewmodels/AuthViewModel';
+
+function Header() {
+  const [state, vm] = useAuth();
+  return <span>{vm.displayName}</span>;
+}
+```
+
+This is a user-land convention, not a framework feature. The ViewModel class itself stays framework-agnostic — testable without React via `new AuthViewModel(state)`. Use this sparingly for the 2–3 singletons that appear in many files, not for every ViewModel. Component-scoped ViewModels (which use `useLocal` with constructor args) don't benefit from this pattern.
+
+### Pattern C: Separate Components with Shared Collection
+
+When two components show different views of the same data, give each its own ViewModel and let them share a singleton Collection. The Collection is the synchronization point.
+
+```tsx
+function UsersPage() {
+  return (
+    <div className="users-layout">
+      <UsersTable />      {/* UsersViewModel → getters read from UsersCollection */}
+      <OnDutySidebar />   {/* OnDutyViewModel → getters read from UsersCollection */}
+    </div>
+  );
+}
+```
+
+When `UsersViewModel` calls `collection.reset(data)`, auto-tracking detects the change and `OnDutyViewModel`'s derived getters recompute. Both stay in sync from a single data fetch.
+
+### Which Pattern to Choose
+
+"Can the parent own one ViewModel and pass props?" → **Pattern A**.
+"Should state survive route changes and be accessible from anywhere?" → **Pattern B**.
+"Do the components have different concerns but share underlying data?" → **Pattern C**.
+
+---
+
+## Services
+
+Services are singleton, stateless infrastructure adapters. They wrap external dependencies behind a clean interface. See `src/Service.md` for full API reference.
+
+**Rules:**
+- **Stateless** — don't cache data between calls (that's a Collection's job).
+- **Accept `AbortSignal`** — lets ViewModels cancel in-flight requests via `disposeSignal`.
+- **Throw `HttpError`** — carries the HTTP status code for `classifyError()` to produce canonical error codes.
+- **No knowledge of ViewModels or Collections** — Services sit at the bottom of the dependency graph.
+
+```typescript
+import { Service, HttpError } from 'mvc-kit';
+
+export class UserService extends Service {
+  async getAll(signal?: AbortSignal): Promise<UserState[]> {
+    const res = await fetch('/api/users', { signal });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+}
+```
+
+Resolved via `singleton()` inside ViewModels as property initializers:
+
+```typescript
+private service = singleton(LocationService);
+```
+
+---
+
+## Collections
+
+Collections are reactive typed arrays — the shared in-memory data cache. See `src/Collection.md` for full API reference.
+
+**Rules:**
+- **One Collection per entity** — thin subclasses for singleton identity. Don't add methods; query logic belongs in ViewModel getters.
+- **Never component-facing** — components don't import, subscribe to, or know about Collections.
+- **Getters read from collections directly** — auto-tracking handles reactivity. Use `subscribeTo` only for imperative side effects.
+- **Use `upsert()` for paginated/incremental loads** — accumulates data without destroying what other ViewModels depend on. Use `reset()` only for full replacement.
+- **Use `collection.optimistic()`** for instant UI feedback — don't manually snapshot and restore.
+
+```typescript
+export class UsersCollection extends Collection<UserState> {}
+```
+
+### Optimistic Updates
+
+```typescript
+async toggleStatus(id: string) {
+  const rollback = this.collection.optimistic(() => {
+    this.collection.update(id, { status: 'done' });
+  });
+  try {
+    await this.service.update(id, { status: 'done' }, this.disposeSignal);
+  } catch (e) {
+    if (!isAbortError(e)) rollback(); // guard needed — rollback affects shared Collection
+    throw e;
+  }
+}
+```
+
+Snapshot is a reference capture (items are always frozen), rollback is idempotent and no-op when disposed, nesting works naturally. Re-throw the error so async tracking still captures it. The `isAbortError()` guard is needed here because `rollback()` operates on the singleton Collection which outlives the ViewModel — on abort (component unmount), you don't want to undo the optimistic update.
+
+### Eviction & TTL
+
+For long-lived singleton Collections that accumulate unbounded data (chat messages, notifications, activity feeds), configure `MAX_SIZE` and/or `TTL` via static overrides:
+
+```typescript
+class MessagesCollection extends Collection<Message> {
+  static MAX_SIZE = 500;       // FIFO eviction when exceeded
+  static TTL = 5 * 60_000;    // Auto-expire after 5 minutes
+}
+```
+
+Both features are zero-cost when not configured — no timers, no timestamp maps. Override `onEvict` to control which items get evicted:
+
+```typescript
+class ActiveOrdersCollection extends Collection<Order> {
+  static MAX_SIZE = 200;
+
+  protected onEvict(items: Order[], reason: 'capacity' | 'ttl') {
+    return items.filter(o => o.status !== 'in_progress');
+  }
+}
+```
+
+---
+
+## Persistence
+
+For Collections that need to cache/repopulate from storage across sessions, use a `PersistentCollection` subclass. See `src/PersistentCollection.md` for the full API.
+
+**When to use which adapter:**
+- **`WebStorageCollection`** (`mvc-kit/web`) — Small datasets (<5MB), sync auto-hydration, localStorage/sessionStorage
+- **`IndexedDBCollection`** (`mvc-kit/web`) — Large datasets, per-item storage, requires `hydrate()`
+- **`NativeCollection`** (`mvc-kit/react-native`) — React Native, configurable backend, requires `hydrate()`
+
+**Rules:**
+- **Persist entity caches, not ephemeral UI state.** Persistence adds I/O overhead on every mutation. Don't persist search results, selections, or high-churn data.
+- **Use `singleton()` for persistent collections.** Non-singleton persistence triggers a full read on every mount and writes on every mutation.
+- **Call `hydrate()` in `onInit()` for async adapters.** IndexedDB and NativeCollection require manual hydration.
+- **Tune `WRITE_DELAY` for your use case.** Default is `0` (immediate writes). Set `static override WRITE_DELAY = 100` to coalesce rapid mutations (useful for drag-and-drop, real-time collaboration, or high-frequency updates).
+
+```typescript
+// Web — localStorage (auto-hydrates)
+import { WebStorageCollection } from 'mvc-kit/web';
+
+class CartCollection extends WebStorageCollection<CartItem> {
+  protected readonly storageKey = 'cart';
+}
+
+// Web — IndexedDB (requires hydrate)
+import { IndexedDBCollection } from 'mvc-kit/web';
+
+class MessagesCollection extends IndexedDBCollection<Message> {
+  protected readonly storageKey = 'messages';
+  static MAX_SIZE = 500;
+}
+
+// React Native — configured backend (requires hydrate)
+import { NativeCollection } from 'mvc-kit/react-native';
+
+class TodosCollection extends NativeCollection<Todo> {
+  protected readonly storageKey = 'todos';
+}
+```
+
+---
+
+## Resources
+
+Resources extend Collection with lifecycle management and automatic async tracking. Use a Resource when you need a data cache with built-in loading/error state for API calls. See `src/Resource.md` for full API reference.
+
+**When to use Resource vs Collection:**
+- **Collection** — shared data cache, no async loading needed
+- **PersistentCollection** — shared data cache + browser/device storage persistence
+- **Resource** — shared data cache + API loading + `resource.async.methodName.loading/error`
+
+### Define Your Own Async Methods
+
+Resource has no prescribed fetcher. Define your own methods and use inherited Collection mutations. If you have a typed API client, call it directly — no Service wrapper needed:
+
+```typescript
+import { Resource } from 'mvc-kit';
+import { apiClient } from '@/api';
+
+class UsersResource extends Resource<UserState> {
+  async loadAll() {
+    const data = await apiClient.users.list({ signal: this.disposeSignal });
+    this.reset(data);
+  }
+
+  async loadOnDuty(filter: string) {
+    const data = await apiClient.users.getOnDuty(filter, { signal: this.disposeSignal });
+    this.reset(data);
+  }
+}
+```
+
+Use a Service only when wrapping raw `fetch()` with `HttpError`, composing multiple HTTP calls, or managing auth/retries:
+
+```typescript
+class UsersResource extends Resource<UserState> {
+  private api = singleton(UserService); // Service earns its place here
+
+  async loadAll() {
+    const data = await this.api.getAll(this.disposeSignal);
+    this.reset(data);
+  }
+}
+```
+
+Each method gets independent async tracking: `resource.async.loadAll.loading`, `resource.async.loadOnDuty.error`.
+
+### External Collection Injection
+
+When multiple sources feed the same data (Resource for REST + Channel for WebSocket), inject a shared Collection:
+
+```typescript
+class UsersResource extends Resource<UserState> {
+  constructor() {
+    super(singleton(SharedUsersCollection));
+  }
+
+  async loadAll() {
+    const data = await this.api.getAll(this.disposeSignal);
+    this.reset(data); // Mutates the shared collection
+  }
+}
+```
+
+All Collection methods transparently delegate to the external collection. Resource disposal does NOT dispose the shared collection.
+
+### ViewModel Integration
+
+ViewModels access Resources the same way as Collections — via `singleton()` with getter auto-tracking:
+
+```typescript
+class UsersViewModel extends ViewModel<{ search: string }> {
+  private users = singleton(UsersResource);
+
+  get filtered() {
+    return this.users.filter(u => u.name.includes(this.state.search));
+  }
+
+  onInit() {
+    if (this.users.length === 0) this.users.loadAll();
+  }
+}
+```
+
+---
+
+## EventBus
+
+The EventBus connects parts of the app that have no direct reference to each other. See `src/EventBus.md` for full API reference.
+
+**Two scopes:**
+- **ViewModel events** — one-shot imperative signals from a ViewModel to its component, built-in via the second generic parameter. See [Imperative Events](#imperative-events).
+- **App-level EventBus** — signals that cross route boundaries. Singleton, shared across ViewModels.
+
+```typescript
+export interface AppEvents {
+  'users:loaded': void;
+  'auth:logout': void;
+}
+
+export class AppEventBus extends EventBus<AppEvents> {}
+```
+
+**EventBus vs Collection subscription:** If a ViewModel needs to react when *data changes*, subscribe to the Collection. If it needs to react when *something happened* (user logged out, data loaded on another route), listen to the EventBus. Collections carry state; EventBus carries intent.
+
+Keep the event map small — past 10–15 events, your app likely has entangled concerns.
+
+---
+
+## Channel
+
+A Channel manages a persistent external connection (WebSocket, SSE) with auto-reconnect and typed message handling. See `src/Channel.md` for the subclass contract, connection control, auto-reconnect configuration, and message routing API.
+
+Channels are singletons. ViewModels subscribe to them for status changes and message handling.
+
+### pipeChannel — Channel-to-Collection Bridge
+
+When every Channel message should be upserted into a Collection, use `pipeChannel`:
+
+```typescript
+export class DashboardCardViewModel extends ViewModel {
+  private channel = singleton(DashboardChannel);
+  private collection = singleton(DashboardCollection);
+
+  protected onInit() {
+    this.pipeChannel(this.channel, 'data', this.collection);
+    this.channel.connect();
+  }
+}
+```
+
+`pipeChannel` calls `channel.init()` (idempotent), subscribes to the event, and upserts each payload. Auto-cleanup on dispose and reset.
+
+### Custom Channel Handling
+
+When you need to transform, filter, or route messages, use `listenTo` directly:
+
+```typescript
+export class ChatViewModel extends ViewModel<State> {
+  private channel = singleton(ChatChannel);
+
+  protected onInit() {
+    this.listenTo(this.channel, 'message', (msg) => {
+      this.set({ messages: [...this.state.messages, msg] });
+    });
+
+    this.channel.connect();
+  }
+}
+```
+
+Because Channel implements `Subscribable`, it is auto-tracked as a subscribable member — getter memoization sees connection status changes. Use `listenTo` for `channel.on()` event subscriptions — it auto-cleans up on both dispose and reset, just like `subscribeTo` does for state subscriptions.
+
+---
+
+## Controller
+
+Controller is a minimal base class for stateless orchestrators. It provides lifecycle management (`init`/`dispose`), `disposeSignal`, `subscribeTo`, `listenTo`, and `addCleanup` — but no state, no getters, no async tracking.
+
+Most orchestration fits in a single ViewModel. Use a Controller only when coordinating multiple ViewModels in a single workflow (multi-step checkout, drag-and-drop between lists, complex form wizards). It is not a prescribed pattern — reach for it only when a ViewModel can't do the job alone.
+
+---
+
+## Models
+
+Models represent individual entities with validation and dirty tracking. Use them for create and edit forms.
+
+**When to use Model vs ViewModel:** Use a **Model** when editing a single entity with field-level validation, commit/rollback semantics, and dirty tracking. Use a **ViewModel** for everything else.
+
+```typescript
+class UserFormModel extends Model<UserFormState> {
+  setName(name: string) { this.set({ name }); }
+  setEmail(email: string) { this.set({ email }); }
+
+  protected validate(state: UserFormState) {
+    const errors: Partial<Record<keyof UserFormState, string>> = {};
+    if (!state.name.trim()) errors.name = 'Name is required';
+    if (!state.email.includes('@')) errors.email = 'Invalid email';
+    return errors;
+  }
+}
+```
+
+### Models Inside ViewModels
+
+For forms with surrounding page state (submission, server errors), wrap the Model inside a ViewModel:
+
+```typescript
+class EditUserViewModel extends ViewModel<EditState, EditEvents> {
+  public model!: UserFormModel;
+  private service = singleton(UserService);
+
+  protected async onInit() {
+    const user = await this.service.getById(this.userId, this.disposeSignal);
+    this.model = new UserFormModel(user);
+    this.set({ draft: user });
+  }
+
+  async save() {
+    if (!this.model.valid) return;
+    await this.service.update(this.userId, this.model.state, this.disposeSignal);
+    this.model.commit();
+    this.emit('saved', { id: this.userId });
+  }
+
+  protected onDispose() {
+    this.model?.dispose();
+  }
+}
+```
+
+The component:
+
+```tsx
+function EditUserPage() {
+  const [state, vm] = useLocal(EditUserViewModel, { draft: null });
+  const loadState = vm.async.onInit;
+  const saveState = vm.async.save;
+
+  useEvent(vm, 'saved', ({ id }) => {
+    toast.success('User saved');
+    navigate(`/users/${id}`);
+  });
+
+  if (loadState.loading || !vm.model) return <Spinner />;
+  if (loadState.error) return <ErrorBanner message={loadState.error} />;
+
+  return <EditUserForm model={vm.model} onSave={() => vm.save()} saving={saveState.loading} />;
+}
+
+function EditUserForm({ model, onSave, saving }: Props) {
+  const { state, errors, valid, dirty } = useModel(() => model);
+
+  return (
+    <form onSubmit={e => { e.preventDefault(); onSave(); }}>
+      <input value={state.name} onChange={e => model.setName(e.target.value)} />
+      {errors.name && <span>{errors.name}</span>}
+      <button disabled={!valid || !dirty || saving}>
+        {saving ? 'Saving…' : 'Save'}
+      </button>
+    </form>
+  );
+}
+```
+
+`useModel` binds a Model to a React component — it creates the instance from a factory, auto-initializes, auto-disposes, and subscribes to changes. The returned `ModelHandle` provides `state`, `errors`, `valid`, `dirty`, and `model`. For large forms with per-field isolation, use `useModelRef` in the parent (lifecycle-only, no subscription) and `useField(model, 'fieldName')` in children for surgical re-renders. See `src/react/use-model.md` for full API details.
+
+---
+
+## Singleton vs Component-Scoped
+
+| Class | Default Scope | Why |
+|---|---|---|
+| Service | Singleton | Stateless, shared infrastructure |
+| Collection | Singleton | Shared data cache across ViewModels |
+| EventBus (app-level) | Singleton | App-wide communication |
+| Channel | Singleton | Persistent connection shared across ViewModels |
+| ViewModel | Component-scoped | Tied to a specific component's lifecycle |
+| Controller | Component-scoped | Tied to a specific workflow's lifecycle |
+| Model | Component-scoped | Tied to a specific form's lifecycle |
+
+Singleton ViewModels are the exception for app-wide state (auth, theme, cart). Default to `useLocal` and promote to `useSingleton` only when needed.
+
+---
+
+## Dev Mode
+
+Enable `__MVC_KIT_DEV__` during development to catch common mistakes early:
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  define: {
+    __MVC_KIT_DEV__: process.env.NODE_ENV !== 'production',
+  },
+});
+```
+
+Dev mode catches:
+
+- **`set()` inside a getter** — prevents infinite loops with a clear console error.
+- **Ghost async operations** — warns when a ViewModel is disposed with pending async calls, suggesting `disposeSignal`.
+- **Method call after dispose** — warns and returns `undefined` instead of silently proceeding.
+- **Method call before init** — warns that async tracking isn't active yet.
+
+In production, omit the flag (or set to `false`). All dev checks are dead-code-eliminated by minifiers — zero runtime cost.
+
+---
+
+## Error Handling Strategy
+
+mvc-kit provides a three-layer error handling strategy:
+
+**Layer 1 — Async Tracking (automatic).** For most async methods, write the happy path. Errors are captured in `vm.async.methodName.error` and `errorCode`. The component reads them directly. No try/catch needed. See [Async Methods](#async-methods) for examples.
+
+**Layer 2 — Imperative Events (explicit).** When an error should trigger a specific UI effect (toast, redirect, modal), add try/catch, emit a ViewModel event, and **re-throw** so async tracking still captures it. `emit()` and `set()` are no-ops after dispose, so no `isAbortError()` guard is needed for them. See [Imperative Events](#imperative-events) for examples.
+
+**Layer 3 — Error Classification (services).** Services throw `HttpError` for HTTP failures. `classifyError()` normalizes any error into a canonical shape:
+
+```typescript
+const appError = classifyError(error);
+// appError.code: 'unauthorized' | 'network' | 'timeout' | 'abort' | ...
+// appError.message: human-readable string
+```
+
+**When to use `isAbortError()`:** The async tracking wrapper swallows AbortErrors at the outer promise level, but your internal catch blocks do receive them. You only need `isAbortError()` when the catch block has side effects on shared state that outlives the ViewModel — like rolling back optimistic updates on a singleton Collection. You don't need it when the catch block only calls `set()` and `emit()` (both are no-ops after dispose), and you never need it in methods without try/catch.
+
+---
+
+## Testing
+
+Test ViewModels by constructing, calling `init()`, invoking methods, and asserting state, getters, and async status. Always call `teardownAll()` in `beforeEach` to reset the singleton registry.
+
+```typescript
+import { singleton, teardownAll } from 'mvc-kit';
+
+beforeEach(() => teardownAll());
+
+test('filtered getter applies search', () => {
+  const collection = singleton(UsersCollection);
+  collection.reset([
+    { id: '1', firstName: 'Alice', status: 'on_duty' },
+    { id: '2', firstName: 'Bob', status: 'off_duty' },
+  ]);
+
+  const vm = new UsersViewModel({ search: '', roleFilter: 'all' });
+  vm.init();
+
+  expect(vm.items).toHaveLength(2);
+  expect(vm.filtered).toHaveLength(2);
+
+  vm.setSearch('alice');
+  expect(vm.filtered).toHaveLength(1);
+  expect(vm.filtered[0].firstName).toBe('Alice');
+
+  vm.dispose();
+});
+```
+
+**Async methods:** Assert against `vm.async.methodName.loading` and `vm.async.methodName.error` before and after awaiting the method.
+
+**Events:** Subscribe via `vm.events.on('eventName', handler)` and assert the handler was called with expected payload.
+
+**Models:** Construct, call setters, assert `model.valid`, `model.errors`, and `model.dirty`. See `src/Model.md`.
+
+**Integration tests with Provider:** See `src/react/use-model.md` and `src/react/use-local.md` for examples with mock dependency injection.
+
+---
+
+## Composable Helpers
+
+Sorting, Pagination, Selection, Feed, and Pending are composable helpers that extend `Trackable`. They integrate with auto-tracking: any ViewModel getter that reads from a helper auto-invalidates when the helper's state changes.
+
+### Custom Helpers with Trackable
+
+When integrating third-party SDKs or building custom reactive state, extend `Trackable` instead of reimplementing subscribe/dispose/bind boilerplate:
+
+```typescript
+import { Trackable } from 'mvc-kit';
+
+class RPCQuery<Data> extends Trackable {
+  private _data: Data | undefined;
+  private _loading = false;
+
+  get data() { return this._data; }
+  get loading() { return this._loading; }
+
+  async call(): Promise<void> {
+    this._loading = true;
+    this.notify();
+    this._data = await fetchData();
+    this._loading = false;
+    this.notify();
+  }
+}
+```
+
+Use as a ViewModel property for auto-tracking, or directly with `useLocal` for component-scoped reactive instances.
+
+### When to Use Which Helper
+
+| Scenario | Helper |
+|----------|--------|
+| Table column sorting (single or multi) | `Sorting<T>` |
+| Client-side page-based pagination | `Pagination` |
+| Row/item selection (checkboxes, bulk actions) | `Selection<K>` |
+| Server-side cursor pagination (infinite scroll) | `Feed<T>` |
+| Per-item operation retry with status tracking | `Pending<K, Meta?>` |
+
+### Pattern: Table with Sort + Filter + Pagination + Selection
+
+```typescript
+interface UsersFilter { search: string; roleFilter: 'all' | Role }
+
+class UsersListVM extends ViewModel<UsersFilter> {
+  private users = singleton(UsersResource);
+
+  readonly sorting = new Sorting<User>({ sorts: [{ key: 'name', direction: 'asc' }] });
+  readonly pagination = new Pagination({ pageSize: 25 });
+  readonly selection = new Selection<string>();
+
+  get filtered(): User[] {
+    const { search, roleFilter } = this.state;
+    let result = this.users.items;
+    if (search) {
+      const q = search.toLowerCase();
+      result = result.filter(u => u.name.toLowerCase().includes(q));
+    }
+    if (roleFilter !== 'all') result = result.filter(u => u.role === roleFilter);
+    return result;
+  }
+
+  get items(): User[] {
+    return this.pagination.apply(this.sorting.apply(this.filtered));
+  }
+
+  get total() { return this.filtered.length; }
+
+  protected onInit() {
+    if (this.users.length === 0) this.users.loadAll();
+  }
+
+  setSearch(search: string) { this.set({ search }); this.pagination.reset(); }
+}
+```
+
+### Pattern: Infinite Scroll Feed
+
+```typescript
+class SocialFeedVM extends ViewModel {
+  private resource = singleton(PostsResource);
+  readonly feed = new Feed();
+
+  get items() { return this.resource.items; }
+  get hasMore() { return this.feed.hasMore; }
+
+  protected onInit() {
+    if (this.resource.length === 0) this.loadMore();
+  }
+
+  async loadMore() {
+    const result = await fetchPosts(this.feed.cursor, 20, this.disposeSignal);
+    this.resource.upsert(...result.items);
+    this.feed.setResult(result);
+  }
+}
+```
+
+### Pattern: Resilient Optimistic Updates with Pending
+
+```typescript
+class ItemsResource extends Resource<Item> {
+  readonly pending = new Pending<string>();
+
+  async deleteItem(id: string) {
+    this.optimistic(() => this.remove(id));
+    this.pending.enqueue(id, 'delete', async (signal) => {
+      await api.deleteItem(id, signal);
+    });
+  }
+
+  protected override onDispose() {
+    this.pending.dispose();
+  }
+}
+
+class ItemsVM extends ViewModel<{ filter: string }> {
+  private resource = singleton(ItemsResource);
+
+  get pending() { return this.resource.pending; }
+  get items() { return this.resource.items; }
+
+  deleteItem(id: string) { this.resource.deleteItem(id); }
+  retryFailed() { this.resource.pending.retryAll(); }
+}
+```
+
+### Key Points
+
+- Helpers are **plain classes** with a `subscribe()` method — no base class needed
+- Declare as `readonly` instance properties (not in state)
+- Reset pagination on filter changes: `this.pagination.reset()`
+- Reset feed on filter changes: `this.feed.reset()`
+- Use `Selection.set(...keys)` to replace the entire selection atomically (single notification, no-op if unchanged)
+- Use `Feed.replacePage(page)` for pull-to-refresh — replaces all items and updates cursor/hasMore atomically
+- Pending lives on the **singleton Resource**, not the component-scoped ViewModel — operations survive unmount
+- Use the signal from Pending's `enqueue` callback, not `vm.disposeSignal`
+- Helpers without lifecycle (Sorting, Pagination, Selection, Feed) are garbage collected with the ViewModel; Pending has `dispose()` and should be cleaned up in the Resource's `onDispose()`
+
+---
+
+## Headless React Components
+
+`DataTable`, `CardList`, and `InfiniteScroll` are unstyled, semantic HTML components with render-prop customization. They compose naturally with the helpers above but work independently.
+
+### Wiring Helpers to Components
+
+Pass helpers directly — DataTable duck-types their interfaces:
+
+```tsx
+function UsersPage() {
+  const [state, vm] = useLocal(UsersListVM, { search: '', roleFilter: 'all' });
+  return (
+    <DataTable
+      items={vm.items}
+      columns={columns}
+      sort={vm.sorting}
+      selection={vm.selection}
+      pagination={vm.pagination}
+      paginationTotal={vm.total}
+      renderEmpty={() => <p>No users found.</p>}
+    />
+  );
+}
+```
+
+### InfiniteScroll + CardList
+
+```tsx
+function SocialFeed() {
+  const [, vm] = useLocal(SocialFeedVM, {});
+  return (
+    <InfiniteScroll
+      hasMore={vm.hasMore}
+      loading={vm.async.loadMore?.loading}
+      onLoadMore={() => vm.loadMore()}
+      renderEnd={() => <p>You've seen it all!</p>}
+    >
+      <CardList
+        items={vm.items}
+        renderItem={post => <PostCard post={post} />}
+        layout="grid"
+        columns={2}
+      />
+    </InfiniteScroll>
+  );
+}
+```
+
+### Styling with Data Attributes
+
+Components emit data attributes for CSS hooks — no class name opinions:
+
+```css
+[data-component="data-table"] table { width: 100%; }
+[data-component="data-table"] th[data-sorted] { font-weight: bold; }
+[data-component="data-table"] tr[data-selected] { background: #e8f0fe; }
+[data-component="card-list"][data-layout="grid"] { --card-list-columns: 4; }
+```
+
+---
+
+## Quick Reference
+
+### Do
+
+- State holds only source-of-truth values (user input, filters)
+- Collection data accessed via getters reading from collection members directly
+- Derived values are `get` accessors on the ViewModel
+- One ViewModel per component via `useLocal`
+- Pass `this.disposeSignal` to every async call
+- Re-throw errors in explicit try/catch blocks
+- Use `collection.optimistic()` for instant UI feedback
+- Use `onInit()` for data loading and subscription setup
+- Name public methods as user-intent verbs
+
+### Don't
+
+- Put `loading`/`error` in your State interface — use `vm.async.methodName`
+- Mirror collection data into state with `subscribeTo` + `set()` — use a getter
+- Store derived values in state — use getters
+- Write `try/catch` for standard loads — async tracking handles it
+- Call `set()` inside a getter — creates infinite loop
+- Import infrastructure (Services, Collections) in components
+- Use `useEffect` for data loading — use `onInit()`
+- Use multiple `useLocal` in one component — split into two components
+- Use `addCleanup` for `channel.on()`/`bus.on()` subscriptions — use `listenTo` instead (reset-safe, impossible to forget)
+- Swallow errors without re-throwing — breaks async tracking
+- Compose a separate EventBus for ViewModel events — use the second generic
+- Put cache/state in Services — use Collections
+- Write two-step setters that call refilter methods — getters handle derivation
+- Manually snapshot/restore for optimistic updates — use `collection.optimistic()`
+- Empty Collection subclass + Service + manual cache checking when a Resource would eliminate the boilerplate
+- Pass-through Service wrapping a typed API client (RPC, tRPC, GraphQL codegen) → call the client directly from Resource
+- `Pending` as a ViewModel own property — it dies on unmount; put it on the singleton Resource
+- Passing `this.disposeSignal` to fetch inside Pending's execute callback — would abort on VM unmount, defeating resilience
+- Using `collection.optimistic()` rollback with Pending — snapshot goes stale during retries