mvc-kit 2.7.1 → 2.9.0

package/README.md

@@ -666,6 +666,22 @@ function UserForm() {
 }
 ```
 
+#### `useModelRef(factory)`
+
+Create component-scoped Model with lifecycle management (init + dispose) but **no subscription**. The parent never re-renders from model state changes. Use with `useField` for per-field isolation in large forms.
+
+```tsx
+function UserForm() {
+  const model = useModelRef(() => new UserModel({ name: '', email: '' }));
+  return (
+    <form>
+      <NameField model={model} />
+      <FormActions model={model} />
+    </form>
+  );
+}
+```
+
 #### `useField(model, key)`
 
 Subscribe to a single field with surgical re-renders. The returned `set()` calls the Model's `set()` directly — use custom setter methods on the Model for any logic beyond simple assignment.
@@ -766,6 +782,15 @@ function App() {
 | `Service` | Non-reactive infrastructure service (Disposable) |
 | `EventBus<E>` | Typed pub/sub event bus |
 
+### Composable Helpers
+
+| Class | Description |
+|-------|-------------|
+| `Sorting<T>` | Multi-column sort state with 3-click toggle cycle and `apply()` pipeline |
+| `Pagination` | Page/pageSize state with `apply()` slicing |
+| `Selection<K>` | Key-based selection set with toggle/select-all semantics |
+| `Feed<T>` | Cursor + hasMore + item accumulation for server-side pagination |
+
 ### Interfaces
 
 | Interface | Description |
@@ -806,12 +831,21 @@ function App() {
 | `useLocal(Class \| factory, ...args)` | Component-scoped, auto-disposed, auto-init |
 | `useSingleton(Class, ...args)` | Singleton, registry-managed, auto-init |
 | `useModel(factory)` | Model with validation/dirty state, auto-init |
+| `useModelRef(factory)` | Model lifecycle only (no subscription). For per-field forms. |
 | `useField(model, key)` | Single field subscription |
 | `useEvent(source, event, handler)` | Subscribe to EventBus or ViewModel event |
 | `useEmit(bus)` | Get stable emit function |
 | `useResolve(Class, ...args)` | Resolve from Provider or singleton |
 | `useTeardown(...Classes)` | Teardown singletons on unmount |
 
+### Headless React Components
+
+| Component | Description |
+|-----------|-------------|
+| `DataTable<T>` | Unstyled table with sort headers, selection checkboxes, pagination slots; accepts helper instances directly |
+| `CardList<T>` | Unstyled list/grid with render-prop items |
+| `InfiniteScroll` | IntersectionObserver wrapper for infinite loading; `direction="up"` for chat UIs |
+
 ## Behavior Notes
 
 - State is always shallow-frozen with `Object.freeze()`
@@ -856,6 +890,10 @@ Each core class and React hook has a dedicated reference doc with full API detai
 | [EventBus](src/EventBus.md) | Typed pub/sub for cross-cutting event communication |
 | [Channel](src/Channel.md) | Persistent connections (WebSocket, SSE) with auto-reconnect |
 | [Singleton Registry](src/singleton.md) | Global instance management: `singleton()`, `teardown()`, `teardownAll()` |
+| [Sorting](src/Sorting.md) | Multi-column sort state with 3-click toggle cycle and apply pipeline |
+| [Pagination](src/Pagination.md) | Page/pageSize state with array slicing |
+| [Selection](src/Selection.md) | Key-based selection set with toggle/select-all |
+| [Feed](src/Feed.md) | Cursor + hasMore + item accumulation for server-side pagination |
 
 **React Hooks**
 
@@ -864,10 +902,18 @@ Each core class and React hook has a dedicated reference doc with full API detai
 | [useLocal](src/react/use-local.md) | Component-scoped instance, auto-init/dispose, deps array for recreate |
 | [useInstance](src/react/use-instance.md) | Subscribe to an existing Subscribable (no lifecycle management) |
 | [useSingleton](src/react/use-singleton.md) | Singleton resolution with auto-init and shared state |
-| [useModel & useField](src/react/use-model.md) | Model binding with validation/dirty state; surgical per-field subscriptions |
+| [useModel, useModelRef & useField](src/react/use-model.md) | Model binding with validation/dirty state; lifecycle-only ref; surgical per-field subscriptions |
 | [useEvent & useEmit](src/react/use-event-bus.md) | Subscribe to and emit typed events from EventBus or ViewModel |
 | [useTeardown](src/react/use-teardown.md) | Dispose singleton instances on component unmount |
 
+**Headless Components**
+
+| Doc | Description |
+|-----|-------------|
+| [DataTable](src/react/components/DataTable.md) | Unstyled table with sort, selection, pagination; accepts helpers directly |
+| [CardList](src/react/components/CardList.md) | Unstyled list/grid with render-prop items |
+| [InfiniteScroll](src/react/components/InfiniteScroll.md) | IntersectionObserver wrapper for infinite loading; `direction="up"` for chat UIs |
+
 ## Dev Mode (`__MVC_KIT_DEV__`)
 
 mvc-kit includes development-only safety checks guarded by the `__MVC_KIT_DEV__` flag. When enabled, these checks catch common mistakes at development time with clear `console.error` messages instead of silent infinite loops or hard-to-debug failures.

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

@@ -53,6 +53,7 @@ Private fields → Computed getters → Lifecycle → Actions → Setters
 | `useSingleton(Class, ...args)` | Singleton instance, shared state |
 | `useInstance(subscribable)` | Subscribe to existing instance |
 | `useModel(factory)` | Model with validation/dirty state |
+| `useModelRef(factory)` | Model lifecycle only, no subscription. For per-field forms. |
 | `useField(model, key)` | Single field subscription |
 | `useEvent(source, event, handler)` | Subscribe to EventBus or ViewModel event |
 | `useEmit(bus)` | Stable emit function |

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

@@ -433,7 +433,7 @@ async load() {
 
 ---
 
-## 18. Persisting Ephemeral UI State
+## 19. Persisting Ephemeral UI State
 
 ```typescript
 // BAD — persisting search results, selections, or high-churn data
