mvc-kit 2.8.0 → 2.10.0

package/README.md

@@ -782,6 +782,16 @@ 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 |
+| `Pending<K, Meta?>` | Per-item operation queue with retry + status tracking + optional typed metadata |
+
 ### Interfaces
 
 | Interface | Description |
@@ -829,6 +839,14 @@ function App() {
 | `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()`
@@ -873,6 +891,11 @@ 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 |
+| [Pending](src/Pending.md) | Per-item operation queue with retry + status tracking |
 
 **React Hooks**
 
@@ -885,6 +908,14 @@ Each core class and React hook has a dedicated reference doc with full API detai
 | [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/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
@@ -486,3 +486,67 @@ class VM extends ViewModel {
   }
 }
 ```
+
+---
+
+## 22. Pending as a ViewModel Property
+
+```typescript
+// BAD — Pending dies on component unmount, losing in-flight retries
+class ItemsVM extends ViewModel {
+  readonly pending = new Pending<string>();
+  // ...
+}
+
+// GOOD — Pending lives on the singleton Resource
+class ItemsResource extends Resource<Item> {
+  readonly pending = new Pending<string>();
+}
+class ItemsVM extends ViewModel {
+  private resource = singleton(ItemsResource);
+  get pending() { return this.resource.pending; }
+}
+```
+
+---
+
+## 23. Passing disposeSignal to Pending's Execute Callback
+
+```typescript
+// BAD — aborts operation when component unmounts, defeating resilience
+this.pending.enqueue(id, 'delete', async () => {
+  await api.deleteItem(id, this.disposeSignal); // component unmount aborts!
+});
+
+// GOOD — use the signal from Pending (aborted only on cancel/supersede/dispose)
+this.pending.enqueue(id, 'delete', async (signal) => {
+  await api.deleteItem(id, signal);
+});
+```
+
+---
+
+## 24. Using collection.optimistic() Rollback with Pending
+
+```typescript
+// BAD — snapshot goes stale during retries
+async deleteItem(id: string) {
+  const rollback = this.collection.optimistic(() => this.remove(id));
+  this.pending.enqueue(id, 'delete', async (signal) => {
+    try {
+      await api.deleteItem(id, signal);
+    } catch (e) {
+      rollback(); // stale — other mutations may have happened during retries
+      throw e;
+    }
+  });
+}
+
+// GOOD — optimistic remove without rollback; let Pending manage failure UX
+async deleteItem(id: string) {
+  this.optimistic(() => this.remove(id));
+  this.pending.enqueue(id, 'delete', async (signal) => {
+    await api.deleteItem(id, signal);
+  });
+}
+```

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, 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';
 
-// React hooks
+// 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
@@ -157,7 +159,7 @@ Static overrides for auto-eviction (zero-cost when not configured):
 Abstract base for Collections that persist to external storage. Extends Collection with delta tracking, debounced writes, and hydration.
 
 ### Static Config
-- `static WRITE_DELAY = 100` — Debounce ms for storage writes. `0` = immediate.
+- `static WRITE_DELAY = 0` — Debounce ms for storage writes. `0` = immediate (default). Override to a positive value to coalesce rapid mutations.
 
 ### Public API
 - `hydrate(): Promise<T[]>` — Load from storage, idempotent. Returns items.
@@ -283,6 +285,172 @@ 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.
+
+### Pending\<K, Meta\>
+
+Per-item operation queue with retry and status tracking. Lives on singleton Resource, not component-scoped ViewModel. Optional `Meta` generic for typed UI metadata on each operation.
+
+```typescript
+new Pending<string>()                      // string keys, no metadata
+new Pending<number>()                      // numeric keys
+new Pending<string, { label: string }>()   // with typed metadata
+```
+
+- `getStatus(id: K): PendingOperation<Meta> | null` — Frozen snapshot of operation state (`active | retrying | failed`). Includes `meta: Meta | null`.
+- `has(id: K): boolean` — Whether an operation exists for the given ID.
+- `count: number` — Number of operations (all statuses).
+- `hasPending: boolean` — Whether any operations are in-flight (active or retrying). Excludes failed.
+- `hasFailed: boolean` — Whether any operations are in failed status.
+- `failedCount: number` — Number of failed operations.
+- `entries: readonly PendingEntry<K, Meta>[]` — All operations with ids. Cached, reference-stable between mutations. `PendingEntry` extends `PendingOperation<Meta>` with `readonly id: K`.
+- `enqueue(id, operation, execute, meta?): void` — Fire-and-forget. Supersedes existing operation for same ID. Optional `meta` attached to snapshot.
+- `retry(id: K): void` — Re-process a failed operation. Resets attempts to 0.
+- `retryAll(): void` — Retry all failed operations.
+- `cancel(id: K): void` — Abort signal, clear timer, remove operation.
+- `cancelAll(): void` — Cancel all operations.
+- `dismiss(id: K): void` — Remove a failed operation without retrying.
+- `dismissAll(): void` — Remove all failed operations. Single notification.
+- `subscribe(listener): () => void` — Auto-tracked by ViewModel.
+- `dispose(): void` — Cancel all operations, clear listeners.
+
+Static config (override via subclass): `MAX_RETRIES=5`, `RETRY_BASE=1000`, `RETRY_MAX=30000`, `RETRY_FACTOR=2`.
+
+Overridable hooks: `isRetryable(error)`, `onConfirmed(id, operation)`, `onFailed(id, operation, error)`.
+
+---
+
+## 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

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

@@ -65,6 +65,8 @@ setTypeFilter(typeFilter: State['typeFilter']) { this.set({ typeFilter }); }
 
 The setter changes state → React re-renders → getters recompute. No manual refiltering needed.
 
+All classes auto-bind methods, so they can be passed point-free as callbacks (`onFoo={vm.foo}`, `onClick={sorting.toggle}`, `onSubmit={model.commit}`).
+
 ---
 
 ## Encapsulating Collections
@@ -229,6 +231,162 @@ 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);
+  }
+}
+```
+
+### Pending Pattern (resilient optimistic updates)
+
+Pending lives on the singleton Resource so operations survive component unmount:
+
+```typescript
+class ItemsResource extends Resource<Item> {
+  readonly pending = new Pending<string>();
+
+  async deleteItem(id: string) {
+    this.optimistic(() => this.remove(id));
+    this.pending.enqueue(id, 'delete', async (signal) => {
+      await api.deleteItem(id, signal);
+    });
+  }
+
+  protected override onDispose() {
+    this.pending.dispose();
+  }
+}
+
+class ItemsVM extends ViewModel<{ filter: string }> {
+  private resource = singleton(ItemsResource);
+
+  get pending() { return this.resource.pending; }
+  get items() { return this.resource.items; }
+
+  deleteItem(id: string) { this.resource.deleteItem(id); }
+  retryFailed() { this.resource.pending.retryAll(); }
+}
+```
+
+**Key points:**
+- Pending uses the signal from `enqueue`'s callback — do not pass `vm.disposeSignal`.
+- Retries automatically on network, timeout, and server errors. Fails immediately on 4xx.
+- Override `isRetryable()` in a subclass to customize retry logic.
+
+### 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/copilot/copilot-instructions.md

@@ -15,13 +15,28 @@ 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 |
+| `Pending<K, Meta?>` | Per-item operation queue with retry + status tracking + optional typed metadata | Resource 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, Pending } from 'mvc-kit';
 import { singleton, teardownAll, HttpError, isAbortError, classifyError } from 'mvc-kit';
 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';
 ```
@@ -83,6 +98,8 @@ class ItemsViewModel extends ViewModel<ItemState> {
 
 **Section order:** Private fields → Computed getters → Lifecycle → Actions → Setters.
 
+All classes auto-bind methods — safe to pass point-free as callbacks (`onFoo={vm.foo}`, `onClick={sorting.toggle}`).
+
 ## Component Pattern
 
 ```tsx
@@ -160,6 +177,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
@@ -236,6 +286,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
 
@@ -246,6 +298,10 @@ 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
+- Per-item operation retry with status → **Pending** helper (on Resource)
+- Unstyled table/list/infinite scroll → **DataTable/CardList/InfiniteScroll** components
 
 ## Dev Mode