mvc-kit 2.10.1 → 2.11.0

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

@@ -18,19 +18,50 @@ You are an architecture planning agent for applications built with **mvc-kit**,
 | `EventBus<E>` | Typed pub/sub for cross-cutting events | Singleton |
 | `Channel<M>` | Persistent connection (WebSocket/SSE) with auto-reconnect | Singleton |
 | `Controller` | Stateless multi-ViewModel orchestrator (rare) | Component-scoped |
+| `PersistentCollection<T>` | Collection + storage persistence (WebStorage, IndexedDB, RN) | Singleton |
+
+### Composable Helpers
+
+| Helper | Role | Ownership |
+|--------|------|-----------|
+| `Sorting<T>` | Multi-column sort state + `apply()` pipeline | ViewModel property |
+| `Pagination` | Page/pageSize state + `apply()` slicing | ViewModel property |
+| `Selection<K>` | Key-based selection set with toggle/select-all | ViewModel property |
+| `Feed<T>` | Cursor + hasMore + item accumulation for server pagination | ViewModel property |
+| `Pending<K, Meta?>` | Per-item operation queue with retry + status tracking | Resource property |
 
 ## Decision Framework
 
 ### Which class?
 1. Holds UI state for a component? → **ViewModel**
 2. Single entity with validation? → **Model**
-3. List of entities with CRUD? → **Collection**
+3. List of entities with CRUD (no API calls)? → **Collection**
 4. List of entities with CRUD + API loading + loading/error tracking? → **Resource**
-5. Wraps raw `fetch()` with error handling? → **Service** (skip if you have a typed API client)
-6. Broadcasts cross-cutting events? → **EventBus**
-7. Persistent connection? → **Channel**
-8. Coordinates multiple ViewModels? → **Controller** (rare)
-9. None of the above → plain utility function
+5. Need to persist Collection to storage? → **PersistentCollection** (WebStorage, IndexedDB, or NativeCollection)
+6. Wraps raw `fetch()` with error handling? → **Service** (skip if you have a typed API client)
+7. Broadcasts cross-cutting events? → **EventBus**
+8. Persistent connection? → **Channel**
+9. Coordinates multiple ViewModels? → **Controller** (rare)
+10. None of the above → plain utility function
+
+### Collection vs Resource vs Collection + Service?
+- **Collection alone** — in-memory reactive list with no server interaction (e.g., local cart, selected items)
+- **Resource** — replaces the Collection + Service + manual cache check pattern. Preferred when you need a shared data cache with API loading. Each async method gets independent tracking.
+- **Collection + separate Service** — only when the Collection is shared across multiple Resources or a Channel, or when you need the Service for composing calls, retries, or auth management
+- **Resource + external Collection** — when Resource and Channel feed the same store: `super(singleton(SharedCollection))`
+
+### PersistentCollection vs Collection?
+- Need data to survive page refresh? → **PersistentCollection**
+- High-churn data (search results, real-time feeds)? → **Collection** (persistence adds I/O overhead)
+- Entity caches, settings, cart? → **PersistentCollection**
+- Which adapter? localStorage (auto-hydrate, blocking) → **WebStorageCollection**. Large datasets → **IndexedDBCollection**. React Native → **NativeCollection**.
+
+### Which composable helper?
+- Need sortable columns? → **Sorting\<T\>** (ViewModel property, auto-tracked)
+- Need client-side paging? → **Pagination** (ViewModel property, auto-tracked)
+- Need multi-select? → **Selection\<K\>** (ViewModel property, auto-tracked)
+- Need cursor-based server pagination? → **Feed\<T\>** (ViewModel property, auto-tracked)
+- Need per-item retry queue? → **Pending\<K, Meta?\>** (Resource property, survives component unmount)
 
 ### Which sharing pattern?
 - "Can the parent own one ViewModel and pass props?" → **Pattern A** (default)

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