@@ -451,7 +451,7 @@ Persistence adds I/O overhead on every mutation. For high-churn data, this cause
 
 ---
 
-## 19. Using addCleanup for channel.on()/bus.on() Subscriptions
+## 20. Using addCleanup for channel.on()/bus.on() Subscriptions
 
 ```typescript
 // BAD — manual addCleanup is easy to forget and not reset-safe
@@ -468,7 +468,7 @@ protected onInit() {
 
 ---
 
-## 20. Missing hydrate() for Async Adapters
+## 21. Missing hydrate() for Async Adapters
 
 ```typescript
 // BAD — accessing items before hydrate() on async adapter

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

@@ -5,12 +5,14 @@
 ```typescript
 // Core classes and utilities
 import { ViewModel, Model, Collection, PersistentCollection, Resource, Controller, Service, EventBus, Channel } from 'mvc-kit';
+import { Sorting, Pagination, Selection, Feed } 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';
 
-// React hooks
-import { useLocal, useSingleton, useInstance, useModel, useField, useEvent, useEmit, useResolve, useTeardown, Provider } from 'mvc-kit/react';
+// 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';
 
 // Web storage adapters
@@ -283,6 +285,141 @@ No state, no getters, no async tracking.
 
 ---
 
+## Composable Helpers
+
+Plain classes with `subscribe()` — auto-tracked when declared as ViewModel instance properties. Each has an `apply()` method that transforms arrays. Helpers manage state; ViewModels compose them in getters.
+
+### Sorting\<T\>
+
+Multi-column sort state with 3-click toggle cycle (asc → desc → none).
+
+```typescript
+new Sorting<User>({ sorts: [{ key: 'name', direction: 'asc' }] })
+```
+
+- `sorts: readonly SortDescriptor[]` — Current sort descriptors in priority order. Each: `{ key: string, direction: 'asc' | 'desc' }`.
+- `key: string | null` — Primary sort key (first descriptor), or null when empty.
+- `direction: 'asc' | 'desc'` — Primary sort direction. Defaults to `'asc'` when empty.
+- `isSorted(key: string): boolean` — Whether the given key is currently sorted.
+- `directionOf(key: string): 'asc' | 'desc' | null` — Sort direction for a key, or null.
+- `indexOf(key: string): number` — Priority index of a sorted key, or -1.
+- `toggle(key: string): void` — 3-click cycle: not sorted → asc → desc → removed.
+- `setSort(key: string, direction: 'asc' | 'desc'): void` — Replace all with a single sort.
+- `setSorts(sorts: SortDescriptor[]): void` — Replace all sort descriptors.
+- `reset(): void` — Clear all sorts.
+- `apply(items: T[], compareFn?): T[]` — Returns sorted copy. Optional custom comparator `(a, b, key, dir) => number`.
+- `subscribe(listener): () => void` — Auto-tracked by ViewModel.
+
+### Pagination
+
+Page/pageSize state with `apply()` slicing.
+
+```typescript
+new Pagination({ pageSize: 25 })
+```
+
+- `page: number` — Current page (1-based).
+- `pageSize: number` — Items per page.
+- `setPage(page: number): void` — Navigate to a specific page (clamped to >= 1).
+- `setPageSize(size: number): void` — Change page size, resets to page 1.
+- `nextPage(): void` — Advance to the next page.
+- `prevPage(): void` — Go back one page. No-op if already on page 1.
+- `hasNext(total: number): boolean` — Whether there is a next page.
+- `hasPrev(): boolean` — Whether there is a previous page.
+- `pageCount(total: number): number` — Compute total pages.
+- `reset(): void` — Reset to page 1.
+- `apply<T>(items: T[]): T[]` — Slice array to the current page window.
+- `subscribe(listener): () => void` — Auto-tracked by ViewModel.
+
+### Selection\<K\>
+
+Key-based selection set with toggle/select-all semantics.
+
+```typescript
+new Selection<string>()
+```
+
+- `selected: ReadonlySet<K>` — Current selection.
+- `count: number` — Number of selected items.
+- `hasSelection: boolean` — Whether any items are selected.
+- `isSelected(key: K): boolean` — Check if selected.
+- `toggle(key: K): void` — Add or remove.
+- `select(...keys: K[]): void` — Add to selection.
+- `deselect(...keys: K[]): void` — Remove from selection.
+- `toggleAll(allKeys: K[]): void` — If all selected, deselect all; otherwise select all.
+- `set(...keys: K[]): void` — Replace entire selection atomically. Single notification. No-op if unchanged.
+- `clear(): void` — Deselect all.
+- `selectedFrom<T>(items, keyOf): T[]` — Filter items to those whose key is selected.
+- `subscribe(listener): () => void` — Auto-tracked by ViewModel.
+
+### Feed\<T\>
+
+Cursor + hasMore + item accumulation for server-side cursor-based pagination.
+
+```typescript
+new Feed()           // untyped (cursor/hasMore only)
+new Feed<Message>()  // typed (with item accumulation)
+```
+
+- `cursor: string | null` — Current cursor for next page.
+- `hasMore: boolean` — Whether more pages exist.
+- `items: readonly T[]` — Accumulated items (from appendPage/prependPage).
+- `count: number` — Number of accumulated items.
+- `setResult(result): void` — Update cursor/hasMore only (does not affect items).
+- `appendPage(page: FeedPage<T>): void` — Append page items and update cursor/hasMore.
+- `prependPage(page: FeedPage<T>): void` — Prepend page items and update cursor/hasMore.
+- `push(...items: T[]): void` — Add items without affecting cursor/hasMore.
+- `filter(predicate: (item: T) => boolean): void` — Remove non-matching items. No-op if nothing filtered.
+- `replacePage(page: FeedPage<T>): void` — Replace all items and update cursor/hasMore atomically. Ideal for pull-to-refresh.
+- `reset(): void` — Clear cursor, items, set hasMore to true.
+- `subscribe(listener): () => void` — Auto-tracked by ViewModel.
+
+---
+
+## Headless React Components
+
+Unstyled render-prop components from `mvc-kit/react`. They render the output of ViewModel getters and helpers. Neither requires helpers — they work with any array. Helpers don't require components — they work with any rendering approach.
+
+### DataTable\<T\>
+
+Unstyled table with sort headers, selection checkboxes, and pagination slots. Accepts helper instances directly via duck-typing.
+
+```tsx
+<DataTable
+  items={vm.items}
+  columns={columns}
+  sort={vm.sorting}
+  selection={vm.selection}
+  pagination={vm.pagination}
+  paginationTotal={vm.filteredCount}
+/>
+```
+
+### CardList\<T\>
+
+Unstyled list/grid with render-prop items.
+
+```tsx
+<CardList items={vm.items} renderItem={(item) => <Card {...item} />} />
+```
+
+### InfiniteScroll
+
+IntersectionObserver wrapper that calls `onLoadMore` when the sentinel enters the viewport. Supports `direction="up"` for chat-style reverse scroll.
+
+```tsx
+<InfiniteScroll onLoadMore={() => vm.loadMore()} hasMore={vm.feed.hasMore} loading={vm.async.loadMore.loading}>
+  {vm.items.map(item => <Row key={item.id} {...item} />)}
+</InfiniteScroll>
+
+// Chat UI (reverse scroll)
+<InfiniteScroll onLoadMore={() => vm.loadOlder()} hasMore={vm.feed.hasMore} direction="up">
+  {vm.messages.map(msg => <MessageBubble key={msg.id} message={msg} />)}
+</InfiniteScroll>
+```
+
+---
+
 ## Singleton Registry
 
 ```typescript
