mvc-kit 2.8.0 → 2.9.0

package/README.md

@@ -782,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 |
@@ -829,6 +838,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 +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**
 
@@ -885,6 +906,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

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
+// 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

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/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, 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';
 ```
@@ -160,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
@@ -236,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
 
@@ -246,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, 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';
 ```
@@ -160,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
@@ -236,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
 
@@ -246,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/dist/Collection.cjs

@@ -134,6 +134,33 @@ class Collection {
       throw new Error("Cannot upsert on disposed Collection");
     }
     if (items.length === 0) return;
+    if (items.length === 1) {
+      const item = items[0];
+      const existing = this._index.get(item.id);
+      if (existing) {
+        if (existing === item) return;
+        const prev2 = this._items;
+        const idx = this._items.indexOf(existing);
+        const newItems = [...prev2];
+        newItems[idx] = item;
+        this._index.set(item.id, item);
+        if (this._timestamps) this._timestamps.set(item.id, Date.now());
+        this._items = freeze(newItems);
+        this.notify(prev2);
+      } else {
+        const prev2 = this._items;
+        let result2 = [...prev2, item];
+        this._index.set(item.id, item);
+        if (this._timestamps) this._timestamps.set(item.id, Date.now());
+        if (this._maxSize > 0 && result2.length > this._maxSize) {
+          result2 = this._evictForCapacity(result2);
+        }
+        this._items = freeze(result2);
+        this.notify(prev2);
+        this._scheduleEvictionTimer();
+      }
+      return;
+    }
     const incoming = /* @__PURE__ */ new Map();
     for (const item of items) {
       incoming.set(item.id, item);
@@ -186,6 +213,17 @@ class Collection {
     if (ids.length === 0) {
       return;
     }
+    if (ids.length === 1) {
+      const id = ids[0];
+      if (!this._index.has(id)) return;
+      const prev2 = this._items;
+      this._items = freeze(prev2.filter((item) => item.id !== id));
+      this._index.delete(id);
+      this._timestamps?.delete(id);
+      this.notify(prev2);
+      this._scheduleEvictionTimer();
+      return;
+    }
     const idSet = new Set(ids);
     const filtered = this._items.filter((item) => !idSet.has(item.id));
     if (filtered.length === this._items.length) {