@@ -8,12 +8,12 @@ import { ViewModel, Model, Collection, PersistentCollection, Resource, Controlle
 import { Sorting, Pagination, Selection, Feed, Pending } from 'mvc-kit';
 import { singleton, hasSingleton, teardown, teardownAll } from 'mvc-kit';
 import { HttpError, isAbortError, classifyError } from 'mvc-kit';
-import type { Subscribable, Disposable, Initializable, Listener, Updater, ValidationErrors, TaskState, AppError, AsyncMethodKeys, ResourceAsyncMethodKeys, ChannelStatus } from 'mvc-kit';
+import type { Subscribable, Disposable, Initializable, Listener, Updater, ValidationErrors, TaskState, EventSource, EventPayload, AppError, AsyncMethodKeys, ResourceAsyncMethodKeys, ChannelStatus, SortDescriptor, FeedPage, PendingOperation, PendingEntry } from 'mvc-kit';
 
 // React hooks and headless components
 import { useLocal, useSingleton, useInstance, useModel, useModelRef, useField, useEvent, useEmit, useResolve, useTeardown, Provider } from 'mvc-kit/react';
 import { DataTable, CardList, InfiniteScroll } from 'mvc-kit/react';
-import type { StateOf, ItemOf, SingletonClass, ProviderRegistry, ModelHandle, FieldHandle, ProviderProps } from 'mvc-kit/react';
+import type { StateOf, ItemOf, SingletonClass, ProviderRegistry, ModelHandle, FieldHandle, ProviderProps, Column, SortHeaderProps, SelectionState, SelectionHelper, PaginationState, PaginationHelper, PaginationInfo, SortingHelper, AsyncStateProps, DataTableProps, CardListProps, InfiniteScrollProps } from 'mvc-kit/react';
 
 // Web storage adapters
 import { WebStorageCollection, IndexedDBCollection } from 'mvc-kit/web';
@@ -558,6 +558,7 @@ useTeardown(UserViewModel, CartViewModel);
 ## Interfaces
 
 ```typescript
+// Core interfaces
 interface Subscribable<S> { state: S; subscribe(listener: Listener<S>): () => void; dispose(): void; disposeSignal: AbortSignal; }
 interface Disposable { disposed: boolean; disposeSignal: AbortSignal; dispose(): void; }
 interface Initializable { initialized: boolean; init(): void; }
@@ -565,6 +566,27 @@ type Listener<S> = (state: S, prev: S) => void;
 type Updater<S> = (prev: S) => Partial<S>;
 type ValidationErrors<S> = Partial<Record<keyof S, string>>;
 interface TaskState { readonly loading: boolean; readonly error: string | null; readonly errorCode: string | null; }
+
+// Event types
+type EventSource = Record<string, any>;
+type EventPayload<E extends EventSource, K extends keyof E> = E[K];
+
+// Helper types
+interface SortDescriptor { key: string; direction: 'asc' | 'desc'; }
+interface FeedPage<T> { items: T[]; cursor: string | null; hasMore: boolean; }
+interface PendingOperation<Meta = unknown> { status: 'active' | 'retrying' | 'failed'; attempts: number; error: unknown | null; meta: Meta | null; }
+interface PendingEntry<K = string, Meta = unknown> extends PendingOperation<Meta> { readonly id: K; }
+
+// React component types (duck-typed interfaces for DataTable helper pass-through)
+interface Column<T> { key: string; header: ReactNode; render: (item: T, index: number) => ReactNode; sortable?: boolean; width?: string; align?: 'left' | 'center' | 'right'; }
+interface SortHeaderProps { active: boolean; direction: 'asc' | 'desc'; index: number; onToggle: () => void; }
+interface SelectionState<K = string | number> { selected: ReadonlySet<K>; onToggle: (key: K) => void; onToggleAll: (allKeys: K[]) => void; }
+interface SelectionHelper { readonly selected: ReadonlySet<any>; toggle(key: any): void; toggleAll(allKeys: any[]): void; }
+interface PaginationState { page: number; total: number; onPageChange: (page: number) => void; }
+interface PaginationHelper { readonly page: number; readonly pageSize: number; setPage(page: number): void; }
+interface PaginationInfo { page: number; pageCount: number; total: number; pageSize: number; hasPrev: boolean; hasNext: boolean; goToPage: (p: number) => void; goPrev: () => void; goNext: () => void; }
+interface SortingHelper { readonly sorts: readonly SortDescriptor[]; toggle(key: string): void; }
+interface AsyncStateProps { loading?: boolean; error?: string | null; }
 ```
 
 ## Dev Mode (`__MVC_KIT_DEV__`)

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

@@ -561,6 +561,155 @@ test('filtered getter applies search', () => {
 
 ---
 
+## useInstance Pattern
+
+Subscribe to an existing ViewModel or Subscribable without managing its lifecycle. Useful when a parent passes a ViewModel as a prop to a child that needs reactive updates.
+
+```tsx
+function StatusIndicator({ vm }: { vm: DashboardViewModel }) {
+  const state = useInstance(vm);
+  return <span>{state.status}</span>;
+}
+```
+
+No init/dispose — the caller manages the instance lifecycle. For singletons, prefer `useSingleton` which handles both lifecycle and subscription.
+
+---
+
+## useEmit Pattern
+
+Get a stable emit function for an EventBus. Useful in components that only emit events without subscribing. The bus typically comes from a ViewModel property or `useResolve`.
+
+```tsx
+function QuickAction({ bus, itemId }: { bus: AppEventBus; itemId: string }) {
+  const emit = useEmit(bus);
+
+  return (
+    <button onClick={() => emit('item:selected', { id: itemId })}>
+      Select
+    </button>
+  );
+}
+```
+
+---
+
+## useModelRef + useField Pattern
+
+For large forms, `useModelRef` avoids re-rendering the parent on every keystroke. Each `useField` subscribes to a single field — only that input re-renders.
+
+```tsx
+function ProfileForm() {
+  const model = useModelRef(() => new ProfileModel({ name: '', email: '', bio: '' }));
+
+  return (
+    <form onSubmit={() => model.commit()}>
+      <NameField model={model} />
+      <EmailField model={model} />
+      <BioField model={model} />
+      <button disabled={!model.valid}>Save</button>
+    </form>
+  );
+}
+
+function NameField({ model }: { model: ProfileModel }) {
+  const { value, error, set } = useField(model, 'name');
+  return (
+    <div>
+      <input value={value} onChange={e => set(e.target.value)} />
+      {error && <span className="error">{error}</span>}
+    </div>
+  );
+}
+```
+
+`useModelRef` returns the model directly (no `[state, model]` tuple) — it manages lifecycle (init/dispose) but doesn't subscribe. The parent never re-renders from model changes.
+
+---
+
+## useTeardown Pattern
+
+Teardown singletons when a route or page unmounts. Frees resources for ViewModels that are no longer needed.
+
+```tsx
+function AdminPage() {
+  useTeardown(AdminViewModel, AdminStatsResource);
+
+  const [state, vm] = useSingleton(AdminViewModel);
+  return <AdminDashboard state={state} vm={vm} />;
+}
+```
+
+When `AdminPage` unmounts, both singletons are disposed and removed from the registry. Next mount creates fresh instances.
+
+---
+
+## Controller Pattern
+
+Stateless orchestrator for coordinating shared singletons (Resources, Collections, EventBus). Use when cross-cutting logic doesn't belong to any single ViewModel.
+
+```typescript
+class DashboardController extends Controller {
+  private ordersResource = singleton(OrdersResource);
+  private notificationsResource = singleton(NotificationsResource);
+  private bus = singleton(AppEventBus);
+
+  protected onInit() {
+    this.listenTo(this.bus, 'order:completed', ({ orderId }) => {
+      this.ordersResource.reload();
+      this.notificationsResource.addNotification(`Order ${orderId} completed`);
+    });
+  }
+}
+```
+
+```tsx
+function DashboardPage() {
+  useLocal(() => new DashboardController());
+  return (
+    <div>
+      <OrdersPanel />
+      <NotificationsPanel />
+    </div>
+  );
+}
+```
+
+Controllers are rare — prefer parent ViewModel with props (Pattern A) when possible.
+
+---
+
+## PersistentCollection Lifecycle
+
+```typescript
+// WebStorageCollection: auto-hydrates (synchronous localStorage)
+class CartCollection extends WebStorageCollection<CartItem> {
+  protected readonly storageKey = 'cart';
+}
+
+// ViewModel — no hydrate() needed
+protected onInit() {
+  if (this.collection.length === 0) this.loadFromServer();
+}
+```
+
+```typescript
+// IndexedDBCollection: requires async hydrate()
+class MessagesCollection extends IndexedDBCollection<Message> {
+  protected readonly storageKey = 'messages';
+}
+
+// ViewModel — must hydrate before accessing data
+protected async onInit() {
+  await this.collection.hydrate();
+  if (this.collection.length === 0) this.loadFromServer();
+}
+```
+
+Mutations persist automatically after hydration. Override `serialize()`/`deserialize()` for custom encoding. Override `onPersistError()` for error handling.
+
+---
+
 ## Error Handling Layers
 
 1. **Async tracking** (automatic) — write happy path, read `vm.async.method.error`

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

@@ -75,6 +75,73 @@
 
 ---
 
+## Resource Checks (6)
+
+### Critical
+1. **Thin subclass** — Resource should define async methods for CRUD. Use inherited Collection mutations (`reset`, `upsert`, `add`, `update`, `remove`) — don't re-implement them.
+
+### Warning
+2. **No pass-through Service** — If wrapping a typed API client (RPC, tRPC, GraphQL codegen) with zero added value, call it directly from Resource.
+3. **`onInit()` for initial load** — Resource should load data in `onInit()` with smart-init pattern (`if (this.length === 0)`).
+4. **Pending on Resource, not ViewModel** — `Pending` helper must live on the singleton Resource so operations survive component unmount.
+5. **Dispose owned helpers** — If Resource owns a `Pending`, dispose it in `onDispose()`.
+
+### Suggestion
+6. **External Collection injection** — When Resource + Channel feed the same data store, inject a shared Collection via `super(singleton(SharedCollection))`.
+
+---
+
+## Model Checks (4)
+
+### Critical
+1. **Validation in `validate()`** — All validation logic belongs in the `validate(state)` override, not in setters or external code.
+
+### Warning
+2. **Field-level errors** — `validate()` should return `Partial<Record<keyof S, string>>` with per-field messages, not a single error string.
+3. **Dirty tracking** — Use `commit()` to set baseline after save, `rollback()` to revert. Don't manually track dirty state in a separate field.
+
+### Suggestion
+4. **`useModelRef` + `useField` for large forms** — For forms with many fields, use `useModelRef` (no subscription) with `useField` per input for surgical re-renders.
+
+---
+
+## EventBus Checks (4)
+
+### Critical
+1. **Typed event map** — EventBus must have a typed generic `EventBus<E>` with explicit event names and payloads.
+2. **Use `listenTo()` over `addCleanup(bus.on(...))`** — `listenTo` is reset-safe and auto-cleans up on dispose.
+
+### Warning
+3. **No state in EventBus** — EventBus is for fire-and-forget signals (toasts, navigation, analytics). State belongs in ViewModel or Collection.
+4. **Prefer ViewModel events for component-scoped signals** — Use the second generic `ViewModel<S, E>` for events that belong to a single ViewModel. Use EventBus only for cross-cutting, app-wide events.
+
+---
+
+## Channel Checks (4)
+
+### Critical
+1. **Implement `connect()` and `disconnect()`** — Channel requires abstract method overrides for connection management.
+2. **Use `listenTo()` for subscriptions** — ViewModel should use `listenTo(channel, event, handler)`, not `addCleanup(channel.on(...))`.
+
+### Warning
+3. **Auto-reconnect config** — Review static overrides (`RECONNECT_DELAY`, `MAX_RECONNECT_DELAY`, `MAX_RECONNECT_ATTEMPTS`) for production suitability.
+4. **`pipeChannel()` for Collection bridging** — When a Channel event should upsert into a Collection, use `pipeChannel(channel, event, collection)` instead of manual `listenTo` + `upsert`.
+
+---
+
+## Composable Helper Checks (5)
+
+### Critical
+1. **Correct ownership** — Sorting, Pagination, Selection belong on ViewModel. Pending belongs on singleton Resource (survives unmount).
+2. **No `init()` on helpers** — Helpers are plain classes with `subscribe()`. They don't need lifecycle management.
+
+### Warning
+3. **`apply()` in getters** — Helpers should be composed via `apply()` in getter pipelines: `pagination.apply(sorting.apply(filtered))`.
+4. **Feed uses `setResult()` with Resource** — When items live in a Resource, Feed tracks only cursor/hasMore via `setResult()`. Use `appendPage()` only for component-scoped item accumulation.
+5. **No `disposeSignal` in Pending execute** — Pending's `enqueue` callback receives its own signal. Do not pass `vm.disposeSignal` (would abort on component unmount).
+
+---
+
 ## Test Checks (5)
 
 ### Critical

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

@@ -7,7 +7,7 @@ invocable_by:
 user_instructions: |
   Usage: /mvc-kit:scaffold <type> <Name>
 
-  Types: viewmodel, model, collection, service, eventbus, channel, controller, page-component
+  Types: viewmodel, model, collection, persistent-collection, resource, service, eventbus, channel, controller, page-component
 
   Examples:
     /mvc-kit:scaffold viewmodel OrderList
@@ -34,6 +34,8 @@ Parse `$ARGUMENTS` as `<type> <Name>` (case-insensitive type, PascalCase Name).
 | `viewmodel` | `templates/viewmodel.md` | `{{Name}}ViewModel.ts`, `{{Name}}ViewModel.test.ts` |
 | `model` | `templates/model.md` | `{{Name}}Model.ts`, `{{Name}}Model.test.ts` |
 | `collection` | `templates/collection.md` | `{{Name}}Collection.ts` |
+| `persistent-collection` | `templates/persistent-collection.md` | `{{Name}}Collection.ts` |
+| `resource` | `templates/resource.md` | `{{Name}}Resource.ts`, `{{Name}}Resource.test.ts` |
 | `service` | `templates/service.md` | `{{Name}}Service.ts`, `{{Name}}Service.test.ts` |
 | `eventbus` | `templates/eventbus.md` | `{{Name}}EventBus.ts` |
 | `channel` | `templates/channel.md` | `{{Name}}Channel.ts` |
@@ -45,7 +47,8 @@ Parse `$ARGUMENTS` as `<type> <Name>` (case-insensitive type, PascalCase Name).
 - Follow the ViewModel section order: Private fields → Computed getters → Lifecycle → Actions → Setters.
 - State interfaces hold only source-of-truth values. No derived values, no loading/error flags.
 - Services are stateless, accept `AbortSignal`, throw `HttpError`.
-- Collections are thin subclasses — no custom methods.
+- Collections are thin subclasses — no custom methods. PersistentCollection subclasses set `storageKey` and optional static config.
+- Resources are thin subclasses with async methods for CRUD — use inherited Collection mutations.
 - Use `singleton()` for dependency resolution in ViewModels.
 - Getters read from collections directly — auto-tracking handles reactivity. Use `subscribeTo()` only for imperative side effects.
 - Pass `this.disposeSignal` to every async call.

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

@@ -0,0 +1,111 @@
+# PersistentCollection Template: {{Name}}
+
+Ask the user which storage adapter to use if not specified:
+- **WebStorageCollection** (`mvc-kit/web`) — localStorage/sessionStorage, auto-hydrates
+- **IndexedDBCollection** (`mvc-kit/web`) — IndexedDB per-item storage, requires `hydrate()`
+- **NativeCollection** (`mvc-kit/react-native`) — configurable async backend, requires `hydrate()`
+
+## {{Name}}Collection.ts
+
+### WebStorageCollection variant
+
+```typescript
+import { WebStorageCollection } from 'mvc-kit/web';
+
+export interface {{Name}}Item {
+  id: string;
+  // TODO: Add your fields
+}
+
+export class {{Name}}Collection extends WebStorageCollection<{{Name}}Item> {
+  protected readonly storageKey = 'TODO_set_storage_key';
+
+  // Override for custom storage type (default: 'local')
+  // static STORAGE: 'local' | 'session' = 'session';
+
+  // Override for debounced writes (default: 0 = immediate)
+  // static WRITE_DELAY = 300;
+}
+```
+
+### IndexedDBCollection variant
+
+```typescript
+import { IndexedDBCollection } from 'mvc-kit/web';
+
+export interface {{Name}}Item {
+  id: string;
+  // TODO: Add your fields
+}
+
+export class {{Name}}Collection extends IndexedDBCollection<{{Name}}Item> {
+  protected readonly storageKey = 'TODO_set_storage_key';
+
+  // Override for custom database name (default: 'mvc-kit')
+  // static DB_NAME = 'my-app';
+
+  // Override for debounced writes (default: 0 = immediate)
+  // static WRITE_DELAY = 300;
+}
+```
+
+### NativeCollection variant
+
+```typescript
+import { NativeCollection } from 'mvc-kit/react-native';
+
+export interface {{Name}}Item {
+  id: string;
+  // TODO: Add your fields
+}
+
+export class {{Name}}Collection extends NativeCollection<{{Name}}Item> {
+  protected readonly storageKey = 'TODO_set_storage_key';
+
+  // Override for debounced writes (default: 0 = immediate)
+  // static WRITE_DELAY = 300;
+}
+```
+
+## Rules
+
+- **Generate only the variant the user selected** — do not output all three.
+- **Thin subclass** — only set `storageKey` and optional static config. No custom methods.
+- **Persist entity caches** — users, todos, settings, cart. NOT ephemeral UI state (search results, selections).
+- **WebStorageCollection auto-hydrates** — no `hydrate()` call needed. localStorage blocks main thread, so avoid high-churn data.
+- **IndexedDB/Native require `hydrate()`** — call `await collection.hydrate()` in ViewModel `onInit()` before accessing data.
+- **Serialization hooks** — override `serialize(items)` and `deserialize(raw)` for custom encoding (default: JSON).
+- **Error hook** — override `onPersistError(error)` for custom error handling.
+
+## Usage in a ViewModel
+
+```typescript
+import { ViewModel, singleton } from 'mvc-kit';
+import { {{Name}}Collection, {{Name}}Item } from '../collections/{{Name}}Collection';
+
+class {{Name}}ViewModel extends ViewModel<{ filter: string }> {
+  private collection = singleton({{Name}}Collection);
+
+  get items(): {{Name}}Item[] {
+    return this.collection.items as {{Name}}Item[];
+  }
+
+  // Required for async adapters (IndexedDB, NativeCollection):
+  protected async onInit() {
+    await this.collection.hydrate();
+    if (this.collection.length === 0) this.load();
+  }
+
+  // For WebStorageCollection, hydrate() is not needed:
+  // protected onInit() {
+  //   if (this.collection.length === 0) this.load();
+  // }
+
+  async load() {
+    // const data = await this.service.getAll(this.disposeSignal);
+    // this.collection.reset(data);
+  }
+
+  setFilter(filter: string) { this.set({ filter }); }
+}
+```

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

@@ -0,0 +1,129 @@
+# Resource Template: {{Name}}
+
+## {{Name}}Resource.ts
+
+```typescript
+import { Resource, singleton, HttpError } from 'mvc-kit';
+// import { {{Name}}Service } from '../services/{{Name}}Service';
+
+export interface {{Name}}Item {
+  id: string;
+  // TODO: Add your fields
+}
+
+export class {{Name}}Resource extends Resource<{{Name}}Item> {
+  // private api = singleton({{Name}}Service);
+
+  // --- Lifecycle ---
+  protected onInit() {
+    if (this.length === 0) this.loadAll();
+  }
+
+  // --- Actions ---
+  async loadAll() {
+    // const data = await this.api.getAll(this.disposeSignal);
+    // this.reset(data);
+    // TODO: implement data loading
+  }
+
+  async loadById(id: string) {
+    // const item = await this.api.getById(id, this.disposeSignal);
+    // this.upsert(item);
+    // TODO: implement single-item loading
+  }
+
+  async save(item: Omit<{{Name}}Item, 'id'>) {
+    // const created = await this.api.create(item, this.disposeSignal);
+    // this.add(created);
+    // return created;
+    // TODO: implement create
+  }
+
+  async deleteItem(id: string) {
+    // this.optimistic(() => this.remove(id));
+    // await this.api.delete(id, this.disposeSignal);
+    // TODO: implement delete
+  }
+
+  protected override onDispose() {
+    // Dispose any owned helpers (e.g., Pending) here
+  }
+}
+```
+
+## {{Name}}Resource.test.ts
+
+```typescript
+import { describe, test, expect, beforeEach } from 'vitest';
+import { teardownAll, singleton } from 'mvc-kit';
+import { {{Name}}Resource } from './{{Name}}Resource';
+
+beforeEach(() => teardownAll());
+
+describe('{{Name}}Resource', () => {
+  test('starts empty', () => {
+    const resource = singleton({{Name}}Resource);
+    expect(resource.length).toBe(0);
+    expect(resource.items).toEqual([]);
+  });
+
+  test('loadAll populates items', async () => {
+    // TODO: set up API mocks BEFORE init() — onInit() triggers loadAll()
+    // vi.spyOn(service, 'getAll').mockResolvedValue([{ id: '1' }, { id: '2' }]);
+
+    const resource = singleton({{Name}}Resource);
+    resource.init();
+
+    // await vi.waitFor(() => expect(resource.items).toHaveLength(2));
+  });
+
+  test('async tracking reports loading state', async () => {
+    const resource = singleton({{Name}}Resource);
+    resource.init();
+
+    expect(resource.async.loadAll.loading).toBe(false);
+    expect(resource.async.loadAll.error).toBeNull();
+  });
+});
+```
+
+## Rules
+
+- **Singleton** — access via `singleton({{Name}}Resource)` from ViewModels
+- **Thin subclass** — define async methods for CRUD; use inherited Collection mutations (`reset`, `upsert`, `add`, `update`, `remove`)
+- **Eliminates boilerplate** — replaces empty Collection subclass + Service + manual cache check pattern
+- **Async tracking** — each method gets independent `resource.async.methodName` tracking after `init()`
+- **Skip Service if you have a typed API client** — call RPC/tRPC/GraphQL codegen directly from Resource
+- **Use Service only** when wrapping raw `fetch()` with `HttpError`, composing calls, or managing auth/retries
+- **External Collection injection** — pass a shared Collection to the constructor when Resource + Channel feed the same store
+
+## Usage in a ViewModel
+
+```typescript
+import { ViewModel, singleton } from 'mvc-kit';
+import { {{Name}}Resource, {{Name}}Item } from '../resources/{{Name}}Resource';
+
+class {{Name}}ViewModel extends ViewModel<{ search: string }> {
+  private resource = singleton({{Name}}Resource);
+
+  // Getter reads from resource — auto-tracked
+  get items(): {{Name}}Item[] {
+    return this.resource.items as {{Name}}Item[];
+  }
+
+  get filtered(): {{Name}}Item[] {
+    const { search } = this.state;
+    if (!search) return this.items;
+    const q = search.toLowerCase();
+    return this.items.filter(item =>
+      JSON.stringify(item).toLowerCase().includes(q),
+    );
+  }
+
+  protected onInit() {
+    // Resource handles its own init via singleton — just read from it
+  }
+
+  setSearch(search: string) { this.set({ search }); }
+}
+```

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

@@ -289,18 +289,45 @@ test('example', () => {
 - `addCleanup` for `channel.on()`/`bus.on()` subscriptions → use `listenTo()` (auto-cleanup on dispose and reset)
 - Missing `hydrate()` for async adapters (IndexedDB, NativeCollection) → call `hydrate()` in `onInit()` before accessing data
 
+## Resource Pattern
+
+```typescript
+class UsersResource extends Resource<User> {
+  private api = singleton(UserService);
+
+  async loadAll() {
+    const data = await this.api.getAll(this.disposeSignal);
+    this.reset(data);
+  }
+}
+// ViewModel reads from Resource via getter -- auto-tracked
+class UsersVM extends ViewModel<{ search: string }> {
+  private users = singleton(UsersResource);
+  get items() { return this.users.items as User[]; }
+}
+```
+
+**Resource vs Collection + Service:** Resource eliminates boilerplate (empty Collection subclass + Service + manual cache check). Use Resource when you need a shared data cache with API loading. Use Collection + Service only when the Collection is shared across multiple Resources/Channels.
+
+## PersistentCollection Lifecycle
+
+- **WebStorageCollection** -- auto-hydrates, no `hydrate()` needed. Avoid for high-churn data.
+- **IndexedDBCollection / NativeCollection** -- require `await collection.hydrate()` in ViewModel `onInit()` before accessing data.
+
 ## Decision Framework
 
 - Holds UI state for a component → **ViewModel**
 - Single entity with validation → **Model**
-- List of entities with CRUD → **Collection**
+- List of entities with CRUD (no API) → **Collection**
+- List + API loading + async tracking → **Resource** (replaces Collection + Service + cache check)
+- Need persistence across page refresh → **PersistentCollection** (WebStorage, IndexedDB, NativeCollection)
 - Wraps raw `fetch()` with error handling → **Service** (skip if you have a typed API client)
 - Cross-cutting events → **EventBus**
 - Persistent connection → **Channel**
 - Coordinates multiple ViewModels → **Controller** (rare)
 - Sort/paginate/select on a list → **Sorting/Pagination/Selection** helpers
 - Cursor-based server pagination → **Feed** helper
-- Per-item operation retry with status → **Pending** helper (on Resource)
+- Per-item operation retry with status → **Pending** helper (on Resource, not ViewModel)
 - Unstyled table/list/infinite scroll → **DataTable/CardList/InfiniteScroll** components
 
 ## Dev Mode

package/agent-config/cursor/cursorrules

@@ -289,18 +289,45 @@ test('example', () => {
 - `addCleanup` for `channel.on()`/`bus.on()` subscriptions → use `listenTo()` (auto-cleanup on dispose and reset)
 - Missing `hydrate()` for async adapters (IndexedDB, NativeCollection) → call `hydrate()` in `onInit()` before accessing data
 
+## Resource Pattern
+
+```typescript
+class UsersResource extends Resource<User> {
+  private api = singleton(UserService);
+
+  async loadAll() {
+    const data = await this.api.getAll(this.disposeSignal);
+    this.reset(data);
+  }
+}
+// ViewModel reads from Resource via getter — auto-tracked
+class UsersVM extends ViewModel<{ search: string }> {
+  private users = singleton(UsersResource);
+  get items() { return this.users.items as User[]; }
+}
+```
+
+**Resource vs Collection + Service:** Resource eliminates boilerplate (empty Collection subclass + Service + manual cache check). Use Resource when you need a shared data cache with API loading. Use Collection + Service only when the Collection is shared across multiple Resources/Channels.
+
+## PersistentCollection Lifecycle
+
+- **WebStorageCollection** — auto-hydrates, no `hydrate()` needed. Avoid for high-churn data.
+- **IndexedDBCollection / NativeCollection** — require `await collection.hydrate()` in ViewModel `onInit()` before accessing data.
+
 ## Decision Framework
 
 - Holds UI state for a component → **ViewModel**
 - Single entity with validation → **Model**
-- List of entities with CRUD → **Collection**
+- List of entities with CRUD (no API) → **Collection**
+- List + API loading + async tracking → **Resource** (replaces Collection + Service + cache check)
+- Need persistence across page refresh → **PersistentCollection** (WebStorage, IndexedDB, NativeCollection)
 - Wraps raw `fetch()` with error handling → **Service** (skip if you have a typed API client)
 - Cross-cutting events → **EventBus**
 - Persistent connection → **Channel**
 - Coordinates multiple ViewModels → **Controller** (rare)
 - Sort/paginate/select on a list → **Sorting/Pagination/Selection** helpers
 - Cursor-based server pagination → **Feed** helper
-- Per-item operation retry with status → **Pending** helper (on Resource)
+- Per-item operation retry with status → **Pending** helper (on Resource, not ViewModel)
 - Unstyled table/list/infinite scroll → **DataTable/CardList/InfiniteScroll** components
 
 ## Dev Mode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mvc-kit",
-  "version": "2.10.1",
+  "version": "2.11.0",
   "description": "Zero-magic, class-based reactive ViewModel library",
   "type": "module",
   "main": "./dist/mvc-kit.cjs",