@@ -343,6 +480,13 @@ Returns `ModelHandle: { state, errors, valid, dirty, model }`.
 const { state, errors, valid, dirty, model } = useModel(() => new UserModel({ name: '' }));
 ```
 
+### useModelRef(factory)
+Lifecycle-only (init + dispose), no subscription. Returns `M` directly. Use with `useField` for per-field isolation in large forms.
+```tsx
+const model = useModelRef(() => new FormModel({ name: '', email: '' }));
+// Pass model to children that use useField — parent never re-renders from model changes.
+```
+
 ### useField(model, key)
 Returns `FieldHandle: { value, error, set }`. Surgical re-renders.
 ```tsx

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

@@ -229,6 +229,126 @@ Thin subclass for singleton identity. No custom methods — query logic goes in
 
 ---
 
+## Composable Helpers Pattern
+
+Declare helpers as ViewModel instance properties. They have `subscribe()` so they're auto-tracked — getters that read them recompute when helper state changes.
+
+```typescript
+interface FilterState {
+  search: string;
+}
+
+class UsersListVM extends ViewModel<FilterState> {
+  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>();
+
+  // Getters compose helpers via apply()
+  get filtered(): User[] {
+    const { search } = this.state;
+    let result = this.users.items as User[];
+    if (search) {
+      const q = search.toLowerCase();
+      result = result.filter(u => u.name.toLowerCase().includes(q));
+    }
+    return result;
+  }
+
+  get items(): User[] {
+    return this.pagination.apply(this.sorting.apply(this.filtered));
+  }
+
+  get pageCount(): number {
+    return this.pagination.pageCount(this.filtered.length);
+  }
+
+  // --- Setters ---
+  setSearch(search: string) { this.set({ search }); }
+}
+```
+
+**Key points:**
+- 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.
+- `Feed<T>` is for server-side cursor pagination (cursor + hasMore + optional item accumulation), not client-side slicing.
+
+### Feed Pattern (cursor-based)
+
+With Resource (shared data cache):
+
+```typescript
+class FeedVM extends ViewModel {
+  private resource = singleton(PostsResource);
+  readonly feed = new Feed();
+
+  get items(): Post[] {
+    return this.resource.items as Post[];
+  }
+
+  async loadMore() {
+    const result = await this.api.getPosts(this.feed.cursor, this.disposeSignal);
+    this.resource.upsert(...result.items);
+    this.feed.setResult(result);
+  }
+
+  protected onInit() {
+    this.loadMore();
+  }
+}
+```
+
+With item accumulation (component-scoped):
+
+```typescript
+class MessageThreadVM extends ViewModel<{ draft: string }> {
+  readonly feed = new Feed<Message>();
+
+  get messages() { return this.feed.items; }
+
+  async loadConversation(id: string) {
+    this.feed.reset();
+    const page = await this.service.getMessages(id, this.disposeSignal);
+    this.feed.appendPage(page);
+  }
+
+  async loadOlder() {
+    if (!this.feed.hasMore) return;
+    const page = await this.service.getMessages(id, this.disposeSignal, { cursor: this.feed.cursor });
+    this.feed.appendPage(page);
+  }
+}
+```
+
+### Headless Components
+
+Pass helpers directly — DataTable duck-types their interfaces:
+
+```tsx
+function UsersPage() {
+  const [state, vm] = useLocal(UsersListVM, { search: '' });
+
+  return (
+    <div>
+      <input value={state.search} onChange={e => vm.setSearch(e.target.value)} />
+      <DataTable
+        items={vm.items}
+        columns={columns}
+        sort={vm.sorting}
+        selection={vm.selection}
+        pagination={vm.pagination}
+        paginationTotal={vm.filteredCount}
+      />
+    </div>
+  );
+}
+```
+
+Components and helpers are independent — use helpers without components, or components without helpers. InfiniteScroll supports `direction="up"` for chat-style reverse scroll.
+
+---
+
 ## Persistence Pattern
 
 ```typescript

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

@@ -79,8 +79,10 @@ describe('{{Name}}Model', () => {
 
 ## React Usage
 
+### Simple form (useModel)
+
 ```tsx
