mvc-kit 2.2.1 → 2.2.3

package/README.md

@@ -131,6 +131,7 @@ const todos = new Collection<Todo>();
 
 // CRUD (triggers re-renders)
 todos.add({ id: '1', text: 'Learn mvc-kit', done: false });
+todos.upsert({ id: '1', text: 'Updated', done: true }); // Add-or-replace by ID
 todos.update('1', { done: true });
 todos.remove('1');
 todos.reset([...]); // Replace all
@@ -325,7 +326,9 @@ vm.fetchUsers();  // loading: true (count: 2)
 #### Error handling
 
 - **Normal errors** are captured in `TaskState.error` (as a string message) AND re-thrown — standard Promise rejection behavior is preserved
-- **AbortErrors** are silently swallowed — not captured in `TaskState.error`, not re-thrown
+- **AbortErrors** are silently swallowed by the wrapper — not captured in `TaskState.error`, not re-thrown from the outer promise
+
+For methods without try/catch, AbortError handling is fully automatic. For methods with explicit try/catch, see [Error Utilities](#error-utilities) for when `isAbortError()` is needed.
 
 #### Sync method pruning
 
@@ -364,14 +367,16 @@ import { isAbortError, classifyError, HttpError } from 'mvc-kit';
 // In services — throw typed HTTP errors
 if (!res.ok) throw new HttpError(res.status, res.statusText);
 
-// In ViewModels — replace verbose AbortError checks
-if (isAbortError(e)) return;
+// In ViewModel catch blocks — guard shared-state side effects on abort
+if (!isAbortError(e)) rollback();
 
 // Classify any error into a canonical shape
 const appError = classifyError(error);
 // appError.code: 'unauthorized' | 'network' | 'timeout' | 'abort' | ...
 ```
 
+**When to use `isAbortError()`:** The async tracking wrapper swallows AbortErrors at the outer promise level, but your catch blocks do receive them. Use `isAbortError()` only when the catch block has side effects on shared state (like rolling back optimistic updates on a singleton Collection). You don't need it for `set()` or `emit()` (both are no-ops after dispose), and you never need it in methods without try/catch.
+
 ## Signal & Cleanup
 
 Every class in mvc-kit has a built-in `AbortSignal` and cleanup registration system. This eliminates the need to manually track timers, subscriptions, and in-flight requests.
@@ -397,13 +402,13 @@ class ChatViewModel extends ViewModel<{ messages: Message[] }> {
 
 ### `subscribeTo(source, listener)` (protected)
 
-Subscribe to a Subscribable and auto-unsubscribe on dispose. Available on ViewModel, Model, and Controller.
+Subscribe to a Subscribable and auto-unsubscribe on dispose. Available on ViewModel, Model, and Controller. Use for **imperative reactions** — for deriving values from collections, use getters instead (auto-tracking handles reactivity).
 
 ```typescript
-class UsersViewModel extends ViewModel<State> {
+class ChatViewModel extends ViewModel<State> {
   protected onInit() {
-    // Replaces: this.addCleanup(this.collection.subscribe(() => this.derive()))
-    this.subscribeTo(this.collection, () => this.derive());
+    // Imperative reaction: play sound on new messages
+    this.subscribeTo(this.messagesCollection, () => this.playNotificationSound());
   }
 }
 ```
@@ -685,7 +690,7 @@ function App() {
 |--------|-------------|
 | `AppError` (type) | Canonical error shape with typed `code` field |
 | `HttpError` | Typed HTTP error class for services to throw |
-| `isAbortError(error)` | Guard for AbortError DOMException |
+| `isAbortError(error)` | Guard for AbortError — use in catch blocks with shared-state side effects |
 | `classifyError(error)` | Maps raw errors → `AppError` |
 
 ### React Hooks
@@ -722,7 +727,7 @@ function App() {
 - ViewModel has built-in typed events via optional second generic `E` — `events` getter, `emit()` method
 - After `init()`, all subclass methods are wrapped for automatic async tracking; `vm.async.methodName` returns `TaskState`
 - Sync methods are auto-pruned on first call — zero overhead after detection
-- Async errors are re-thrown (preserves standard Promise rejection); AbortErrors are silently swallowed
+- Async errors are re-thrown (preserves standard Promise rejection); AbortErrors are silently swallowed by the wrapper (but internal catch blocks do receive them — use `isAbortError()` to guard shared-state side effects like Collection rollbacks)
 - `async` and `subscribeAsync` are reserved property names on ViewModel
 - React hooks (`useLocal`, `useModel`, `useSingleton`) auto-call `init()` after mount
 - `singleton()` does **not** auto-call `init()` — call it manually outside React

package/agent-config/claude-code/agents/mvc-kit-architect.md

@@ -52,10 +52,9 @@ When asked to plan a feature:
 
 - State holds only source-of-truth values. Derived values are `get` accessors. Async status comes from `vm.async.methodName`.
 - One ViewModel per component via `useLocal`. No `useEffect` for data loading.
-- Collections are encapsulated by ViewModels. Components never import Collections.
+- Collections are encapsulated by ViewModels. Getters read from collections directly — auto-tracking handles reactivity. Components never import Collections.
 - Services are stateless, accept `AbortSignal`, throw `HttpError`.
-- `onInit()` handles data loading and subscription setup.
-- Use `subscribeTo()` for Collection subscriptions (auto-cleanup).
+- `onInit()` handles data loading. Use `subscribeTo()` only for imperative side effects, not for deriving values.
 - ViewModel section order: Private fields → Computed getters → Lifecycle → Actions → Setters.
 - Pass `this.disposeSignal` to every async call.
 

package/agent-config/claude-code/skills/guide/SKILL.md

@@ -29,13 +29,13 @@ You are assisting a developer using **mvc-kit**, a zero-dependency TypeScript-fi
 
 3. **Components are declarative.** Read `state.x` for raw values, `vm.x` for computed, `vm.async.x` for loading/error. Call `vm.method()` for actions.
 
-4. **Collections are encapsulated.** ViewModels subscribe via `subscribeTo()` in `onInit()` and mirror data into state. Components never import Collections.
+4. **Collections are encapsulated.** ViewModel getters read from collections directly — auto-tracking handles reactivity. Use `subscribeTo()` only for imperative side effects. Components never import Collections.
 
 5. **Services are stateless.** Accept `AbortSignal`, throw `HttpError`, no knowledge of ViewModels or Collections.
 
 6. **Lifecycle**: `construct → init() → use → dispose()`. React hooks auto-call `init()`. Use `onInit()` for data loading.
 
-7. **Async tracking is automatic.** After `init()`, all async methods are tracked. `vm.async.methodName` returns `{ loading, error, errorCode }`. AbortErrors are silently swallowed. Other errors are captured AND re-thrown.
+7. **Async tracking is automatic.** After `init()`, all async methods are tracked. `vm.async.methodName` returns `{ loading, error, errorCode }`. AbortErrors are silently swallowed by the wrapper. Other errors are captured AND re-thrown. Internal catch blocks do receive AbortErrors — use `isAbortError()` only to guard shared-state side effects (like Collection rollbacks). `set()` and `emit()` don't need the guard (no-ops after dispose).
 
 8. **Pass `this.disposeSignal`** to every async call for automatic cancellation on unmount.
 

package/agent-config/claude-code/skills/guide/anti-patterns.md

@@ -9,16 +9,37 @@ Reject these patterns. Each entry shows the bad pattern and the correct alternat
 ```typescript
 // BAD
 interface State {
-  items: Item[];
   loading: boolean;
   error: string | null;
 }
 
 // GOOD — async tracking handles it
+// Read: vm.async.load.loading, vm.async.load.error
+```
+
+---
+
+## 1b. Mirroring Collection Data into State
+
+```typescript
+// BAD — subscribeTo + set() to mirror collection data
 interface State {
   items: Item[];
+  search: string;
+}
+protected onInit() {
+  this.subscribeTo(this.collection, () => {
+    this.set({ items: this.collection.items });
+  });
+}
+
+// GOOD — getter reads from collection directly, auto-tracked
+interface State {
+  search: string;
+}
+get items(): Item[] {
+  return this.collection.items as Item[];
 }
-// Read: vm.async.load.loading, vm.async.load.error
 ```
 
 ---
@@ -175,9 +196,7 @@ async save() {
     await this.service.save(this.state.draft, this.disposeSignal);
     this.emit('saved', { id: this.state.draft.id });
   } catch (e) {
-    if (!isAbortError(e)) {
-      this.emit('error', { message: classifyError(e).message });
-    }
+    this.emit('error', { message: classifyError(e).message }); // no isAbortError guard needed — emit() is a no-op after dispose
     throw e; // async tracking captures the error
   }
 }
@@ -243,7 +262,7 @@ async toggleStatus(id: string) {
   try {
     await this.service.update(id, { status: 'done' }, this.disposeSignal);
   } catch (e) {
-    if (!isAbortError(e)) rollback();
+    if (!isAbortError(e)) rollback(); // guard needed — rollback affects shared Collection
     throw e;
   }
 }
@@ -304,7 +323,25 @@ function UsersPage() {
 
 ---
 
-## 15. Missing disposeSignal on Async Calls
+## 15. Using reset() for Paginated/Incremental Loads
+
+```typescript
+// BAD — reset() destroys data other ViewModels depend on
+async loadPage(page: number) {
+  const data = await this.service.getPage(page, this.disposeSignal);
+  this.collection.reset(data); // wipes previous pages!
+}
+
+// GOOD — upsert() accumulates data, replacing stale items and adding new ones
+async loadPage(page: number) {
+  const data = await this.service.getPage(page, this.disposeSignal);
+  this.collection.upsert(...data);
+}
+```
+
+---
+
+## 16. Missing disposeSignal on Async Calls
 
 ```typescript
 // BAD — no cancellation on unmount

package/agent-config/claude-code/skills/guide/api-reference.md

@@ -108,10 +108,11 @@ Same as ViewModel: `onInit()`, `onSet()`, `onDispose()`, `disposeSignal`, `subsc
 Reactive typed array with CRUD and query methods. Items must have an `id: string` field.
 
 ### CRUD (triggers notifications)
-- `add(item: T): void`
+- `add(...items: T[]): void` — Append items. Skips existing IDs.
+- `upsert(...items: T[]): void` — Add-or-replace by ID. Existing replaced in-place; new appended. Ideal for paginated loads.
 - `update(id: string, partial: Partial<T>): void`
-- `remove(id: string): void`
-- `reset(items: T[]): void` — Replace all items.
+- `remove(...ids: string[]): void`
+- `reset(items: T[]): void` — Replace all items. Use for full loads; prefer `upsert()` for incremental.
 - `clear(): void`
 
 ### Query (pure, no notifications)
@@ -215,7 +216,7 @@ teardownAll()                 // Dispose all (use in test beforeEach)
 ## Error Utilities
 
 - `HttpError(status: number, statusText: string)` — Throw from services.
-- `isAbortError(error: unknown): boolean` — Guard for AbortError.
+- `isAbortError(error: unknown): boolean` — Guard for AbortError. Only needed in catch blocks with shared-state side effects (e.g., Collection rollbacks). Not needed for `set()`/`emit()` (no-ops after dispose) or methods without try/catch.
 - `classifyError(error: unknown): AppError` — Returns `{ code, message, status? }`.
   - Codes: `'unauthorized'`, `'forbidden'`, `'not_found'`, `'network'`, `'timeout'`, `'abort'`, `'server_error'`, `'unknown'`
 

package/agent-config/claude-code/skills/guide/patterns.md

@@ -69,28 +69,27 @@ The setter changes state → React re-renders → getters recompute. No manual r
 
 ## Encapsulating Collections
 
-ViewModels subscribe internally. Components never see Collections.
+Getters read directly from collection members — auto-tracking handles reactivity. Components never see Collections.
 
 ```typescript
 class LocationsViewModel extends ViewModel<State> {
-  private collection = singleton(LocationsCollection);
+  collection = singleton(LocationsCollection);
   private service = singleton(LocationService);
 
+  // Getter reads from collection — auto-tracked
+  get items(): LocationState[] {
+    return this.collection.items as LocationState[];
+  }
+
   protected onInit() {
-    this.subscribeTo(this.collection, () => {
-      this.set({ items: this.collection.items });
-    });
-
-    // Smart init: use cached data or fetch fresh
-    if (this.collection.length > 0) {
-      this.set({ items: this.collection.items });
-    } else {
-      this.load();
-    }
+    // Smart init: skip fetch if data already loaded
+    if (this.collection.length === 0) this.load();
   }
 }
 ```
 
+Use `subscribeTo()` only for imperative side effects (e.g. play a sound on new messages), not for deriving values.
+
 ---
 
 ## Async Methods — Happy Path Only
@@ -100,22 +99,27 @@ async load() {
   const data = await this.service.getAll(this.disposeSignal);
   this.collection.reset(data);
 }
+
+// For paginated/incremental loads, use upsert() to accumulate data:
+async loadPage(page: number) {
+  const data = await this.service.getPage(page, this.disposeSignal);
+  this.collection.upsert(...data);
+}
 ```
 
 No try/catch. No `set({ loading: true })`. No AbortError check. The framework handles it.
 
-**Only add try/catch** for imperative events on error:
+**Only add try/catch** for imperative events on error or optimistic rollbacks:
 
 ```typescript
+// Imperative events — no isAbortError guard needed (emit is a no-op after dispose)
 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) {
-    if (!isAbortError(e)) {
-      this.emit('error', { message: classifyError(e).message });
-    }
+    this.emit('error', { message: classifyError(e).message });
     throw e; // MUST re-throw so async tracking captures it
   }
 }
@@ -221,7 +225,7 @@ class UserService extends Service {
 class UsersCollection extends Collection<UserState> {}
 ```
 
-Thin subclass for singleton identity. No custom methods — query logic goes in ViewModel getters.
+Thin subclass for singleton identity. No custom methods — query logic goes in ViewModel getters. Use `reset()` for full loads, `upsert()` for paginated/incremental loads, and `add`/`update`/`remove` for granular mutations.
 
 ---
 
@@ -235,7 +239,7 @@ async toggleStatus(id: string) {
   try {
     await this.service.update(id, { status: 'done' }, this.disposeSignal);
   } catch (e) {
-    if (!isAbortError(e)) rollback();
+    if (!isAbortError(e)) rollback(); // guard needed — rollback affects shared Collection
     throw e; // re-throw for async tracking
   }
 }

package/agent-config/claude-code/skills/review/checklist.md

@@ -7,13 +7,13 @@
 2. **No derived state in State** — State must not contain values computable from other state (filtered lists, counts, flags). Use getters.
 3. **No `set()` inside getters** — Creates infinite loop. Derived values must be pure computations.
 4. **`disposeSignal` on async calls** — Every `fetch()`, service call, or async operation must receive `this.disposeSignal` or a composed signal.
-5. **Re-throw in try/catch** — Any explicit try/catch must re-throw the error so async tracking captures it. Only guard with `isAbortError()`.
+5. **Re-throw in try/catch** — Any explicit try/catch must re-throw the error so async tracking captures it. Use `isAbortError()` only to guard shared-state side effects (Collection rollbacks). Not needed for `set()`/`emit()` (no-ops after dispose).
 
 ### Warning
 6. **Section order** — Must follow: Private fields → Computed getters → Lifecycle → Actions → Setters.
 7. **No two-step setters** — Setters should be one-liners (`this.set({ x })`). No manual refilter/rederive calls after `set()`.
 8. **Smart init pattern** — When subscribing to a Collection, check `collection.length > 0` before fetching.
-9. **Use `subscribeTo`** — Collection subscriptions must use `subscribeTo()` (auto-cleanup), not manual `subscribe()` + `addCleanup()`.
+9. **Getters read from collections** — Collection data should be accessed via getters, not mirrored into state with `subscribeTo()` + `set()`. Use `subscribeTo()` only for imperative side effects.
 10. **Use `collection.optimistic()`** — No manual snapshot/restore for optimistic updates.
 11. **Singleton resolution as property** — Dependencies resolved via `private service = singleton(MyService)`, not in `onInit()`.
 

package/agent-config/claude-code/skills/scaffold/SKILL.md

@@ -47,6 +47,6 @@ Parse `$ARGUMENTS` as `<type> <Name>` (case-insensitive type, PascalCase Name).
 - Services are stateless, accept `AbortSignal`, throw `HttpError`.
 - Collections are thin subclasses — no custom methods.
 - Use `singleton()` for dependency resolution in ViewModels.
-- Use `subscribeTo()` for Collection subscriptions with smart init pattern.
+- Getters read from collections directly — auto-tracking handles reactivity. Use `subscribeTo()` only for imperative side effects.
 - Pass `this.disposeSignal` to every async call.
 - Test files use `teardownAll()` in `beforeEach`.

package/agent-config/claude-code/skills/scaffold/templates/collection.md

@@ -22,23 +22,16 @@ import { ViewModel, singleton } from 'mvc-kit';
 import { {{Name}}Collection } from '../collections/{{Name}}Collection';
 import type { {{Name}}Item } from '../collections/{{Name}}Collection';
 
-interface State {
-  items: {{Name}}Item[];
-}
+class {{Name}}ViewModel extends ViewModel<{ search: string }> {
+  collection = singleton({{Name}}Collection);
 
-class {{Name}}ViewModel extends ViewModel<State> {
-  private collection = singleton({{Name}}Collection);
+  // Getter reads from collection — auto-tracked
+  get items(): {{Name}}Item[] {
+    return this.collection.items as {{Name}}Item[];
+  }
 
   protected onInit() {
-    this.subscribeTo(this.collection, () => {
-      this.set({ items: this.collection.items });
-    });
-
-    if (this.collection.length > 0) {
-      this.set({ items: this.collection.items });
-    } else {
-      this.load();
-    }
+    if (this.collection.length === 0) this.load();
   }
 
   async load() {

package/agent-config/claude-code/skills/scaffold/templates/viewmodel.md

@@ -8,7 +8,6 @@ import { ViewModel, singleton } from 'mvc-kit';
 // import { {{Name}}Collection } from '../collections/{{Name}}Collection';
 
 interface {{Name}}State {
-  items: any[]; // TODO: Replace with your item type
   search: string;
 }
 
@@ -20,11 +19,18 @@ interface {{Name}}State {
 export class {{Name}}ViewModel extends ViewModel<{{Name}}State> {
   // --- Private fields ---
   // private service = singleton({{Name}}Service);
-  // private collection = singleton({{Name}}Collection);
+  // collection = singleton({{Name}}Collection);
 
   // --- Computed getters ---
+  // Getter reads from collection — auto-tracked
+  // get items(): any[] {
+  //   return this.collection.items;
+  // }
+
   get filtered(): any[] {
-    const { items, search } = this.state;
+    const { search } = this.state;
+    // TODO: read from this.items (collection getter) instead of hardcoded array
+    const items: any[] = [];
     if (!search) return items;
     const q = search.toLowerCase();
     return items.filter(item =>
@@ -33,7 +39,7 @@ export class {{Name}}ViewModel extends ViewModel<{{Name}}State> {
   }
 
   get total(): number {
-    return this.state.items.length;
+    return this.filtered.length;
   }
 
   get hasResults(): boolean {
@@ -42,17 +48,8 @@ export class {{Name}}ViewModel extends ViewModel<{{Name}}State> {
 
   // --- Lifecycle ---
   protected onInit() {
-    // Subscribe to collection and mirror data into state
-    // this.subscribeTo(this.collection, () => {
-    //   this.set({ items: this.collection.items });
-    // });
-
-    // Smart init: use cached data or fetch fresh
-    // if (this.collection.length > 0) {
-    //   this.set({ items: this.collection.items });
-    // } else {
-    //   this.load();
-    // }
+    // Smart init: skip fetch if data already loaded
+    // if (this.collection.length === 0) this.load();
 
     this.load();
   }
@@ -79,9 +76,8 @@ import { {{Name}}ViewModel } from './{{Name}}ViewModel';
 beforeEach(() => teardownAll());
 
 describe('{{Name}}ViewModel', () => {
-  function create(overrides: Partial<{ items: any[]; search: string }> = {}) {
+  function create(overrides: Partial<{ search: string }> = {}) {
     return new {{Name}}ViewModel({
-      items: [],
       search: '',
       ...overrides,
     });
@@ -89,7 +85,6 @@ describe('{{Name}}ViewModel', () => {
 
   test('initializes with default state', () => {
     const vm = create();
-    expect(vm.state.items).toEqual([]);
     expect(vm.state.search).toBe('');
     vm.dispose();
   });
@@ -100,29 +95,5 @@ describe('{{Name}}ViewModel', () => {
     expect(vm.state.search).toBe('test');
     vm.dispose();
   });
-
-  test('filtered getter applies search', () => {
-    const vm = create({
-      items: [
-        { id: '1', name: 'Alpha' },
-        { id: '2', name: 'Beta' },
-      ],
-    });
-
-    expect(vm.filtered).toHaveLength(2);
-
-    vm.setSearch('alpha');
-    expect(vm.filtered).toHaveLength(1);
-
-    vm.dispose();
-  });
-
-  test('total returns item count', () => {
-    const vm = create({
-      items: [{ id: '1' }, { id: '2' }, { id: '3' }],
-    });
-    expect(vm.total).toBe(3);
-    vm.dispose();
-  });
 });
 ```

package/agent-config/copilot/copilot-instructions.md

@@ -30,7 +30,7 @@ import { useLocal, useSingleton, useInstance, useModel, useField, useEvent, useE
 4. **One ViewModel per component** via `useLocal`. No `useEffect` for data loading — use `onInit()`.
 5. **No `useState`/`useMemo`/`useCallback`** — the ViewModel is the hook.
 6. **Components are declarative.** Read `state.x` for raw, `vm.x` for computed, `vm.async.x` for loading/error.
-7. **Collections are encapsulated.** ViewModels subscribe via `subscribeTo()` in `onInit()`. Components never import Collections.
+7. **Collections are encapsulated.** ViewModel getters read from collections directly — auto-tracking handles reactivity. Use `subscribeTo()` only for imperative side effects. Components never import Collections.
 8. **Services are stateless.** Accept `AbortSignal`, throw `HttpError`, no knowledge of ViewModels.
 9. **Pass `this.disposeSignal`** to every async call.
 10. **Lifecycle**: `construct → init() → use → dispose()`. Hooks auto-call `init()`.
@@ -39,35 +39,31 @@ import { useLocal, useSingleton, useInstance, useModel, useField, useEvent, useE
 
 ```typescript
 interface ItemState {
-  items: Item[];
   search: string;
 }
 
 class ItemsViewModel extends ViewModel<ItemState> {
   // --- Private fields ---
   private service = singleton(ItemService);
-  private collection = singleton(ItemsCollection);
+  collection = singleton(ItemsCollection);
 
   // --- Computed getters ---
+  get items(): Item[] {
+    return this.collection.items as Item[];
+  }
+
   get filtered(): Item[] {
-    const { items, search } = this.state;
-    if (!search) return items;
+    const { search } = this.state;
+    if (!search) return this.items;
     const q = search.toLowerCase();
-    return items.filter(i => i.name.toLowerCase().includes(q));
+    return this.items.filter(i => i.name.toLowerCase().includes(q));
   }
 
-  get total(): number { return this.state.items.length; }
+  get total(): number { return this.items.length; }
 
   // --- Lifecycle ---
   protected onInit() {
-    this.subscribeTo(this.collection, () => {
-      this.set({ items: this.collection.items });
-    });
-    if (this.collection.length > 0) {
-      this.set({ items: this.collection.items });
-    } else {
-      this.load();
-    }
+    if (this.collection.length === 0) this.load();
   }
 
   // --- Actions ---
@@ -87,7 +83,7 @@ class ItemsViewModel extends ViewModel<ItemState> {
 
 ```tsx
 function ItemsPage() {
-  const [state, vm] = useLocal(ItemsViewModel, { items: [], search: '' });
+  const [state, vm] = useLocal(ItemsViewModel, { search: '' });
   const { loading, error } = vm.async.load;
 
   return (
@@ -133,6 +129,7 @@ class UserService extends Service {
 ```typescript
 class UsersCollection extends Collection<UserState> {}
 // Thin subclass. Query logic in ViewModel getters.
+// Use reset() for full loads, upsert() for paginated/incremental loads.
 ```
 
 ## Model Pattern
@@ -181,7 +178,7 @@ async toggleStatus(id: string) {
   try {
     await this.service.update(id, { status: 'done' }, this.disposeSignal);
   } catch (e) {
-    if (!isAbortError(e)) rollback();
+    if (!isAbortError(e)) rollback(); // guard needed — rollback affects shared Collection
     throw e;
   }
 }
@@ -190,9 +187,11 @@ async toggleStatus(id: string) {
 ## Error Handling Layers
 
 1. **Async tracking** (automatic): Write happy path, read `vm.async.method.error`
-2. **Imperative events** (explicit): try/catch + `emit()` + **re-throw**
+2. **Imperative events** (explicit): try/catch + `emit()` + **re-throw**. No `isAbortError()` guard needed — `emit()` and `set()` are no-ops after dispose.
 3. **Error classification** (services): `throw HttpError`, `classifyError()`
 
+**`isAbortError()` rule:** Only needed in catch blocks that affect shared state (Collection rollbacks). Not needed for `set()`/`emit()` or methods without try/catch.
+
 ## Testing
 
 ```typescript
@@ -220,6 +219,7 @@ test('example', () => {
 - Manual try/catch for standard loads → async tracking handles it
 - Two-step setters with refilter calls → getters auto-recompute
 - Manual optimistic snapshot/restore → use `collection.optimistic()`
+- `reset()` for paginated/incremental loads → use `upsert()` to accumulate data
 - `useState`/`useMemo`/`useCallback` in connected components → ViewModel handles it
 
 ## Decision Framework