mvc-kit 2.12.5 → 2.13.0

package/agent-config/bin/postinstall.mjs

@@ -21,11 +21,12 @@ if (resolve(projectRoot) === ownPackageRoot) {
 }
 
 // If the developer previously opted in (files exist), auto-update them
-const skillFile = join(projectRoot, '.claude', 'skills', 'mvc-kit.md');
-// Also detect legacy rules file from older versions
+const skillDir = join(projectRoot, '.claude', 'skills', 'mvc-kit');
+// Also detect legacy file paths from older versions
+const legacySkillFile = join(projectRoot, '.claude', 'skills', 'mvc-kit.md');
 const legacyRulesFile = join(projectRoot, '.claude', 'rules', 'mvc-kit.md');
 
-if (existsSync(skillFile) || existsSync(legacyRulesFile)) {
+if (existsSync(skillDir) || existsSync(legacySkillFile) || existsSync(legacyRulesFile)) {
   try {
     const { installClaude } = await import('../lib/install-claude.mjs');
     installClaude(projectRoot);

package/agent-config/bin/setup.mjs

@@ -87,7 +87,11 @@ function setupClaude() {
     console.log(`    ${f}`);
   }
   console.log('');
-  console.log('  Skill:  /project:mvc-kit (framework reference, on-demand)');
+  console.log('  Skills:');
+  console.log('    mvc-kit          — framework reference (auto-loaded by Claude)');
+  console.log('    /mvc-kit-review  — review code for pattern adherence');
+  console.log('    /mvc-kit-scaffold — scaffold classes with correct patterns');
+  console.log('');
   console.log('  Agent:  mvc-kit-architect (architecture planning)\n');
 }
 

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

@@ -1,24 +1,27 @@
 ---
 name: mvc-kit-architect
 description: "Architecture planning agent for mvc-kit applications. Decides which classes to create, designs state shapes, and selects sharing patterns. Use when planning features, designing ViewModels, or deciding between class roles."
-model: sonnet
+model: opus
+tools: Read, Grep, Glob, Bash
+memory: project
+color: blue
+skills:
+  - mvc-kit-guide
 ---
 
 You are an architecture planning agent for applications built with **mvc-kit**, a TypeScript-first reactive state management library for React. You help developers plan features by deciding which classes to create, designing state shapes, and selecting sharing patterns.
 
 ## Documentation
 
-For detailed, up-to-date documentation on any class or hook, search the `.md` files colocated with source in `node_modules/mvc-kit/src/`. Read these when you need specifics beyond the summary tables below.
+The mvc-kit framework reference skill is preloaded into this agent's context. For deeper reference, read the supporting files in the mvc-kit skill directory (search for `.claude/skills/mvc-kit/` or `node_modules/mvc-kit/agent-config/claude-code/skills/guide/`):
 
-**Core classes:** `ViewModel.md`, `Model.md`, `Collection.md`, `PersistentCollection.md`, `Resource.md`, `Service.md`, `EventBus.md`, `Channel.md`, `Controller.md`, `Trackable.md`, `singleton.md`
-**Composable helpers:** `Sorting.md`, `Pagination.md`, `Selection.md`, `Feed.md`, `Pending.md`, `produceDraft.md`
-**React hooks:** `react/use-local.md`, `react/use-instance.md`, `react/use-singleton.md`, `react/use-model.md`, `react/use-event-bus.md`, `react/use-teardown.md`
-**Headless components:** `react/components/DataTable.md`, `react/components/CardList.md`, `react/components/InfiniteScroll.md`
-
-Additional reference files in `node_modules/mvc-kit/agent-config/claude-code/skills/guide/`:
 - `api-reference.md` — Full API reference for all classes and hooks
 - `patterns.md` — Prescribed patterns with code examples
 - `anti-patterns.md` — Anti-patterns to reject with fixes
+- `recipes.md` — Composition recipes for real-world features
+- `testing.md` — Testing patterns
+
+For detailed per-class documentation, search the `.md` files colocated with source in `node_modules/mvc-kit/src/`.
 
 ## Core Classes
 

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

@@ -1,8 +1,7 @@
 ---
-name: guide
-description: "mvc-kit framework reference — class roles, architecture rules, React hooks, and decision framework. Auto-loaded when mvc-kit imports are detected."
-invocable_by:
-  - model
+name: mvc-kit-guide
+description: "mvc-kit framework reference — class roles, architecture rules, React hooks, and decision framework. Use when working with mvc-kit imports or planning mvc-kit features."
+user-invocable: false
 ---
 
 # mvc-kit Framework Reference
@@ -79,8 +78,22 @@ Import core from `mvc-kit`, hooks from `mvc-kit/react`.
 2. State survives route changes → **Pattern B** (singleton ViewModel via `useSingleton`)
 3. Different concerns, shared data → **Pattern C** (separate ViewModels, shared Collection)
 
+## Common Compositions
+
+Most features combine multiple classes. These are the key composition patterns:
+
+- **Data table**: ViewModel + Collection/Resource + Sorting + Pagination + Selection → getter pipeline (`items → filtered → sorted → paged`). Always reset pagination when filters change.
+- **Infinite scroll / chat**: ViewModel + Feed + Service → cursor-based server pagination with `appendPage()`. Use `AbortSignal.any()` for per-call cancellation on rapid user interactions.
+- **Form with validation**: ViewModel creates Model in `onInit()`, disposes in `onDispose()`. Guard `save()` on `model.valid`. Call `model.commit()` after successful save.
+- **Two-tier events**: ViewModel `.emit()` for component reactions (navigate, show inline error). EventBus `.emit()` for app-wide side effects (toasts, analytics).
+- **Singleton with DEFAULT_STATE**: `static DEFAULT_STATE` lets `singleton()` and `useSingleton()` work without repeating initial state at every call site.
+
+For full composition recipes with code, see [recipes.md](recipes.md).
+
 ## Supporting Files
 
-For complete API details, see `api-reference.md` in this skill directory.
-For prescribed patterns with code examples, see `patterns.md`.
-For anti-pattern rejection list with fixes, see `anti-patterns.md`.
+- [api-reference.md](api-reference.md) — Full API reference for all classes and hooks
+- [patterns.md](patterns.md) — Prescribed patterns with code examples
+- [anti-patterns.md](anti-patterns.md) — Anti-patterns to reject with fixes
+- [recipes.md](recipes.md) — Composition recipes for real-world features
+- [testing.md](testing.md) — Testing patterns (teardownAll, async assertions, memoization verification)

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

@@ -67,6 +67,16 @@ The setter changes state → React re-renders → getters recompute. No manual r
 
 All classes auto-bind methods, so they can be passed point-free as callbacks (`onFoo={vm.foo}`, `onClick={sorting.toggle}`, `onSubmit={model.commit}`).
 
+### Reset Pagination on Filter Changes
+
+When a ViewModel uses Pagination, **every setter that changes filter/sort criteria must call `pagination.reset()`**. Otherwise the user can be on an invalid page (e.g., page 5 when results shrink to 2 pages).
+
+```typescript
+setSearch(search: string) { this.set({ search }); this.pagination.reset(); }
+setRoleFilter(roleFilter: State['roleFilter']) { this.set({ roleFilter }); this.pagination.reset(); }
+setStatusFilter(statusFilter: State['statusFilter']) { this.set({ statusFilter }); this.pagination.reset(); }
+```
+
 ---
 
 ## Encapsulating Collections
@@ -271,6 +281,8 @@ class UsersListVM extends ViewModel<FilterState> {
 ```
 
 **Key points:**
+- Helpers are `readonly` **public** properties — DataTable and other headless components need direct access to call `sorting.toggle()`, `pagination.goNext()`, `selection.toggle()`.
+- Helpers extend `Trackable` and have `subscribe()` — they're **auto-tracked** when declared as ViewModel properties. Getters that read helper state (e.g., `sorting.sorts`) recompute automatically when the helper changes. No `subscribeTo()` needed.
 - Helpers are plain classes, not ViewModels — no `init()` needed.
 - `apply()` is a pure pipeline — chain them in getters: `pagination.apply(sorting.apply(filtered))`.
 - `Selection` is key-based — works with any ID type.

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

@@ -0,0 +1,510 @@
+# mvc-kit Composition Recipes
+
+Real-world features combine multiple classes. These recipes show the correct composition patterns.
+
+---
+
+## Recipe 1: Data Table with Filters, Sorting, Pagination, and Selection
+
+The most common pattern. ViewModel owns helpers as `readonly` public properties. Getters form a pipeline: `items → filtered → sorted → paged`. DataTable receives helper instances directly.
+
+```typescript
+interface UsersState {
+  search: string;
+  roleFilter: 'all' | 'admin' | 'manager' | 'viewer';
+  statusFilter: 'all' | 'active' | 'inactive';
+}
+
+class UsersViewModel extends ViewModel<UsersState> {
+  // Helpers are readonly public — DataTable needs direct access
+  readonly sorting = new Sorting<UserState>({ sorts: [{ key: 'firstName', direction: 'asc' }] });
+  readonly pagination = new Pagination({ pageSize: 25 });
+  readonly selection = new Selection<string>();
+
+  private users = singleton(UsersResource);
+
+  // --- Computed getters (pipeline) ---
+
+  get items(): UserState[] {
+    return this.users.items as UserState[];
+  }
+
+  get filtered(): UserState[] {
+    const { search, roleFilter, statusFilter } = this.state;
+    let result = this.items;
+    if (search) {
+      const q = search.toLowerCase();
+      result = result.filter(u =>
+        u.firstName.toLowerCase().includes(q) ||
+        u.lastName.toLowerCase().includes(q) ||
+        u.email.toLowerCase().includes(q),
+      );
+    }
+    if (roleFilter !== 'all') result = result.filter(u => u.role === roleFilter);
+    if (statusFilter !== 'all') result = result.filter(u => u.status === statusFilter);
+    return result;
+  }
+
+  get sorted(): UserState[] {
+    return this.sorting.apply(this.filtered);
+  }
+
+  get paged(): UserState[] {
+    return this.pagination.apply(this.sorted);
+  }
+
+  get total(): number { return this.items.length; }
+  get filteredCount(): number { return this.filtered.length; }
+  get hasResults(): boolean { return this.filtered.length > 0; }
+  get isEmpty(): boolean { return this.total > 0 && !this.hasResults; }
+
+  get selectedItems(): UserState[] {
+    return this.selection.selectedFrom(this.filtered, u => u.id);
+  }
+
+  // --- Lifecycle ---
+
+  protected onInit() {
+    if (this.users.length === 0) this.users.loadAll();
+  }
+
+  // --- Actions ---
+
+  async bulkDelete() {
+    const items = this.selectedItems;
+    if (items.length === 0) return;
+    for (const item of items) {
+      await this.users.deleteItem(item.id);
+    }
+    this.selection.clear();
+  }
+
+  // --- Setters (MUST reset pagination on filter changes) ---
+
+  setSearch(search: string) { this.set({ search }); this.pagination.reset(); }
+  setRoleFilter(roleFilter: UsersState['roleFilter']) { this.set({ roleFilter }); this.pagination.reset(); }
+  setStatusFilter(statusFilter: UsersState['statusFilter']) { this.set({ statusFilter }); this.pagination.reset(); }
+}
+```
+
+```tsx
+function UsersPage() {
+  const [state, vm] = useLocal(UsersViewModel, { search: '', roleFilter: 'all', statusFilter: 'all' });
+  const { loading, error } = vm.async.loadAll ?? {};
+
+  return (
+    <DataTable
+      items={vm.paged}
+      columns={columns}
+      sort={vm.sorting}
+      selection={vm.selection}
+      pagination={vm.pagination}
+      paginationTotal={vm.filteredCount}
+      loading={loading}
+      error={error?.message}
+    />
+  );
+}
+```
+
+**Key rules:**
+- Helpers are `readonly` public properties — not private, not methods
+- Pipeline: each getter composes the previous one (`sorted` calls `this.filtered`)
+- **Always reset pagination when filters change** — otherwise the user can be on an invalid page
+- Selection operates on `filtered`, not `paged` (select across pages)
+- DataTable receives helper instances directly (duck-typed, not wrapped)
+- `paginationTotal` is `filteredCount`, not `total` (pagination needs the filtered count)
+
+---
+
+## Recipe 2: Infinite Scroll with Cursor-Based Server Pagination
+
+Feed tracks cursor + hasMore for server-side paginated data. InfiniteScroll triggers loading more.
+
+```typescript
+interface ThreadState {
+  conversationId: string;
+  draft: string;
+}
+
+interface ThreadEvents {
+  messageSent: { conversationId: string };
+}
+
+class MessageThreadViewModel extends ViewModel<ThreadState, ThreadEvents> {
+  readonly feed = new Feed<MessageState>();
+
+  private service = singleton(MessageService);
+  private _loadController: AbortController | null = null;
+
+  // --- Computed getters ---
+
+  get sortedMessages(): MessageState[] {
+    return [...this.feed.items].sort(
+      (a, b) => new Date(a.sentAt).getTime() - new Date(b.sentAt).getTime(),
+    );
+  }
+
+  get canSend(): boolean {
+    return this.state.draft.trim().length > 0;
+  }
+
+  // --- Lifecycle ---
+
+  protected onInit() {
+    // Load conversation on init — no useEffect needed.
+    // useLocal deps recreate the VM when conversationId changes, triggering onInit again.
+    this.loadConversation(this.state.conversationId);
+  }
+
+  // --- Actions ---
+
+  async loadConversation(conversationId: string) {
+    // Per-call cancellation: abort previous in-flight load
+    this._loadController?.abort();
+    this._loadController = new AbortController();
+
+    this.feed.reset();
+
+    // Compose signals: abort if component unmounts OR user switches conversations
+    const page = await this.service.getMessages(
+      conversationId,
+      AbortSignal.any([this.disposeSignal, this._loadController.signal]),
+    );
+    this.feed.appendPage(page);
+  }
+
+  async loadOlderMessages() {
+    if (!this.feed.hasMore) return;
+
+    const page = await this.service.getMessages(
+      this.state.conversationId,
+      this.disposeSignal,
+      { cursor: this.feed.cursor },
+    );
+    this.feed.appendPage(page);
+  }
+
+  async sendMessage() {
+    const text = this.state.draft.trim();
+    if (!text) return;
+
+    const message = await this.service.sendMessage(
+      this.state.conversationId,
+      text,
+      this.disposeSignal,
+    );
+    this.feed.push(message);
+    this.set({ draft: '' });
+    this.emit('messageSent', { conversationId: this.state.conversationId });
+  }
+
+  // --- Setters ---
+
+  setDraft(draft: string) { this.set({ draft }); }
+}
+```
+
+```tsx
+function MessageThread({ conversationId }: { conversationId: string }) {
+  // deps: [conversationId] — recreates VM when conversation changes, onInit() loads new data
+  const [state, vm] = useLocal(MessageThreadViewModel, { conversationId, draft: '' }, [conversationId]);
+  const { loading } = vm.async.loadConversation ?? {};
+  const { loading: loadingMore } = vm.async.loadOlderMessages ?? {};
+
+  return (
+    <div>
+      <InfiniteScroll
+        hasMore={vm.feed.hasMore}
+        loading={loadingMore}
+        onLoadMore={() => vm.loadOlderMessages()}
+        direction="up"
+      >
+        {vm.sortedMessages.map(msg => <Message key={msg.id} message={msg} />)}
+      </InfiniteScroll>
+      <input value={state.draft} onChange={e => vm.setDraft(e.target.value)} />
+      <button disabled={!vm.canSend} onClick={() => vm.sendMessage()}>Send</button>
+    </div>
+  );
+}
+```
+
+**Key rules:**
+- **No `useEffect` for data loading** — put `conversationId` in state, load in `onInit()`. `useLocal` deps recreate the VM when props change, triggering `onInit()` again.
+- Service returns `FeedPage<T>`: `{ items: T[], hasMore: boolean, cursor?: string }`
+- Call `feed.appendPage(page)` to accumulate items and update cursor/hasMore
+- Pass `feed.cursor` when requesting the next page
+- **Per-call cancellation**: `AbortSignal.any([this.disposeSignal, controller.signal])` aborts if EITHER the component unmounts or the user switches context
+- `disposeSignal` alone is NOT enough for rapid user interactions (switching conversations, search-as-you-type)
+- `direction="up"` for chat UIs (loads older items at top)
+
+---
+
+## Recipe 3: Form with Model Validation
+
+ViewModel creates and owns a Model instance. Model handles validation, dirty tracking, commit/rollback. ViewModel handles async save.
+
+```typescript
+interface ProfileState {
+  location: LocationState | null;
+  locationId: string;
+}
+
+interface ProfileEvents {
+  saved: { id: string };
+}
+
+class LocationProfileViewModel extends ViewModel<ProfileState, ProfileEvents> {
+  // Model is created dynamically after data loads — starts null
+  public model: LocationFormModel | null = null;
+
+  private service = singleton(LocationService);
+  private collection = singleton(LocationsCollection);
+  private bus = singleton(AppEventBus);
+
+  // --- Computed getters ---
+
+  get canSave(): boolean {
+    return this.model !== null && this.model.valid && this.model.dirty;
+  }
+
+  // --- Lifecycle ---
+
+  protected onInit() {
+    this.load();
+  }
+
+  protected onDispose() {
+    // Model has its own lifecycle — must dispose
+    this.model?.dispose();
+  }
+
+  // --- Actions ---
+
+  async load() {
+    const location = await this.service.getById(this.state.locationId, this.disposeSignal);
+
+    this.model = new LocationFormModel({
+      name: location.name,
+      type: location.type,
+      city: location.city,
+      capacity: location.capacity,
+    });
+    this.set({ location });
+  }
+
+  async save() {
+    if (!this.model || !this.model.valid) return;
+
+    try {
+      const updated = await this.service.update(
+        this.state.locationId,
+        this.model.state,
+        this.disposeSignal,
+      );
+      this.collection.update(this.state.locationId, updated);
+      this.model.commit(); // Reset dirty state after successful save
+      this.set({ location: updated });
+      this.emit('saved', { id: updated.id });
+      this.bus.emit('toast:show', { message: 'Location saved', severity: 'success' });
+    } catch (e) {
+      if (!isAbortError(e)) {
+        this.bus.emit('toast:show', { message: 'Failed to save', severity: 'error' });
+      }
+      throw e; // Re-throw so async tracking captures it
+    }
+  }
+}
+```
+
+```tsx
+function LocationProfile({ locationId }: { locationId: string }) {
+  const [state, vm] = useLocal(LocationProfileViewModel, { location: null, locationId });
+  const { loading: saving } = vm.async.save ?? {};
+
+  useEvent(vm, 'saved', () => navigate('/locations'));
+
+  if (!vm.model) return <Spinner />;
+
+  return (
+    <form onSubmit={e => { e.preventDefault(); vm.save(); }}>
+      <ModelFields model={vm.model} />
+      <button disabled={!vm.canSave || saving}>
+        {saving ? 'Saving...' : 'Save'}
+      </button>
+    </form>
+  );
+}
+```
+
+**Key rules:**
+- Model is created in `onInit()` (or after async load), disposed in `onDispose()` — **always pair create/dispose**
+- Guard `save()` with `model.valid` — never submit invalid data
+- Call `model.commit()` after successful save to reset dirty tracking
+- Use `model.rollback()` for cancel/discard
+- For large forms: use `useModelRef(factory)` + `useField(model, 'fieldName')` for surgical per-field re-renders
+- ViewModel events (`emit('saved')`) for navigation; EventBus for app-wide toasts
+
+---
+
+## Recipe 4: Two-Tier Event System
+
+ViewModel events are for "this instance did something" (component reactions). EventBus events are for "something happened app-wide" (toasts, analytics, navigation).
+
+```typescript
+// App-wide EventBus — singleton
+interface AppEvents {
+  'toast:show': { message: string; severity: 'success' | 'error' | 'info' };
+  'analytics:track': { event: string; properties?: Record<string, unknown> };
+}
+
+class AppEventBus extends EventBus<AppEvents> {}
+
+// ViewModel with both tiers
+interface AuthState { user: UserState | null; isAuthenticated: boolean; }
+interface AuthEvents { loginFailed: { message: string }; }
+
+class AuthViewModel extends ViewModel<AuthState, AuthEvents> {
+  static DEFAULT_STATE: AuthState = { user: null, isAuthenticated: false };
+
+  private authService = singleton(AuthService);
+  private bus = singleton(AppEventBus);
+
+  async login(email: string, password: string) {
+    try {
+      const user = await this.authService.login(email, password, this.disposeSignal);
+      this.set({ user, isAuthenticated: true });
+      // App-wide: toast notification
+      this.bus.emit('toast:show', { message: `Welcome, ${user.firstName}!`, severity: 'success' });
+      // App-wide: analytics
+      this.bus.emit('analytics:track', { event: 'login', properties: { role: user.role } });
+    } catch (e) {
+      if (!isAbortError(e)) {
+        // Instance-scoped: only the login form cares about this
+        this.emit('loginFailed', { message: classifyError(e).message });
+      }
+      throw e;
+    }
+  }
+}
+```
+
+```tsx
+// Login form listens to ViewModel events
+function LoginPage() {
+  const [state, vm] = useLocal(AuthViewModel);
+  useEvent(vm, 'loginFailed', ({ message }) => setErrorBanner(message));
+  // ...
+}
+
+// Toast component listens to EventBus events (app root)
+function ToastProvider() {
+  const bus = useInstance(singleton(AppEventBus));
+  useEvent(bus, 'toast:show', ({ message, severity }) => showToast(message, severity));
+  // ...
+}
+```
+
+**When to use which:**
+| Use | For | Example |
+|-----|-----|---------|
+| ViewModel events (`this.emit()`) | Component-scoped reactions | `saved` → navigate, `loginFailed` → show error |
+| EventBus (`bus.emit()`) | Cross-cutting, app-wide effects | Toasts, analytics, logging |
+
+**Key rules:**
+- ViewModel events use the second generic: `ViewModel<State, Events>`
+- Components listen via `useEvent(vm, 'eventName', handler)`
+- EventBus is a singleton — one per event domain (e.g., `AppEventBus`)
+- Use `listenTo(bus, event, handler)` inside ViewModels for auto-cleanup
+
+---
+
+## Recipe 5: Resource with Singleton DEFAULT_STATE
+
+Singleton ViewModels that share state across routes need `static DEFAULT_STATE` so `singleton()` and `useSingleton()` work without repeating initial state at every call site.
+
+```typescript
+// Resource — thin subclass, async methods for CRUD
+class UsersResource extends Resource<UserState> {
+  private api = singleton(UserService);
+
+  async loadAll() {
+    const data = await this.api.getAll(this.disposeSignal);
+    this.reset(data);
+  }
+}
+
+// Singleton ViewModel with DEFAULT_STATE
+class AuthViewModel extends ViewModel<AuthState> {
+  static DEFAULT_STATE: AuthState = { user: null, isAuthenticated: false };
+  // ...
+}
+
+// Usage — no args needed at call sites
+const auth = singleton(AuthViewModel);              // bare singleton (no auto-init)
+const [state, auth] = useSingleton(AuthViewModel);  // React (auto-init + subscribe)
+```
+
+**Key rules:**
+- `static DEFAULT_STATE` is checked at runtime by `singleton()` when no args passed
+- `singleton()` does NOT call `init()` — use `useSingleton()` in React, or call `init()` manually
+- `useSingleton()` auto-calls `init()` and subscribes to state changes
+- Singletons persist across route changes — use `useTeardown(...Classes)` to dispose when a route unmounts
+- Smart-init in `onInit()`: `if (this.collection.length === 0) this.load()` prevents re-fetching on re-mount
+
+---
+
+## Recipe 6: Error Handling with isAbortError
+
+Async tracking handles errors automatically. Manual try/catch is only needed when you have **side effects** in the catch block (toasts, event emissions, collection rollbacks).
+
+```typescript
+class OrderViewModel extends ViewModel<OrderState> {
+  private resource = singleton(OrdersResource);
+  private bus = singleton(AppEventBus);
+
+  // Simple load — NO try/catch needed (async tracking handles it)
+  async load() {
+    const orders = await this.resource.loadAll();
+  }
+
+  // Save with side effects — try/catch + isAbortError guard
+  async save(order: OrderDraft) {
+    try {
+      const saved = await this.resource.save(order);
+      this.bus.emit('toast:show', { message: 'Order saved', severity: 'success' });
+    } catch (e) {
+      // Guard shared-state side effects against AbortError
+      if (!isAbortError(e)) {
+        this.bus.emit('toast:show', { message: 'Save failed', severity: 'error' });
+      }
+      throw e; // ALWAYS re-throw — async tracking needs it
+    }
+  }
+
+  // Optimistic update — isAbortError guards the rollback
+  async toggleStatus(id: string) {
+    const order = this.resource.get(id)!;
+    const newStatus = order.status === 'active' ? 'inactive' : 'active';
+
+    const restore = this.resource.optimistic(id, { ...order, status: newStatus });
+    try {
+      const updated = await this.service.update(id, { status: newStatus }, this.disposeSignal);
+      this.resource.update(id, updated);
+    } catch (e) {
+      if (!isAbortError(e)) restore(); // Only rollback if NOT an abort
+      throw e;
+    }
+  }
+}
+```
+
+**When you need `isAbortError()`:**
+- Before emitting events in catch blocks
+- Before rolling back optimistic updates
+- Before any shared-state side effect in catch
+
+**When you DON'T need it:**
+- `set()` — no-op after dispose
+- `emit()` — guards on disposed state internally
+- Simple loads with no catch block — async tracking handles everything