-import { useModel, useField } from 'mvc-kit/react';
+import { useModel } from 'mvc-kit/react';
 import { {{Name}}Model } from '../models/{{Name}}Model';
 
 function {{Name}}Form() {
@@ -100,3 +102,38 @@ function {{Name}}Form() {
   );
 }
 ```
+
+### Large form with per-field isolation (useModelRef + useField)
+
+```tsx
+import { useModelRef, useField, useInstance } from 'mvc-kit/react';
+import { {{Name}}Model } from '../models/{{Name}}Model';
+
+// Parent — creates model, never re-renders from field changes
+function {{Name}}Form() {
+  const model = useModelRef(() => new {{Name}}Model({ name: '' }));
+  return (
+    <form>
+      <NameField model={model} />
+      <FormActions model={model} />
+    </form>
+  );
+}
+
+// Per-field child — only re-renders when this field changes
+function NameField({ model }: { model: {{Name}}Model }) {
+  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>
+  );
+}
+
+// Submit button — subscribes to full model for valid/dirty
+function FormActions({ model }: { model: {{Name}}Model }) {
+  useInstance(model);
+  return <button disabled={!model.valid || !model.dirty}>Save</button>;
+}
+```

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

@@ -15,13 +15,27 @@ This project uses **mvc-kit**, a zero-dependency TypeScript-first reactive state
 | `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 |
+| `Sorting<T>` | Multi-column sort state with 3-click toggle cycle and `apply()` pipeline | ViewModel property |
+| `Pagination` | Page/pageSize state with `apply()` slicing | ViewModel property |
+| `Selection<K>` | Key-based selection set with toggle/select-all semantics | ViewModel property |
+| `Feed<T>` | Cursor + hasMore + item accumulation for server-side pagination | ViewModel property |
+
+## Headless React Components (`mvc-kit/react`)
+
+| Component | Description |
+|-----------|-------------|
+| `DataTable<T>` | Unstyled table with sort headers, selection checkboxes, pagination slots; accepts helpers directly |
+| `CardList<T>` | Unstyled list/grid with render-prop items |
+| `InfiniteScroll` | IntersectionObserver wrapper for infinite loading; `direction="up"` for chat UIs |
 
 ## Imports
 
 ```typescript
 import { ViewModel, Model, Collection, PersistentCollection, Resource, Controller, Service, EventBus, Channel } from 'mvc-kit';
+import { Sorting, Pagination, Selection, Feed } from 'mvc-kit';
 import { singleton, teardownAll, HttpError, isAbortError, classifyError } from 'mvc-kit';
-import { useLocal, useSingleton, useInstance, useModel, useField, useEvent, useEmit, useResolve, useTeardown, Provider } from 'mvc-kit/react';
+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 { WebStorageCollection, IndexedDBCollection } from 'mvc-kit/web';
 import { NativeCollection } from 'mvc-kit/react-native';
 ```
@@ -110,6 +124,7 @@ function ItemsPage() {
 | `useSingleton(Class, ...args)` | Singleton, shared state. Returns `[state, instance]`. |
 | `useInstance(subscribable)` | Subscribe to existing instance. Returns `state`. |
 | `useModel(factory)` | Model with `{ state, errors, valid, dirty, model }`. |
+| `useModelRef(factory)` | Model lifecycle only (no subscription). Returns `M`. For per-field forms. |
 | `useField(model, key)` | Single field: `{ value, error, set }`. |
 | `useEvent(source, event, handler)` | EventBus/ViewModel event subscription. |
 | `useEmit(bus)` | Stable emit function. |
@@ -159,6 +174,39 @@ class UserModel extends Model<UserFormState> {
 }
 ```
 
+## Composable Helpers Pattern
+
+Declare helpers as ViewModel instance properties. They have `subscribe()` so they're auto-tracked -- getters that read them recompute when helper state changes.
+
+```typescript
+class UsersListVM extends ViewModel<FilterState> {
+  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 } = this.state;
+    let result = this.users.items as User[];
+    if (search) {
+      const q = search.toLowerCase();
+      result = result.filter(u => u.name.toLowerCase().includes(q));
+    }
+    return result;
+  }
+
+  get items(): User[] {
+    return this.pagination.apply(this.sorting.apply(this.filtered));
+  }
+}
+```
+
+**Key points:**
+- Helpers are plain classes, not ViewModels -- no `init()` needed.
+- `apply()` is a pure pipeline -- chain in getters: `pagination.apply(sorting.apply(filtered))`.
+- `Feed<T>` is for server-side cursor pagination (cursor + hasMore + optional item accumulation), not client-side slicing.
+- Headless components (`DataTable`, `CardList`, `InfiniteScroll`) are optional -- helpers work with any rendering approach. DataTable accepts helpers directly via duck-typing (`sort={vm.sorting}`, `selection={vm.selection}`, `pagination={vm.pagination}`).
+
 ## Sharing Patterns
 
 1. **Pattern A** (default): Parent ViewModel passes props to presentational children
@@ -235,6 +283,8 @@ test('example', () => {
 - `reset()` for paginated/incremental loads → use `upsert()` to accumulate data
 - `useState`/`useMemo`/`useCallback` in connected components → ViewModel handles it
 - Pass-through Service wrapping a typed API client → call the client directly from Resource
+- `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
 
 ## Decision Framework
 
@@ -245,6 +295,9 @@ test('example', () => {
 - 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
+- Unstyled table/list/infinite scroll → **DataTable/CardList/InfiniteScroll** components
 
 ## Dev Mode
 

package/agent-config/cursor/cursorrules

@@ -15,13 +15,27 @@ This project uses **mvc-kit**, a zero-dependency TypeScript-first reactive state
 | `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 |
+| `Sorting<T>` | Multi-column sort state with 3-click toggle cycle and `apply()` pipeline | ViewModel property |
+| `Pagination` | Page/pageSize state with `apply()` slicing | ViewModel property |
+| `Selection<K>` | Key-based selection set with toggle/select-all semantics | ViewModel property |
+| `Feed<T>` | Cursor + hasMore + item accumulation for server-side pagination | ViewModel property |
+
+## Headless React Components (`mvc-kit/react`)
+
+| Component | Description |
+|-----------|-------------|
+| `DataTable<T>` | Unstyled table with sort headers, selection checkboxes, pagination slots; accepts helpers directly |
+| `CardList<T>` | Unstyled list/grid with render-prop items |
+| `InfiniteScroll` | IntersectionObserver wrapper for infinite loading; `direction="up"` for chat UIs |
 
 ## Imports
 
 ```typescript
 import { ViewModel, Model, Collection, PersistentCollection, Resource, Controller, Service, EventBus, Channel } from 'mvc-kit';
+import { Sorting, Pagination, Selection, Feed } from 'mvc-kit';
 import { singleton, teardownAll, HttpError, isAbortError, classifyError } from 'mvc-kit';
-import { useLocal, useSingleton, useInstance, useModel, useField, useEvent, useEmit, useResolve, useTeardown, Provider } from 'mvc-kit/react';
+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 { WebStorageCollection, IndexedDBCollection } from 'mvc-kit/web';
 import { NativeCollection } from 'mvc-kit/react-native';
 ```
@@ -110,6 +124,7 @@ function ItemsPage() {
 | `useSingleton(Class, ...args)` | Singleton, shared state. Returns `[state, instance]`. |
 | `useInstance(subscribable)` | Subscribe to existing instance. Returns `state`. |
 | `useModel(factory)` | Model with `{ state, errors, valid, dirty, model }`. |
+| `useModelRef(factory)` | Model lifecycle only (no subscription). Returns `M`. For per-field forms. |
 | `useField(model, key)` | Single field: `{ value, error, set }`. |
 | `useEvent(source, event, handler)` | EventBus/ViewModel event subscription. |
 | `useEmit(bus)` | Stable emit function. |
@@ -159,6 +174,39 @@ class UserModel extends Model<UserFormState> {
 }
 ```
 
+## Composable Helpers Pattern
+
+Declare helpers as ViewModel instance properties. They have `subscribe()` so they're auto-tracked — getters that read them recompute when helper state changes.
+
+```typescript
+class UsersListVM extends ViewModel<FilterState> {
+  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 } = this.state;
+    let result = this.users.items as User[];
+    if (search) {
+      const q = search.toLowerCase();
+      result = result.filter(u => u.name.toLowerCase().includes(q));
+    }
+    return result;
+  }
+
+  get items(): User[] {
+    return this.pagination.apply(this.sorting.apply(this.filtered));
+  }
+}
+```
+
+**Key points:**
+- Helpers are plain classes, not ViewModels — no `init()` needed.
+- `apply()` is a pure pipeline — chain in getters: `pagination.apply(sorting.apply(filtered))`.
+- `Feed<T>` is for server-side cursor pagination (cursor + hasMore + optional item accumulation), not client-side slicing.
+- Headless components (`DataTable`, `CardList`, `InfiniteScroll`) are optional — helpers work with any rendering approach. DataTable accepts helpers directly via duck-typing (`sort={vm.sorting}`, `selection={vm.selection}`, `pagination={vm.pagination}`).
+
 ## Sharing Patterns
 
 1. **Pattern A** (default): Parent ViewModel passes props to presentational children
@@ -235,6 +283,8 @@ test('example', () => {
 - `reset()` for paginated/incremental loads → use `upsert()` to accumulate data
 - `useState`/`useMemo`/`useCallback` in connected components → ViewModel handles it
 - Pass-through Service wrapping a typed API client → call the client directly from Resource
+- `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
 
 ## Decision Framework
 
@@ -245,6 +295,9 @@ test('example', () => {
 - 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
+- Unstyled table/list/infinite scroll → **DataTable/CardList/InfiniteScroll** components
 
 ## Dev Mode